Supported Agents

Tempest supports multiple AI coding agents out of the box. This guide covers the exact CLI commands, configuration options, and integration details for each agent.

Agent Configuration System

Each agent in Tempest is defined by an AgentConfig object with the following properties:

Property	Description
`name`	Display name shown in the UI (e.g., “Claude Code”)
`hint`	CLI command to invoke the agent (e.g., “claude”)
`sessionIdArgs`	Flags passed on first spawn to establish a session (e.g., `["--session-id", "{UUID}"]`)
`resumeArgs`	Flags passed when reopening to resume a conversation (e.g., `["--resume", "{UUID}"]`)
`capturePattern`	Optional regex to extract session ID from PTY output (for agents that mint their own ID)
`captureResumeArgs`	Optional flags for resuming with a captured ID (e.g., `["-s", "{UUID}"]`)
`autoApproveArgs`	Optional flags appended when Auto-approve agent tool calls is enabled — skips all in-session permission prompts

The {UUID} placeholder is replaced by Tempest with the actual session or conversation UUID.

Claude Code

Display Name: Claude Code
CLI Command: claude
Resumable: Yes (by conversation ID)

Launch Command

First spawn:

claude --session-id <conversation-uuid>

Resuming a saved session:

claude --resume <conversation-uuid>

Configuration

Claude Code reads configuration from:

~/.claude directory (user home)
Environment variables (e.g., ANTHROPIC_API_KEY)
MCP configuration from .mcp.json in the project root (if Token Intelligence is enabled)

API Key Setup

Set your Claude API key via the Claude CLI:

claude configure

This stores credentials in ~/.claude/config.json so Tempest can access them.

Model Selection

Claude Code uses the model configured in your Claude CLI settings. To change the model:

claude config --model claude-3-5-sonnet-20241022

Tempest Integration

Session ID: Persisted as conversationId in localStorage
Work-Done Detection:
- Primary: OSC 9 notification signal at turn completion
- Secondary: Title-based detection (title starts with ✳ for idle, Unicode spinners for busy)
- Fallback: Quiet timer (5 seconds no output)
MCP Support: Enabled by default if Token Intelligence is configured
Tab Badge: Shows ”✳ Claude Code” title when idle
Auto-approve flag: --dangerously-skip-permissions — appended by default; disables all tool-call confirmation prompts

Troubleshooting

If Claude Code doesn’t launch:

Ensure claude is installed: which claude (macOS/Linux) or gcm claude (Windows)
Run claude configure to set up your API key
Test in a terminal: claude --help should print the help menu
Check that the API key is valid by running claude in the terminal

Gemini CLI

Display Name: Gemini CLI
CLI Command: gemini
Resumable: Yes (by conversation ID)

Launch Command

First spawn:

gemini --session-id <conversation-uuid>

Resuming a saved session:

gemini --resume <conversation-uuid>

Configuration

Gemini CLI reads configuration from:

~/.gemini directory (user home)
Environment variables (e.g., GOOGLE_API_KEY, GOOGLE_PALM_KEY)
MCP configuration from .gemini/settings.json in the project root (if Token Intelligence is enabled)

API Key Setup

Set your Google API key via the Gemini CLI:

gemini configure

Or set the environment variable:

export GOOGLE_API_KEY="your-api-key"

Model Selection

Gemini CLI uses the model configured in your settings. To change the model:

gemini config --model gemini-pro

Tempest Integration

Session ID: Persisted as conversationId in localStorage
Work-Done Detection:
- Primary: OSC 9 notification signal at turn completion
- Secondary: Title-based detection (title starts with ◇ for idle, ✦ or ✋ for busy)
- Fallback: Quiet timer (5 seconds no output)
MCP Support: Enabled if Token Intelligence is configured (writes to .gemini/settings.json)
Tab Badge: Shows title with busy/idle indicators
Auto-approve flag: --yolo — appended by default; puts Gemini CLI into full auto-approval mode

Troubleshooting

If Gemini CLI doesn’t launch:

Ensure gemini is installed: which gemini (macOS/Linux) or gcm gemini (Windows)
Run gemini configure to set up your API key
Test in a terminal: gemini --help should print the help menu
Check that the API key is valid by running gemini in the terminal

