CLI Agents
Launch, supervise, and review your external CLI coding agents — presets, program status, screen-inferred status, diffs, and notifications.
Cordy orchestrates the external CLI coding agents you already use. It launches them into workspace terminals, shows their status, 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:
| Agent | Preset command |
|---|---|
| Claude Code | claude |
| Codex CLI | codex |
| Cursor Agent | cursor-agent |
| Gemini CLI | gemini |
| Copilot | copilot --allow-tool=write |
| OpenCode | opencode |
Each preset runs in the project folder of the active workspace; agents only start inside a project folder. Claude Code and Codex launch without approval-bypass arguments; each CLI keeps its own permission flow. 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 and notifications. Start one from:
- Agent presets in the terminal preset bar;
- the command palette (
Cmd/Ctrl+K):Launch <preset>orSplit with <preset>in the Agent group; or - a preset's right-click menu in the preset bar:
Split right with <preset>orSplit down with <preset>.
The agent runs in a workspace terminal with its working directory set to the project folder. All workspaces of a project share that folder, so two agents in the same project edit the same files. For a separate checkout, add a git worktree add folder as its own project. See Concepts.
To stop an agent, use Stop <agent> in the command palette's Stop Agent group, or close its tab. Clicking an agent's badge in the sidebar focuses its tab.
Status and notifications
Cordy gets an agent's status in one of two ways.
Program status (OSC 7501)
A program that reports its own status through the Program Status Protocol (OSC 7501), such as Claude Code 2.1.295 or later, shows it on its tab in any terminal tab, whether launched from a preset or by hand:
| Tab label | Meaning |
|---|---|
| Working (or Working N%) | The program is working. |
| Needs approval | It is waiting for you to approve an action. |
| Has a question | It asked you something. |
| Needs sign-in | It needs you to sign in. |
| Needs attention | It is blocked for another reason. |
| Finished | It finished its task. |
| Failed | It failed. |
Once a run reports this way, Cordy stops reading its screen for status.
Since 0.6.0 Cordy no longer adds hook settings to Claude Code. Older Claude Code versions still run: launched from the Claude Code preset they get screen-inferred status like other agents; started by hand in a plain tab they show no status.
Screen-inferred status
For other preset launches, Cordy infers each agent's state from its terminal output 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 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 (30 seconds by default, 45 for Cursor Agent) moves running → idle; a failure pattern moves to failed; and process exit moves to exited. Treat screen-inferred status as a hint because a CLI can change its displayed text.
Notifications
When an agent needs you or finishes, Cordy notifies you:
| Source | Notification |
|---|---|
| Program status | <workspace> · Needs approval, Has a question, Needs sign-in, Needs attention, Finished, or Failed |
| Screen inference: waiting for input | "Agent needs input" |
| Screen inference: failure pattern | "Agent failed" |
| Screen inference: exit after running at least 30 seconds | "Agent finished" |
| You stop the agent | "Agent stopped" |
- A program-status update produces at most one notification. Notifications for the same run are throttled to one every 5 seconds; a question or approval request gets through sooner, after at least 2 seconds.
- An agent that exits by itself within 30 seconds produces no "finished" notification.
- Every notification appears as an in-app toast while Cordy is open. An OS notification is sent only when the Cordy window is not focused — hidden, minimized, or (on Windows) closed to the tray.
- Clicking an OS notification, or Open on the in-app toast, takes you to that agent's session.
- If the OS refuses notifications, Cordy shows a one-time in-app warning; you still get in-app toasts.
Cordy never answers an approval for an agent. Approvals stay in the agent's own terminal prompt.
Reviewing an agent's changes
An agent's work shows up as Git changes in the project's checkout, in the Changes panel: per-file and hunk-level stage, unstage, and discard; bulk actions; conflicts; and commit, fetch, pull, and push. Before a Pull or a branch switch, Cordy warns you about running agents on the project. See Files, Search & Git.
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 Settings → Terminal presets and choose Add preset. Provide:
- a Display name and the Command (executable);
- optional Default args (one per line) and Env overrides (key/value pairs);
- optional status patterns — Running, Waiting for input, Busy (wins over waiting), and Failure patterns, plus an Idle window (ms).
The working directory is always the project folder. Because a preset runs a real command with your full user permissions and no sandbox, Cordy shows a summary of the exact command line 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
- 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. 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
- Terminal — tabs, splits, program status, and exit handling.
- Files, Search & Git — the Changes panel and diff review.
- Shortcuts — the command palette and workspace keys.
- Privacy — keys, terminal output, and stored data.