Agent Mode

Turn an idle session into a full-tool local agent.

coop agent registers a headless agent consumer on a session. When a message arrives, it runs a real coding agent locally on the prompt and posts the reply back into the session — no human turn. It is the executor that makes an idle twin act, built on the same message bus every coop session already uses.

Quick start

# Wake on every message and drive the local Claude agent
coop agent --name twin my-session

# Point the agent at a specific working directory
coop agent --name twin --work-dir ~/code/my-project my-session

Options

• --name <name> — the agent's display identity in the session. A distinct name keeps the transcript legible and means the agent's own replies never wake it again (the fan-out skips the sender).
• --work-dir <path> — the working directory the agent runs in (its cwd). Defaults to the current directory. Scope this to a project workspace, not your home directory.
• --harness <claude> — which agent backs the run. Only claude is supported today; other harnesses are reserved for later.

Claude-only, for now

The harness is pluggable by design, but the shipped implementation is claude — headless Claude Code through the Agent SDK. It is the only harness that yields a configuration-inheriting twin (below). Cross-vendor executors are a future addition; selecting anything else today is an error.

Local credentials

The agent resolves Anthropic credentials from your machine, in order: ANTHROPIC_API_KEY, then ANTHROPIC_AUTH_TOKEN, then the active ant auth login / Claude Code login. Nothing is bundled or prompted for, and no key ever leaves your machine. Headless Agent SDK usage is metered separately from interactive use.

LifeOS inheritance (settingSources)

The Agent SDK loads no local configuration by default. Agent mode makes inheritance an explicit choice: when it enables the user setting sources (settingSources: ['user', 'project', 'local']), the headless run picks up your ~/.claude — CLAUDE.md, skills, hooks, and MCP connectors. Point it at the same ~/.claude and the twin is your interactive setup, headless. Point it at a scoped profile and it is a narrower, safer twin. This is a config choice, not magic — and it is the reason the claude harness alone yields a full twin.

The headless permission profile

A headless full-tool agent acting unattended — and inheriting your MCP credentials — is the highest-risk surface in the system, so agent mode never runs under the interactive permission mode. Every run carries a dedicated, restrictive permission profile:

• Tool allowlist — deny-by-default; anything outside the list is blocked.
• Side-effect gating — message sends, git push, deploys, and destructive shell (rm -rf, npm publish, wrangler deploy) require an explicit opt-in.
• Scoped configuration — run against a separate ~/.claude profile / MCP subset so the twin need not hold your production connectors.
• Distinct identity — the twin's messages are attributed to the agent consumer, not to you.

Single-run vs long-running

The same runner supports two latency profiles — swap the subscription, not the loop:

• Long-running (listen) — the agent holds a WebSocket and wakes near-instantly on each message. Good for an interactive twin while you keep the process up.
• Single-run / polling — the agent checks for messages on a cadence (no persistent process), runs the harness on anything new, and exits. Good for a scheduled or hook-driven twin with bounded latency and no idle cost.

Either way, the agent reads only messages after its own cursor and advances it crash-safely, so a restart never re-runs a message it already handled — and it is never woken by its own replies.