Opencode

Display Name: Opencode
CLI Command: opencode
Resumable: Yes (session ID captured from output)

Launch Command

First spawn:

opencode

Resuming a saved session:

opencode -s <captured-session-id>

Session ID Capture

Unlike Claude Code or Gemini CLI, Opencode does not accept a --session-id flag on first spawn. Instead, it prints a session ID to stdout when it starts. Tempest captures this ID using a regex pattern:

\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b

When a UUID is matched in the PTY output, it is extracted and stored for resumption.

Configuration

Opencode reads configuration from:

opencode.json or opencode.jsonc in the project root
Environment variables
MCP configuration under mcp.atlas in the config file (if Token Intelligence is enabled)

MCP Configuration (Atlas)

If Token Intelligence is enabled, Tempest writes:

{
  "mcp": {
    "atlas": {
      "type": "local",
      "command": ["node", "--liftoff-only", "<entry-path>", "--path", "<project-path>"],
      "enabled": true
    }
  }
}

Tempest Integration

Session ID: Captured from output on first spawn, then persisted as conversationId
Work-Done Detection: Uses standard heuristics (quiet timer, signal-based detection)
MCP Support: Writes to opencode.jsonc or opencode.json
Resume Behavior: Uses -s <captured-id> flag on reopening

Troubleshooting

If the session ID is not captured:

Check that Opencode prints a UUID to stdout on startup
Run Opencode in a terminal and look for UUID output: opencode
If Opencode prints a different ID format, the regex pattern in NewSessionMenu.tsx may need tuning
Check the Tempest logs (DevTools console) for capture errors

Copilot CLI

Display Name: Copilot CLI
CLI Command: gh copilot
Resumable: No (stateless)

Launch Command

gh copilot

Configuration

Copilot CLI reads configuration from:

GitHub CLI config (~/.config/gh/config.yml on macOS/Linux)
GitHub authentication token (use gh auth login to set up)

Authentication

Authenticate with GitHub:

gh auth login

Follow the prompts to log in. Tempest will use your authenticated GitHub session.

Tempest Integration

Session ID: Not persisted (stateless sessions)
Resumption: Not supported; each spawn creates a fresh session
Work-Done Detection: Uses heuristics and signal detection
Limitations: Copilot CLI is designed for one-off suggestions, not persistent conversations

Use Cases

Quick code suggestions
Testing command generation
One-off questions without conversation context

Cline

Display Name: Cline
CLI Command: cline
Resumable: No (stateless)

Launch Command

cline

Configuration

Cline reads configuration from:

~/.cline directory (user home)
Environment variables (model selection, API keys)
Project-level configuration files

API Key Setup

Set your Anthropic API key:

export ANTHROPIC_API_KEY="your-api-key"

Tempest Integration

Session ID: Not persisted
Resumption: Not supported; each spawn creates a fresh session
Work-Done Detection: Uses signal detection and heuristics
Model Support: Typically runs Claude models; configuration via environment

Troubleshooting

If Cline doesn’t launch:

Ensure cline is installed: which cline (macOS/Linux) or gcm cline (Windows)
Set your API key: export ANTHROPIC_API_KEY="your-key"
Test in a terminal: cline --help or cline to start a session

Cursor Agent

Display Name: Cursor Agent
CLI Command: cursor
Resumable: No (stateless)

Launch Command

cursor

Configuration

Cursor Agent reads configuration from:

Cursor IDE settings (if the user also has Cursor installed)
Environment variables
.cursor/mcp.json for MCP configuration (if Token Intelligence is enabled)

MCP Configuration

If Token Intelligence is enabled, Tempest writes:

{
  "mcpServers": {
    "atlas": {
      "type": "stdio",
      "command": "node",
      "args": ["--liftoff-only", "<entry-path>", "--path", "<project-path>"]
    }
  }
}

Tempest Integration

Session ID: Not persisted
Resumption: Not supported; each spawn creates a fresh session
Work-Done Detection: Uses signal detection
MCP Support: Writes to .cursor/mcp.json if Token Intelligence is configured

