CLI Agents

Cordy orchestrates the external CLI coding agents you already use. It launches them into workspace terminals, infers their status from their output, gathers the changes they make, and notifies you when they need attention. It does none of the AI itself: each agent talks to its own provider, in its own process, with its own keys. Cordy holds no API keys and never reads an agent's prompts or responses.

Bring your own agents

Cordy does not bundle or install any agent. Install and authenticate each CLI agent exactly as its own documentation describes — its own account, provider, model, and keys — so that running its command in a terminal already works. Then Cordy can launch it for you.

Cordy ships presets for six agents out of the box:

Agent	Preset command
Claude Code	claude
Codex CLI	codex
Cursor Agent	cursor-agent
Gemini CLI	gemini
Copilot	copilot
OpenCode	opencode

Each preset launches its command with default arguments and runs with the workspace's CodeTarget as its working directory. Some presets pass permissive defaults so an agent can work with fewer prompts — for example, Claude Code launches as claude --permission-mode acceptEdits. You can inspect and change a preset's arguments to match how much autonomy you want to grant. If an agent's command is not on your PATH, the launch fails in the terminal exactly as running it yourself would — install or authenticate the agent and try again.

Launching an agent

There are two ways to start an agent, and they behave differently.

Tracked launch (supervised)

A tracked launch goes through Cordy's runtime supervisor, so the agent gets a status badge, an activity panel, and notifications. Start one from any of:

• the Agent button in the workspace header, which opens the preset picker;
• the Launch agent picker shortcut, Cmd/Ctrl+Shift+A; or
• the command palette (Cmd/Ctrl+K) → the Agent group → "Launch <agent>".

The agent runs in a workspace terminal session with its working directory set to the workspace's code path. Because each worktree-backed workspace is isolated, launching agents into different workspaces lets them work in parallel without colliding — see Concepts.

Quick launch from the terminal preset strip

The terminal tab bar also has a preset strip of quick-launch buttons. Clicking one opens a new terminal tab and types the generated command for you. This is a convenience for starting a command fast — it is not supervised, so it gets no status badge, activity panel, or notifications. Use a tracked launch when you want Cordy to watch the agent.

Live status

For tracked launches, Cordy infers each agent's state by watching its terminal output for patterns, and shows it as a badge:

State	Badge	Meaning
launched	Agent: launched	The process started; no defining output seen yet.
running	Agent: running	The agent is actively producing output — working.
waiting_for_input	Agent: waiting for input	The agent is prompting you and is blocked on your response.
idle	Agent: idle	Running, but quiet for a while (no output for the preset's idle window).
exited	Agent: exited	The process ended.
failed	Agent: failed	A failure pattern was matched (for example an auth or quota error).

Transitions are driven by pattern matches and timeouts: a running pattern moves launched → running; a waiting pattern moves running → waiting_for_input; any new output moves waiting_for_input or idle back to running; silence past the idle window moves running → idle; a failure pattern moves to failed; and the process ending moves to exited. The design deliberately prefers a missed transition over a wrong one, so treat status as a helpful hint, not a contract.

The activity panel

The agent activity panel shows the running agent's preset, its process id, its terminal session, and a short trail of evidence — the specific matched lines, heuristic reasons, or exit code that explain why Cordy assigned the current state. It also has a Kill agent control. The panel never shows raw agent output: only the small pieces of evidence behind each state change, which are kept in memory and never written to disk. See Privacy.

Reviewing an agent's changes

Because the convention is one agent per worktree-backed workspace, an agent's work shows up as the Git changes of that workspace's CodeTarget. The Git panel aggregates those changes so you can review them as a unit:

• a running +/− total across staged, unstaged, and untracked files;
• Staged Changes, Changes, and Untracked Files sections;
• per-file open diff, stage / unstage, and discard;
• hunk-level staging and discarding inside the diff viewer, plus an inline commit form; and
• fetch / pull / push for the same worktree.

Cordy watches the worktree for changes and refreshes automatically. For the full Git workflow, see Workspaces.

Notifications

When an agent changes state while your attention is elsewhere, Cordy notifies you:

Event	Notification	Level
Agent starts waiting for input	"Agent needs input"	warning
Agent matches a failure pattern	"Agent failed"	error
Agent exits after running at least ~30s	"Agent finished"	info

An agent that exits within about 30 seconds produces no "finished" notification, to suppress noise from quick failed starts. Notifications for the same agent are throttled to at most one every few seconds.

How a notification reaches you depends on Cordy's window focus:

• Every notification appears as an in-app toast while Cordy is open, regardless of focus.
• An OS system notification is sent only when the Cordy window is not focused — hidden, minimized, or (on Windows) closed to the tray.

If the OS refuses notifications (permission denied), Cordy shows a one-time in-app warning; you still get in-app toasts while the app is open. Notifications identify the agent run, but clicking one does not currently jump you to that agent or workspace.

Custom presets

You can register your own preset for any command — another agent, a wrapper script, or a specific invocation of a built-in agent. Open Register custom preset from the agent picker (or add one under Settings), and provide:

• a display name and the command to run;
• optional default arguments (one per line) and environment overrides (key/value pairs);
• optional status-detection patterns — running, waiting-for-input, and failure patterns, plus an idle timeout; and
• the working directory, which is always the workspace's code target.

Because a preset runs a real command with your full user permissions and no sandbox, Cordy shows the exact command line for you to confirm — the approval reads "I authored this preset and own the command." Custom presets are stored locally under your user-data directory.

Current limitation. A custom preset launches with your command, arguments, and environment, but its status-detection patterns are not yet applied to live inference. A custom-launched agent therefore shows as launched until it exits, rather than transitioning through running and waiting_for_input. Built-in presets have full status inference.

What Cordy does not do

To be unambiguous about the boundary:

• Cordy does not embed a chatbot or call any language model.
• Cordy does not hold your provider API keys — each agent reads its own from its own environment or config.
• Cordy does not read, store, or proxy an agent's prompts or responses.
• Cordy does not intercept an agent's own approval prompts (for file writes, shell commands, or tool calls). Those stay entirely inside the agent, over its own terminal. Cordy's own confirmations cover only Cordy-level actions — launching a custom command, running workspace setup/teardown scripts, and committing or discarding changes.

See Privacy for the full data boundary, and Runtime for the process supervisor that launches agents.

Related pages

• Concepts — the workspaces and CodeTargets that isolate agents.
• Workspaces — the Git panel and diff review.
• Shortcuts — the agent-picker shortcut and command palette.
• Privacy — keys, prompts, and evidence.