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

# Agent Overview

> How CliDeck integrates with CLI coding agents

CliDeck supports four CLI coding agents out of the box, plus any custom CLI tool you want to add.

## How It Works

Each agent runs in its own real terminal (PTY). CliDeck doesn't modify the agent, inject middleware, or intercept your commands. The agent thinks it's running in a normal terminal.

The intelligence comes from **telemetry** — lightweight signals the agent already emits (or can be configured to emit). CliDeck receives these signals locally and uses them to show you:

| What CliDeck Shows    | How It Knows                                                                      |
| --------------------- | --------------------------------------------------------------------------------- |
| Working / idle status | Telemetry events (Claude, Codex, Gemini) or I/O heuristics (Shell, custom agents) |
| Last message preview  | Reads terminal output buffer (output markers per agent)                           |
| Session ID for resume | Captured from telemetry logs or plugin events                                     |
| Notifications         | Detects working-to-idle transitions                                               |

<Note>
  CliDeck never reads what you type or what the agent writes back through telemetry. It sees event timing — not content.
</Note>

## Supported Agents

| Agent                              | Telemetry Method   | Auto-Setup | Resume               |
| ---------------------------------- | ------------------ | ---------- | -------------------- |
| [Claude Code](/agents/claude-code) | Hooks + OTLP       | One-click  | `claude --resume`    |
| [Codex](/agents/codex)             | OTLP (config file) | One-click  | `codex resume`       |
| [Gemini CLI](/agents/gemini-cli)   | OTLP (config file) | One-click  | `gemini --resume`    |
| [OpenCode](/agents/opencode)       | Plugin bridge      | One-click  | `opencode --session` |

## Telemetry Methods

**OTLP (OpenTelemetry)** — Claude Code, Codex, and Gemini CLI emit OpenTelemetry logs over HTTP. CliDeck runs a local OTLP receiver at `POST /v1/logs` on port 4000. When you launch an agent from CliDeck, it sets the right environment variables so the agent sends its logs to CliDeck.

**Plugin bridge** — OpenCode uses a JavaScript plugin that sends events to CliDeck over HTTP. This provides the same status and preview information as OTLP, just through a different mechanism.

## Working / Idle Detection

For **Claude Code, Codex, and Gemini CLI**, status is fully **telemetry-driven**. CliDeck reads the timing of telemetry events to know exactly when the agent starts processing and when it finishes — no guessing from terminal output.

| Agent                 | How status works                                                                                                 |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Claude Code           | `api_request` event → idle (confirmed after 1 second of output silence). Other events → working.                 |
| Codex                 | `codex.sse_event` → idle. Other events → working.                                                                |
| Gemini CLI            | `api_response` (main role) → idle. `api_request` / `model_routing` → working.                                    |
| OpenCode              | Explicit `busy`/`idle` status events through its plugin bridge.                                                  |
| Shell / custom agents | I/O heuristics — byte rates and burst timing. Working means output is flowing; idle means 2+ seconds of silence. |

Telemetry-driven status is faster and more reliable than I/O heuristics. It reflects what the agent is actually doing, not just whether text is appearing on screen.

## Adding More Agents

You can add any CLI tool as a session type. See [Custom Agents](/agents/custom-agents) for how to configure your own.