Troubleshooting

If Cursor doesn’t launch:

Ensure the Cursor CLI is installed: which cursor or gcm cursor
Cursor may require the Cursor IDE to be installed or configured
Check Cursor’s documentation for CLI setup

Goose

Display Name: Goose
CLI Command: goose
Resumable: No (stateless)

Launch Command

goose

Configuration

Goose reads configuration from:

~/.goose directory (user home)
Environment variables
Project-level configuration files

API Key Setup

Set your API key (if required):

export GOOSE_API_KEY="your-api-key"

Tempest Integration

Session ID: Not persisted
Resumption: Not supported; each spawn creates a fresh session
Work-Done Detection: Uses signal detection and heuristics
Limitations: Designed for autonomous task execution without persistent conversation

Use Cases

Autonomous task execution
One-shot agents that solve specific problems
Testing and automation workflows

Troubleshooting

If Goose doesn’t launch:

Ensure goose is installed: which goose (macOS/Linux) or gcm goose (Windows)
Check that any required environment variables are set
Test in a terminal: goose --help or goose to start

Antigravity

Display Name: Antigravity CLI Command: agy Resumable: No (stateless — resumes last session via --continue)

Launch Command

First spawn:

agy

Resuming (continues last session in CWD):

agy --continue

Tempest Integration

Session ID: Not persisted (no externally addressable session ID)
Resumption: --continue resumes the most recent session in the current directory
Work-Done Detection: Uses signal detection and heuristics
Auto-approve flag: --dangerously-skip-permissions — appended by default

Troubleshooting

If Antigravity doesn’t launch:

Ensure agy is installed and on your PATH
Test in a terminal: agy --help

Codex CLI

Display Name: Codex CLI CLI Command: codex Resumable: Yes (resumes last session in CWD via subcommand)

Launch Command

First spawn:

codex

Resuming (most recent session in CWD):

codex resume --last

Tempest Integration

Session ID: Not persisted (no externally addressable session ID; resume is CWD-based)
Resumption: codex resume --last picks up the most recent Codex session in the working directory
Work-Done Detection: Uses signal detection and heuristics
Auto-approve flag: --dangerously-bypass-approvals-and-sandbox — appended by default

Troubleshooting

If Codex CLI doesn’t launch:

Ensure codex is installed: which codex (macOS/Linux) or gcm codex (Windows)
Test in a terminal: codex --help

Comparison Table

Agent	Resume	Auto-approve flag	Config Location	API Key Required
Claude Code	Yes (`--resume`)	`--dangerously-skip-permissions`	`~/.claude`	Yes (Anthropic)
Gemini CLI	Yes (`--resume`)	`--yolo`	`~/.gemini`	Yes (Google)
Codex CLI	Yes (`resume --last`)	`--dangerously-bypass-approvals-and-sandbox`	`~/.codex`	Yes (OpenAI)
Antigravity	Yes (`--continue`)	`--dangerously-skip-permissions`	`~/.agy`	Yes
Opencode	Yes (captured ID)	—	`opencode.json`	Varies
Copilot CLI	No	—	`~/.config/gh`	GitHub token
Cline	No	—	`~/.cline`	Yes (Anthropic)
Cursor Agent	No	—	Cursor IDE config	Varies
Goose	No	—	`~/.goose`	Varies
Qwen Code	Yes (`--resume`)	`--yolo`	`~/.qwen`	Yes (DashScope / OpenAI-compatible)
Droid	No (see note)	— (see note)	`~/.factory`	Yes (Factory)
Amp, Hermes, Pi, fx, Grok	Manifest-defined	Per manifest	Per CLI	Per CLI

Droid: why no resume or auto-approve

Droid’s --auto <low\|medium\|high> autonomy flag is droid exec-only — interactive mode sets autonomy through the /model and /fast slash commands instead. Tempest applies flags.autoApprove to the interactive spawn as well as the headless one, so declaring --auto there would break every interactive Droid launch whenever Auto is on. The entry therefore ships without it; set your preferred level per-agent under Settings → Agents → Droid → Extra flags if you only use Droid headlessly. --resume [sessionId] is likewise omitted: it takes an id that Droid minted, and with no value it resumes the last-modified session — which is not necessarily the one belonging to this worktree. Tempest’s flags.session slot needs a CLI that accepts an id we supply on first run.

