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

# Agents

> How Claude agents spawn, run, and track usage

When a task moves to **In Progress**, Claude Board spawns a Claude Code CLI process on your local machine. This is the "agent" — it reads your codebase, writes files, runs commands, and commits code.

## How Agents Spawn

<Steps>
  <Step title="Task enters In Progress" icon="play">
    The server builds a prompt from the task description, project [context snippets](/features/snippets), [prompt template](/features/prompt-templates), [role](/features/roles), and any [file attachments](/features/attachments).
  </Step>

  <Step title="Branch created" icon="code-branch">
    If git automation is enabled, a feature branch is created from the base branch (e.g., `feature/CB-101-add-auth`).
  </Step>

  <Step title="CLI process starts" icon="terminal">
    Claude Board runs `claude` with `--no-input` and the configured permission mode. The working directory is set to the project's configured path.
  </Step>

  <Step title="Streaming begins" icon="signal">
    All output is captured and streamed to connected clients via WebSocket. Logs are persisted to the database for [session replay](/features/session-replay).
  </Step>

  <Step title="Agent completes" icon="check">
    When the CLI exits, the task moves to **Testing** automatically. If [auto-test](/features/auto-test) is enabled, tests run before the transition.
  </Step>
</Steps>

## Token Tracking

Claude Board tracks token usage per task in real-time:

| Metric                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| **Input tokens**        | Tokens sent to Claude (prompt + context)                |
| **Output tokens**       | Tokens generated by Claude                              |
| **Cost estimate**       | Calculated from model pricing (Opus/Sonnet/Haiku rates) |
| **Cache read/creation** | Tokens served from or added to prompt cache             |

Usage updates are emitted via the `task:usage` WebSocket event and visible on the task card.

## Smart Timer

The task timer measures active agent time accurately:

| Event                                           | Timer       |
| ----------------------------------------------- | ----------- |
| Task enters In Progress                         | **Starts**  |
| Task moves to Testing (awaiting review)         | **Pauses**  |
| Task returns to In Progress (changes requested) | **Resumes** |
| Task moves to Done                              | **Stops**   |

<Info>The smart timer gives you an accurate picture of how long Claude actually spent coding, excluding review wait time.</Info>

## Concurrency

Run up to **5 agents** simultaneously. The [auto-queue](/features/queue) feature lets you set a concurrency limit per project.

| Agents  | Best for                                                                |
| ------- | ----------------------------------------------------------------------- |
| **1**   | Sequential tasks, simple projects                                       |
| **2–3** | Moderate parallelism with low conflict risk                             |
| **4–5** | Maximum throughput with [dependency management](/features/dependencies) |

<Warning>Running multiple agents on the same project can cause file conflicts. Use [task dependencies](/features/dependencies) to coordinate which files each agent touches. The [Live view](/features/orchestration) detects conflicts in real-time.</Warning>

## Agent Lifecycle Events

Each agent emits events that you can monitor:

| Event                 | When                                           |
| --------------------- | ---------------------------------------------- |
| `task:started`        | Agent process spawns                           |
| `task:output`         | Terminal output chunk                          |
| `task:usage`          | Token/cost update                              |
| `task:tool_call`      | Individual tool call (Read, Write, Edit, Bash) |
| `task:completed`      | Agent exits successfully                       |
| `task:failed`         | Agent exits with error                         |
| `agent:file_conflict` | Two agents access the same file                |

See [Events API](/api/events) for WebSocket subscription details.