> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness status

> See what a session's harness actually loaded and is doing: its context, plugins, skills, MCP servers, subagents, and workflows.

When an agent misbehaves, you need to know what its harness actually had: which plugins and skills it loaded, whether an MCP server connected, how full the context is, and which subagents are still running. paddock collects that state from inside the harness, in one shape for both harnesses, and gives it to you with the session's events.

## Where it comes from

* **At every turn's end**, while the harness still runs, paddock stores a snapshot as a `session.status` event, just before the turn's `turn.ended`. It is part of the session's history.
* **Between snapshots**, live changes, such as a subagent's progress, an MCP server finishing its start, or the context filling, arrive on the stream as `status.update` events. They are never stored or replayed; each carries whole sections, so the next one supersedes a missed one.

In the browser, the client SDK keeps the latest status for you in `harnessStatus`: the newest snapshot with every later update applied. It is `null` until the session's first turn has ended.

```tsx theme={null}
import { useSession } from "@paddock/react";

export function McpServers({ sessionId, token }: { sessionId: string; token: string }) {
  const { harnessStatus } = useSession(sessionId, { token });
  if (!harnessStatus) return <p>No status yet: it appears after the first turn.</p>;
  return (
    <ul>
      {harnessStatus.mcp.map((server) => (
        <li key={server.name}>
          {server.name}: {server.state} {server.error ?? ""} ({server.tools.length} tools)
        </li>
      ))}
    </ul>
  );
}
```

On your backend, read the latest snapshot from the session's events:

```go Go theme={null}
page, err := session.Events.List(ctx, paddock.EventList{
	Types: []paddock.EventType{paddock.EventSessionStatus},
	Limit: 1,
})
if err != nil {
	return err
}
for _, ev := range page.Data {
	ctxStatus := ev.SessionStatus.Context
	fmt.Printf("%s: %d of %d tokens\n", ctxStatus.Model, ctxStatus.UsedTokens, ctxStatus.WindowTokens)
}
```

```python Python theme={null}
from paddock import types

page = session.events.list(types=["session.status"], limit=1)
for event in page.data:
    if isinstance(event, types.SessionStatusEvent):
        context = event.status.context
        print(f"{context.model}: {context.used_tokens} of {context.window_tokens} tokens")
```

```ts TypeScript theme={null}
const page = await session.events.list({ types: ["session.status"], limit: 1 });
for (const event of page.data) {
  if (event.type === "session.status") {
    const { model, usedTokens, windowTokens } = event.status.context;
    console.log(`${model}: ${usedTokens} of ${windowTokens} tokens`);
  }
}
```

With neither `after` nor `before`, `events.list` returns the latest events, so a limit of 1 returns the newest snapshot.

## The sections

A status has six sections, in this order. Codex has no Workflows section.

| Section | Shows |
| - | - |
| **Context** | The model, its context window, the tokens in use and their percentage, and when the harness compacts. On Claude Code, what its `/context` command shows: usage by category (system prompt, tools, MCP tools, memory files, skills, messages), with the MCP tools, custom agents, memory files, and skills that take space. On Codex, what Codex reports: the last request's input, cached, output, and reasoning tokens, the conversation's total, and the instruction files it loaded |
| **Plugins** | Every plugin the harness knows, its scope, and whether it loaded |
| **Skills** | Every skill the harness loaded, and the plugin it came from or that it is built in |
| **MCP** | Every MCP server: `loaded`, `starting`, or `error` with the harness's message, and the tools it offers |
| **Subagents** | The subagent definitions the harness loaded, then its subagent runs: running, completed, failed, or stopped, with their tokens and tool uses |
| **Workflows** | Claude Code only: workflow definitions, then runs with their phase and agents done |

Each entry of Plugins, Skills, MCP, and the definitions carries a `scope` that says where the harness found it: `home` (the configuration paddock rendered from the agent), `project` (the session's working directory), `plugin` (contributed by a plugin, named in `plugin`), or `builtin` (shipped with the harness). It carries a `state`, `loaded`, `starting`, or `error`, and the harness's `error` message.

Context is marked `estimated` when the harness estimated counts locally instead of counting them; a section the harness does not report is `null`.

The status names no configuration values: no MCP URLs, headers, commands, or environment values.

## Status and configuration together

The status says what the harness made of the agent's configuration. Join it with the agent's capability entries by name to see both:

* An entry the agent has but the status lacks has not been loaded, or is still pending.
* A row is **pending** while the session's harness has not taken the entry's latest change: the entry's `generation` is above the generation of the session's latest `config.applied`. See [Capabilities](https://docs.paddock.build/guides/capabilities.md).
* A status entry of scope `home` that the agent no longer has was removed and is pending until the harness drops it.

The console's **Status** tab, in the Playground and on every session's page, shows exactly this join, and lets you install, disable, and remove plugins and MCP servers from it. See [Console](https://docs.paddock.build/platform/console.md).

## When there is no status

Nothing is collected while no harness runs: before a session's first turn, and while the agent sleeps, the latest stored snapshot stands. A turn whose harness had already exited has no snapshot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.