Provider presets

Some vendors sell a coding plan with no CLI of their own: you keep using Claude Code (or Codex, or opencode) and redirect it at their endpoint with a handful of environment variables. MiniMax and Z.ai/GLM both work this way. Rather than have you paste those vars by hand, Tempest ships the vendors’ documented recipes as presets. Pick one under Settings → Agents → <agent> → Provider, paste your API key, and new sessions of that agent use that provider.

Provider	Works with	Endpoint	Get a key
MiniMax	Claude Code	`https://api.minimax.io/anthropic`	platform.minimax.io
Z.ai (GLM)	Claude Code	`https://api.z.ai/api/anthropic`	z.ai

Notes:

Keys live in your OS credential manager, not in Tempest’s config — the same store the API Keys section uses. One key per provider is shared by every agent pointed at it.
A preset with no key is inert. Until you paste a key, the agent keeps using its own credentials, rather than being pointed at the vendor with an empty token.
Precedence: a preset sits below everything you set explicitly. Your per-agent Environment entries and the repo’s tempest.yml env both override it.
A provider only appears for agents whose recipe has been verified against vendor docs. The variables differ per CLI, so a guessed recipe would silently break authentication.
Presets are bundled with the release, not fetched. They rewrite an API base URL and carry the variable your key is exported into, so they deliberately do not ride the unsigned models.json patch channel. Adding one is a release.

To point an agent somewhere that has no preset, use Settings → Agents → <agent> → Environment directly — a preset is only a shortcut for that same mechanism.

Manifest-Driven Agents

The full agent list ships as config/agents.json. The AgentConfig fields on each entry — hint, sessionIdArgs, resumeArgs, capturePattern, captureResumeArgs, autoApproveArgs, printArgs, modelArgs, clearCommand — are what every surface in Tempest reads: the New Session menu, the Automations headless runner, the Chat pane bridges, and the Message Queue’s agent-aware clear. Agents added since this table was first written and driven entirely through the manifest: Antigravity, Codex CLI, Cursor Agent, Gemini CLI, Amp, Hermes, Pi, fx, Grok, Qwen Code, Droid. Tempest periodically fetches an updated manifest from the tempestai-dev/tempest repository at startup — a new agent added upstream shows up in your workspace without needing to rebuild.

Adding a New Agent

Most agents need no code — just a manifest entry. Add one without rebuilding by using Settings → Agents → Add (see custom agents); to ship one to everyone, open a PR against config/agents.json.

Add an entry to config/agents.json. Note the nesting: the flag templates live under a flags object, and the CLI command is command (it becomes AgentConfig.hint internally).

{
  "id": "myagent",                 // stable key; also overrides a bundled agent of the same id
  "name": "My Agent",
  "command": "myagent",            // bare token, or a few e.g. "gh copilot"
  "adapter": "cli",                // only "cli" is accepted
  "icon": "myagent.svg",           // a file in config/agent-icons/, or a bundled key
  "mono": true,                    // monochrome icon → inverted in dark mode
  "downloadUrl": "https://…",      // https only; shown when the CLI isn't on PATH
  "clearCommand": "/clear",        // REPL command the Message Queue's clear button sends
  "flags": {
    "session":     ["--session-id", "{UUID}"],  // first run; an id WE supply
    "resume":      ["--resume", "{UUID}"],      // resuming a stored conversation
    "model":       ["--model", "{MODEL}"],
    "autoApprove": ["--yolo"],                  // applied only when the user's Auto is on
    "print":       ["-p", "{PROMPT}"]           // headless; required for automations
  },
  "capture": {                     // only for agents that print their OWN session id
    "pattern": "([0-9a-f-]{36})",
    "flags": "i",
    "resume": ["-s", "{UUID}"]
  }
}

