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

​
Adding a Custom Agent

1

Open Settings

Click the gear icon in the left navigation rail to open Settings.
2

Go to CLI Agents

Select the CLI Agents category.
3

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

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)

​
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:
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.