Working with Agents

FlightDeck launches and supervises AI coding agents. This page covers the built-in backends, how to add your own, the live status system, and restarting.

Built-in agents

Four agents ship pre-configured, and OpenCode is the default:

Agent	Config key	Command
OpenCode	`opencode`	`opencode`
Claude Code	`claude`	`claude`
Codex CLI	`codex`	`codex`
Cursor CLI	`cursor`	`cursor-agent`

When you create a tab you pick which agent runs in it, so you can mix agents — Claude Code in one tab, OpenCode in another. If only one agent is configured, the picker is skipped.

Add or customize an agent

Agents are just config. Each lives under an [agents.<key>] table in config.toml with a display name, command, and arguments:

[agents.claude]
display_name = "Claude Code"
command = "claude"
args = []

Add your own by adding another [agents.<key>] table, and change the default tab agent with ui.default_agent. See the Configuration reference for the full schema.

Live status indicators

Every agent tab shows a one-cell status indicator next to its name, mirrored in the sidebar and summarized on the project tab:

🔴 working — a red animated spinner while the backend reports an active turn,
🟢 idle — a green dot while it waits for a prompt,
🔵 manual — a status you set yourself (see below), shown in cyan; it never hides the real process state.

How the status bridge works

At launch, FlightDeck injects a small, launch-scoped integration for each built-in backend that writes working / idle / waiting events to a status file in the worktree:

Claude Code — prompt/stop hooks via a launch-scoped plugin,
Codex CLI — prompt/stop hooks,
OpenCode — a launch-scoped plugin on its own events: turn start and end, permission requests and questions. The same plugin works with OpenCode 2 and OpenCode 1.x,
Cursor CLI — beforeSubmitPrompt / stop hooks.

Generated bridge files live under the ignored .flightdeck/runtime/ directory. Unsupported custom agents stay neutral rather than being guessed — they never show a false status.

note

Cursor only runs turn-level hooks that its user or project config declares, so its bridge is the one that cannot live under .flightdeck/runtime/: FlightDeck writes <worktree>/.cursor/hooks.json plus a self-ignoring .cursor/.gitignore, which keeps both files out of git status. A repo that already ships its own .cursor/hooks.json is never overwritten — that tab stays neutral instead.

Cursor also has no waiting state: it exposes no approval-request event, and the shell hook that fires before an approval fires just the same before an auto-approved command, so a Cursor tab shows working while Cursor asks to run something.

Finally, Cursor asks you to trust each workspace the first time it sees one, and a FlightDeck worktree is a new path every time — so a fresh Cursor tab opens on its trust prompt (press a). Add args = ["--trust"] to [agents.cursor] if you would rather grant it up front.

Reusable global status integrations

The automatic per-launch bridge is normally all you need. To generate standalone hooks for agent sessions launched outside FlightDeck, run:

flightdeck setup-status

This writes ready-to-wire artifacts to .flightdeck/integrations/ (with a README.md explaining how to merge each into your Claude Code, Codex, OpenCode or Cursor config). The hooks are gated on .flightdeck/ existing, so they're a no-op outside FlightDeck worktrees.

Manual status

Press Ctrl-s (palette → Set Manual Status) to attach a manual label to a tab: In progress, Waiting, Blocked, Done, or Clear. It shows in cyan and sits alongside — never on top of — the real process state, so it's a note to yourself, not a lie about what the agent is doing.

Restart an agent

Press Ctrl-r (palette → Restart Agent) to relaunch the primary agent in the same worktree and branch. Use it after changing config, when an agent crashes, or to resume a tab that was recovered but not auto-started.

OS notifications

FlightDeck can post a native notification the moment an agent finishes or needs you — see Notifications.