> ## 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.

# Custom Agents

> Add any CLI tool as a CliDeck session type

Beyond the four built-in agents, you can add any CLI command as a session type in CliDeck.

## Adding a Custom Agent

<Steps>
  <Step title="Open Settings">
    Click the gear icon in the left navigation rail to open Settings.
  </Step>

  <Step title="Go to CLI Agents">
    Select the **CLI Agents** category.
  </Step>

  <Step title="Click Add Agent">
    At the bottom of the agent list, click **Add Agent**. You can pick from unused presets or choose **Custom** to start from scratch.
  </Step>

  <Step title="Configure the agent">
    Fill in the details:

    * **Name** — Display name in the session launcher
    * **Command** — The CLI command to run (e.g., `aider`, `continue`, `my-custom-script`)
    * **AI Agent** — Check this if the tool is an AI agent (enables resume options)
  </Step>
</Steps>

## Resume Support

If your custom agent supports session resume, you can configure it:

1. Check **AI Agent** to enable the resume section
2. Check **Supports session resume**
3. Enter the **Resume command** with `{{sessionId}}` as a placeholder

For example, if your agent resumes with `my-agent --continue SESSION_ID`:

```
my-agent --continue {{sessionId}}
```

CliDeck will substitute the captured session ID when resuming.

## Session ID Capture

For resume to work, CliDeck needs to know the session ID. There are two ways this can happen:

1. **Telemetry** — If your agent supports OpenTelemetry, enable telemetry in the agent settings. CliDeck will capture the session ID from OTLP log attributes.

2. **Output matching** — CliDeck can match a regex pattern against the agent's terminal output to find the session ID. The built-in presets use patterns like UUID format (`[0-9a-f]{8}-...-[0-9a-f]{12}`). You can set a custom pattern in the agent configuration.

## Plain Shell Sessions

The built-in **Shell** option launches a plain terminal (`/bin/zsh`) with no agent features. This is useful for running quick commands, checking git status, or anything else you'd normally do in a terminal.

Shell sessions don't have telemetry, resume, or status detection — they're just regular terminals inside CliDeck.