Agents

Built-in agents, ACP Registry agents, permissions, collaboration modes, and how Cocurdex keeps multi-session work legible.

Cocurdex coordinates multiple agent sessions in one workspace. Runtimes and providers evolve during pre-release; this page describes the product model and the agents available today.

Mental model

Each session has a clear status and derived attention state (see Desktop).
You can run more than one session without merging them into a single transcript.
Permissions, questions, and plan approvals surface in the UI instead of happening silently.
Prefer the narrowest permission and write mode that still lets the task complete.

Supported agents

Cocurdex ships four built-in agents and can add any coding agent published to the ACP Registry.

Id (`--agent`)	UI label	Runtime	Notes
`claude-agent`	Claude Agent	External `claude` CLI (2.0.0 or newer)	Plan mode, steering, native write
`codex`	Codex	External `codex` CLI	Plan mode, steering, native write; auth via Codex itself
`opencode`	OpenCode	External `opencode` CLI (2.0.20 or newer)	Plan mode via OpenCode's native plan agent, streaming; no steering
`pi`	Pi	Built in	Uses your provider configs and MCP servers; read-only write mode
`acp:<registry-id>`	Name from the registry	Any ACP Registry agent you install	Native write; plan mode and steering depend on the agent

Common registry agents:

Id (`--agent`)	UI label	Launch	Notes
`acp:cursor`	Cursor	`cursor-agent acp`	Streaming, native write; login via Cursor
`acp:devin`	Devin	`devin acp`	Streaming, native write; login via Devin
`acp:grok-build`	Grok Build	`grok agent stdio`	Plan mode, steering, native write; plan usage meter

External agents must be installed and authenticated on your machine. Settings → Agent CLIs shows each agent's detected version and status (Ready, Not installed, Update required), a copyable install command, and a docs link. An agent below its minimum version stays usable, but some capabilities may not work until you update.

Upgrading from an earlier build

Cursor, Devin, and Grok Build used to be built in with the ids cursor, devin, and grok-build. They now run through the ACP Registry as acp:cursor, acp:devin, and acp:grok-build. Existing sessions and roles are migrated automatically; update any scripts that pass the old ids to --agent.

ACP Registry agents

ACP agents speak the Agent Client Protocol. Cocurdex reads their model catalog and session modes from the agent itself, so the choices you see track the installed version.

To add one, open Settings → Agent CLIs → Add from ACP Registry, search the official registry, and click Install. Before anything runs, Cocurdex shows the install plan:

Distribution	What install does
Binary	Downloads the platform archive into the app's data directory and verifies its checksum when the registry provides one
npx / uvx	Runs the package runner once to cache the pinned package version; later starts reuse the cache
Local CLI	Nothing is downloaded — Cocurdex runs the CLI it found on your `PATH`

Registry agents are third-party code: review an agent's source and license before installing it. Remove uninstalls it again.

If cursor-agent, devin, or grok is already on your PATH, Cocurdex adopts it automatically the first time it starts.
Use my own command registers an agent the registry does not list (or a custom build): install it yourself, then enter its executable name or absolute path and the arguments that start ACP mode.
If an ACP agent process dies, the next turn respawns it and resumes the same provider session.

Choosing a runtime

Situation	Start with
You already use Claude Code / Claude CLI	`claude-agent`
You already use OpenAI Codex	`codex`
You use OpenCode elsewhere	`opencode`
You have a Cursor subscription	`acp:cursor`
You use Devin	`acp:devin`
You want Grok-oriented implementation	`acp:grok-build`
Another agent from the ACP Registry	`acp:<registry-id>`
Lightweight chat-style turn without native workspace write	`pi` (Pi)

Providers and models

Agents use provider configs (API base URL, credentials, catalog) and models registered in the app. Configure providers in the desktop UI; list them from the CLI:

cocurdex provider list
cocurdex provider models <provider-id>

Cocurdex reuses your existing provider setup where possible (for example Codex account state under ~/.codex). Do not paste secrets into product notes or the public docs site.

Permission modes

Permission modes are agent-specific. Risk levels:

Risk	Intent
normal	Ask or carefully gate tool use
elevated	Broader auto-approve for edits / review
dangerous	Full or bypass-style access — use deliberately

