CLI Agents
Launch, supervise, and review your external CLI coding agents — presets, status inference, diffs, and notifications.
Cordy orchestrates the external CLI coding agents you already use. It launches them into workspace terminals, derives status from terminal output or supported provider hooks, shows their file changes, 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 credentials. Cordy processes terminal output for rendering, recovery history, and supervision; it does not proxy that content to a model service.
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 runs in the workspace's CodeTarget. Claude Code and Codex launch without approval-bypass arguments; each CLI keeps its own permission flow. Copilot's built-in preset currently includes --allow-tool=write. If a command is not on PATH, launch fails in the terminal as it would in your shell — install or authenticate that CLI and try again.
Launching an agent
Agent presets go through Cordy's runtime supervisor, so the run gets a status badge, activity panel, and notifications. Start one from any of:
- the Agent button in the workspace header, which opens the preset picker;
- the command palette (
Cmd/Ctrl+K) → the Agent group → "Launch <agent>".
The terminal preset bar launches the same supervised path. Right-click a preset for Split right with ... or Split down with ...; the new pane receives the same run status and close confirmation as a normal agent tab.
The agent runs in a workspace terminal with its working directory set to the workspace code path. Project-root workspaces share files; only existing worktree-backed targets provide separate working directories. See Concepts.
Live status
Cordy infers each supervised agent's state by watching terminal output 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). |
For screen-derived supervision, transitions are driven by rendered-text matches and timeouts. A running pattern marks successful startup. A prompt-line waiting pattern can mark a request for input; presets with a busy pattern instead treat the absence of busy text after startup as waiting. Busy patterns take priority when configured. New non-waiting output returns a waiting or idle run to running; silence past the idle window moves running → idle; a failure pattern moves to failed; and process exit moves to exited. Treat screen-derived status as a hint because a CLI can change its displayed text.
Claude Code's official hook integration can supply structured working, waiting, session-ended, and approval-request signals. Hook signals take priority over screen inference. The current Desktop build has no out-of-band approval control: an approval request triggers a notification, Cordy returns no decision, and Claude Code's own terminal prompt remains responsible for the answer. Other built-in agents use status and terminal supervision only.
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
An agent's work shows up as Git changes in that workspace's CodeTarget. A project-root workspace shares that directory with other workspaces that point there; an existing worktree-backed workspace has its own stored worktree path. The Changes panel lets you review the active target:
- 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 code target for changes and refreshes automatically. For the full Git workflow, see Files, Search, Git & notebooks.
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 |
| Claude Code hook reports an approval request | "Agent needs approval" | warning |
| Agent matches a failure pattern | "Agent failed" | error |
| Agent exits after running at least ~30s | "Agent finished" | info |
| You stop the agent | "Agent stopped" | info |
An agent that exits by itself within about 30 seconds produces no "finished" notification, to suppress noise from quick failed starts. A user-initiated stop is still acknowledged. 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, busy, 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.
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 send terminal contents to an AI provider of its own. It does render terminal output and persists bounded normal-buffer history for recovery.
- Cordy does not approve an agent action silently. Claude Code hooks can notify Cordy about an approval request, but the current Desktop build answers with no decision and leaves the approval in Claude Code's terminal. Cordy's own confirmations cover Cordy-level actions such as registering a custom command, committing or discarding changes, and destructive closes.
See Privacy for the full data boundary, and Runtime for the process supervisor that launches agents.
Related pages
- Concepts — the workspaces and CodeTargets that define an agent's working directory.
- Files, Search, Git & notebooks — the Changes panel and diff review.
- Shortcuts — the command palette and workspace keys.
- Privacy — keys, prompts, and evidence.