Teams and orchestration

A single session is one agent in one conversation. When a task is wide enough to split, Cocurdex gives agents three daemon-owned ways to coordinate other agents:

All of them are exposed to agents as Cocurdex agent tools (a local MCP server the daemon attaches to each session) and to you through the desktop UI and the CLI. State is durable: runs, teams, and tasks survive app restarts.

Agent teams

A team belongs to a lead session. The lead spawns teammates — separate agent sessions that run in parallel — and coordinates them through a shared task list.

• Each teammate's final reply of every turn is delivered back to the lead automatically.
• When a teammate stops on a permission request or a question, the lead is told that it is waiting for you (once per turn), so the lead can point you to it instead of waiting silently.
• Teammates can message the lead or each other.
• A team holds at most 8 teammates. Teammates cannot spawn their own teammates.
• A teammate can run in its own managed worktree so parallel edits never share a dirty checkout.
• A teammate uses a saved agent role or an agent id; by default it inherits the lead's agent. OpenCode sessions cannot lead or join a team.

Shared task list

Each team has its own task list, separate from your issues: agent-created tasks never land on your issue board. A task has a title, status (backlog, doing, review, done), assignee, prerequisites, and review evidence.

Team templates

Define reusable teams under Settings → Teams: name each teammate, pick a saved role, and give it a standing prompt. A lead agent can spawn the whole template at once, or you can do it from the CLI.

cocurdex team templates
cocurdex team spawn-template --lead <session-id> --template <template-id> [--prompt "<task for the team>"]

From the CLI

cocurdex team get --lead <session-id>
cocurdex team create --lead <session-id> --template <template-id>
cocurdex team spawn --lead <session-id> --name reviewer --prompt "Review the auth changes" \
  [--role <role-id>] [--agent codex] [--worktree]
cocurdex team roles
cocurdex team stop-member --team <team-id> --session <session-id>
cocurdex team stop --team <team-id>

Teammate names are lowercase slugs (a-z, 0-9, -). The desktop shows the team in the lead session with each member's status (Starting, Running, Idle, Error, Stopped), a reply box when a teammate needs input, and Stop all.

The optional /cocurdex-team skill teaches a lead agent when a team actually helps, how to brief teammates, and how to merge their reports.

Peer messaging

Main sessions can message each other by session id. A message is delivered as a new turn when the receiver is idle, or queued after its current turn.

cocurdex session peers <session-id>
cocurdex session send-peer <from-session-id> <to-session-id> "API contract is merged; rebase and continue"
cocurdex session peer-inbound <session-id> deliver|refuse

Script runs

A script run lets an agent describe a fan-out as code. The agent proposes a short JavaScript script; you review it and approve it before anything runs. The result is delivered back to the requesting session as a message when the run finishes.

The script body is plain JavaScript with top-level await and return. It runs in a sandbox with no module imports, filesystem, network, or shell — only subagents do real work.

agent() options: label, agentRoleId (use a saved role instead of inheriting the requester's agent, model, and permissions), worktree: true (isolate file edits), and schema (a JSON Schema — the reply is parsed and validated, with retries).

const modules = await agent("List the packages under packages/ as a JSON array of paths", {
  schema: { type: "array", items: { type: "string" } },
});

const reports = await pipeline(modules, (dir) =>
  agent(`Add missing unit tests in ${dir}. Reply with a one-line summary.`, {
    label: dir,
    worktree: true,
  }),
);

return reports;

Limits

Run status moves through draft (awaiting approval) → running → completed, failed, cancelled, or interrupted. The desktop shows a Script runs panel with each subagent's state and a Cancel action.

cocurdex script-run list [--session <session-id>] [--workspace <workspace-id>]
cocurdex script-run get --run <run-id>
cocurdex script-run create --session <session-id> --name <kebab-name> --file script.js
cocurdex script-run start --run <run-id> [--max-agents <n>]
cocurdex script-run cancel --run <run-id>

Choosing a primitive

• Two or three independent slices of one feature → a team, with worktrees for anything that edits files.
• Dozens of near-identical units → a script run with a schema so results come back structured.
• Two sessions you already run need to sync → peer messaging.

Related

• Agents
• CLI
• Skills