Claude Agent

Mode id	Risk
`claude-default`	normal
`claude-accept-edits`	elevated
`claude-auto`	elevated — offered when the installed Claude CLI supports auto mode; not available on Haiku models
`claude-bypass-permissions`	dangerous

When the collaboration mode is plan, the session uses claude-plan (plan only, no edits or commands). Switching back to default restores claude-default.

Codex

Mode id	Risk
`codex-read-only`	normal
`codex-auto`	elevated
`codex-full-access`	dangerous

Grok Build (`acp:grok-build`)

Mode id	Risk
`grok-ask`	normal
`grok-auto`	elevated (Grok’s risk classifier; may cost extra model calls)
`grok-always-approve`	dangerous

OpenCode

Mode id	Risk
`opencode-ask`	normal
`opencode-allow`	elevated
`opencode-deny`	normal

Other ACP Registry agents

Cursor, Devin, and other registry agents have no Cocurdex-side permission-mode list. Tool approval follows the agent's own ACP permission requests, which surface as permission cards like any other agent. Many registry agents still advertise session modes in the composer (for example Devin's Ask / Plan / Autonomous). Those choices come from the installed agent, not from a Cocurdex table.

Built-in Pi (`pi`)

No separate permission-mode list; write mode is read-only.

When an agent requests a privileged action, Cocurdex surfaces a permission card (and may show path/action detail). Resolve from the session UI or from session tui in the CLI.

Collaboration and write modes

Control	Values	Meaning
Collaboration	`default`, `plan`	Plan mode when the runtime supports a plan-first loop
Write mode	`read-only`, `native-write`	Whether tools may change the workspace

Not every agent supports every combination. ACP Registry agents (including Grok Build) run in native write only; built-in pi is read-only.

Agent roles

An agent role is a saved preset: agent + provider/model + permission mode + collaboration and reasoning axes, plus optional instructions and skills. Each role also has an avatar (an emoji or initial on a color, badged with the agent's icon) and an optional description of what it is good at — team leads read the description when they pick teammates.

Save a role from the composer: open the model menu in a new session and choose Save as role. Edit or delete roles under Settings → Roles, and list them from the CLI:

cocurdex role list

Apply a role when you start a session, or give one to a teammate or a script-run subagent.

Cocurdex agent tools

Every session gets a local MCP tool server from the daemon. Tools are grouped and only offered where they make sense:

Group	Tools	Offered to
`team`	`spawn_teammate`, `spawn_template`, `list_roles`, `list_templates`, `stop_member`, `stop`	Main sessions (team leads)
`team`	`task_create`, `task_list`, `task_update`	Main sessions and teammates
`messaging`	`list_agents`, `send_message`	Main sessions and teammates
`script_run`	`propose`	Main sessions
`settings`	`list`, `get`, `set`, `propose`	Main sessions (also powers the settings assistant)

Subagents started by a script run get none of these tools. Sessions that can delegate also receive guidance on when to use the agent's own native subagents (same provider, result only) versus a Cocurdex team or script run (another provider, a saved role, a separate worktree, or task dependencies).

See Teams and orchestration for what they do.

In-session controls

Some runtimes can change model, thinking / reasoning effort, permission, or related axes without recreating the provider session. That preserves conversation continuity and provider-side cache. If a control is missing for an agent, it is intentionally unsupported — there is no silent “restart the session under the hood” fallback.

While a session is idle, you can also switch the agent in the composer, or fork the session (or Fork from here on a user message). See Fork and switch agent. Execution tree shows the nested runs and tool calls.

Settings → Agent CLIs → Run limits caps concurrent delegated work; sessions you start yourself are never queued. See Providers and settings.

Steering and follow-ups

When an agent supports steering, you can send follow-up guidance while a run is active (or queue follow-ups until the current turn finishes — configurable in chat settings). When steering is unavailable, wait for the turn to finish or stop the session.

Stop a running session from the UI or:

cocurdex session stop <session-id>

Parallel sessions

Typical pattern:

One session implementing a feature
One session investigating a bug or reviewing a branch
Optional plan-mode session for design

Keep titles short and status visible. Switch only when attention demands it — do not merge unrelated work into one transcript to “save a session slot.”

Agents

On this page