Placeholders substituted in every group: {UUID}, {MODEL}, {PROMPT}, {WORKSPACE_ID|NAME|SLUG|PATH}, {BRANCH}, {PORT}. An unknown one passes through verbatim and reaches the CLI literally, so src/lib/agentsManifestFile.check.ts rejects typos.

Commit the icon to config/agent-icons/ (not src/assets/, which holds only the bundled built-ins). Icons are served from Tempest’s own repo via jsDelivr, never a third-party host. Omit icon and the agent renders a generic terminal glyph.
Verify each flag against the CLI’s own --help or docs. Two traps worth calling out:
- autoApprove is applied to the interactive spawn as well as the headless one. A flag that only exists on a headless subcommand (Droid’s --auto, Crush’s --yolo) breaks every launch when Auto is on — leave it out.
- session needs a CLI that accepts an id you supply on first run. A --resume that only takes an id the CLI minted belongs in capture.resume instead, or nowhere.
Run the checks: npm test. agentsManifestFile.check.ts validates the shipped file — every entry survives sanitization, ids are unique, icons resolve to a real file, placeholders are known, and value-carrying slots actually reference their placeholder. A malformed entry is otherwise dropped silently, which looks like “my agent never showed up” rather than an error.
Optional — status detection. Agents whose title conventions are taught to sessionManager.ts’s classifyTitle() get busy/idle/needs-you states; the rest fall back to the quiet timer and OSC/BEL signals. Lifecycle hooks (src/lib/agentHooks/adapters/) give the most accurate status but need a bundled adapter, so they ship with a release.
Sign the manifest. config/agents.json is delivered over a signed channel, so a new entry reaches existing installs only once a key holder regenerates config/agents.json.minisig (see config/README.md). Until then it ships in the bundled floor with the next release.
Test in Tempest: launch it, resume it, and — if print is set — run it as a headless automation.

​Supported Agents

​Agent Configuration System

​Claude Code

​Launch Command

​Configuration

​API Key Setup

​Model Selection

​Tempest Integration

​Troubleshooting

​Gemini CLI

​Launch Command

​Configuration

​API Key Setup

​Model Selection

​Tempest Integration

​Troubleshooting

​Opencode

​Launch Command

​Session ID Capture

​Configuration

​MCP Configuration (Atlas)

​Tempest Integration

​Troubleshooting

​Copilot CLI

​Launch Command

​Configuration

​Authentication

​Tempest Integration

​Use Cases

​Cline

​Launch Command

​Configuration

​API Key Setup

​Tempest Integration

​Troubleshooting

​Cursor Agent

​Launch Command

​Configuration

​MCP Configuration

​Tempest Integration

​Troubleshooting

​Goose

​Launch Command

​Configuration

​API Key Setup

​Tempest Integration

​Use Cases

​Troubleshooting

​Antigravity

​Launch Command

​Tempest Integration

​Troubleshooting

​Codex CLI

​Launch Command

​Tempest Integration

​Troubleshooting

​Comparison Table

​Droid: why no resume or auto-approve

​Provider presets

​Manifest-Driven Agents

​Adding a New Agent

Supported Agents

Agent Configuration System

Claude Code

Launch Command

Configuration

API Key Setup

Model Selection

Tempest Integration

Troubleshooting

Gemini CLI

Launch Command

Configuration

API Key Setup

Model Selection

Tempest Integration

Troubleshooting

Opencode

Launch Command

Session ID Capture

Configuration

MCP Configuration (Atlas)

Tempest Integration

Troubleshooting

Copilot CLI

Launch Command

Configuration

Authentication

Tempest Integration

Use Cases

Cline

Launch Command

Configuration

API Key Setup

Tempest Integration

Troubleshooting

Cursor Agent

Launch Command

Configuration

MCP Configuration

Tempest Integration

Troubleshooting

Goose

Launch Command

Configuration

API Key Setup

Tempest Integration

Use Cases

Troubleshooting

Antigravity

Launch Command

Tempest Integration

Troubleshooting

Codex CLI

Launch Command

Tempest Integration

Troubleshooting

Comparison Table

Droid: why no resume or auto-approve

Provider presets

Manifest-Driven Agents

Adding a New Agent