capd — Daemon do Protocolo de Agentes de Código
codingagentprotocol/capd
Protocolo unificado para controlar múltiplos agentes de código
Ver no GitHubcapd é um daemon que descobre agentes de código locais instalados (Claude Code, Codex, Gemini CLI e outros) e os expõe através de uma interface unificada WebSocket + JSON-RPC 2.0. Traduz as diferentes sintaxes e formatos de cada CLI em um protocolo comum, permitindo que clientes web, desktop e terminal controlem qualquer agente com o mesmo código.
Instalação
npx convez-ai codingagentprotocol/capd1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar múltiplos CLIs de agentes de código em uma única aplicação
- Criar clientes universais que funcionam com Codex, Claude Code, Gemini e outros
- Persistir sessões de coding com recuperação após desconexões ou falhas
- Controlar execução em tempo real com streaming, cancelamento e aprovação de ações
Veredito

capd resolve um problema real de fragmentação no ecosistema de agentes de código, oferecendo abstração robusta com persistência e controle fino. Implementação solid (Go, estrutura arquitetural clara) para equipes que precisam suportar múltiplos agentes simultaneamente, mas requer compreensão profunda da arquitetura para extensão.
README
A tradução para o português deste README ainda está na fila.
capd
One protocol to drive every coding agent CLI.
capd is the Coding Agent Protocol (CAP) daemon. It runs on your machine, discovers the coding agent CLIs you have installed — Codex, Claude Code, Gemini CLI, OpenCode, Xiaomi MiMo Code, Cursor CLI, and more — and exposes them to web, desktop, and terminal clients through a single WebSocket + JSON-RPC 2.0 interface.
Every agent CLI speaks its own dialect: different flags, session models, and streaming formats. capd translates all of them into one unified protocol, so a client written once can drive any agent.
Architecture at a glance
flowchart LR
web["Web app"]
desktop["Desktop app"]
cli["capd run / watch"]
subgraph cap["capd daemon"]
server["server\nWebSocket + JSON-RPC\nmethod dispatch + fan-out"]
session["session\nlive registry\nseq event log\nSQLite persistence"]
adapter["adapter\none translator per agent dialect"]
proc["proc\nsubprocess lifecycle\nstdout/stderr stream plumbing"]
account["account\nsafe account metadata\nquota snapshots\nsession binding"]
server --> session
session --> adapter
adapter --> proc
server -. account-aware routing .-> account
session -. session-account map .-> account
end
codex["Codex CLI\napp-server profile pool"]
claude["Claude Code\nheadless exec"]
gemini["Gemini / Qwen / iFlow\nheadless exec"]
opencode["OpenCode / MiMo\nheadless exec"]
cursor["Cursor CLI\nheadless exec"]
web -- "CAP over WebSocket\nJSON-RPC 2.0" --> server
desktop -- "CAP over WebSocket\nJSON-RPC 2.0" --> server
cli -- "local client" --> server
proc --> codex
proc --> claude
proc --> gemini
proc --> opencode
proc --> cursor
The dependency direction stays one-way:
flowchart LR
cmd["cmd/capd"] --> daemon["internal/daemon"]
daemon --> server["internal/server"]
server --> session["internal/session"]
session --> adapter["internal/adapter"]
adapter --> proc["internal/proc"]
protocol["pkg/protocol\npublic CAP contract"]
cmd -.-> protocol
server -.-> protocol
session -.-> protocol
adapter -.-> protocol
Why capd
- Write once, drive any agent. One client codebase for Codex, Claude Code, Gemini, OpenCode, Cursor — and forks like MiMo Code, Qwen Code, iFlow, and CodeBuddy ride the same translators.
- Sessions that refuse to die. Client disconnects, daemon restarts, and even agent-engine crashes never lose a conversation: events are sequence- numbered and persisted, and sessions revive with their native context.
- Real control, not fire-and-forget. Stream output token by token, steer a running turn, cancel instantly, and approve or deny each dangerous action from any client.
- Tiny footprint. A single CGO-free binary; ~18 MB resident as a daemon.
Install
Download a release archive for your platform from Releases, or build from source:
go install github.com/codingagentprotocol/capd/cmd/capd@latest
Run it in the foreground, or install it as a user-level service (launchd / systemd / Windows SCM — starts on boot, restarts on crash, never runs as root):
capd start --secret-backend native # foreground
capd service install --secret-backend native && capd service start # persistent
# or: CAPD_SECRET_BACKEND=native capd service install && capd service start
# custom CAPD_HOST / CAPD_PORT / CAPD_ORIGINS are captured at install time
The local web console is served by the daemon at
http://127.0.0.1:7777/console/. Open it with capd console; for the compact
data validation page, use capd console --probe. The command passes a
short-lived scoped browser token to the page without printing it to the
terminal; the root daemon token remains in ~/.capd/token for CLI clients. The
probe also calls
/probe/data with Authorization: Bearer ... to fetch machine-readable,
secret-redacted health, account, quota, and route diagnostics. The full
console's ordinary diagnostic refresh and the probe's ordinary Refresh path
use accounts/list metadata plus route evidence, so opening either page does
not read account SecretStore credentials. Use the console's 就绪门禁, the
probe's Readiness, or pass --require-secret-backend native only for
explicit native SecretStore checks.
Quick start
capd agents list # which agent CLIs does this machine have?
capd agents calibrate # dry-run live-calibration plan for installed/fork CLIs
cd ~/your-project
capd run "explain the structure of this repo"
capd run streams the agent's work to your terminal: typewriter output,
each command it executes, and interactive approval prompts:
session s_824067bfb24f2c25 (codex)
⏵ /bin/zsh -lc 'ls -la'
⚠ approval needed (command): rm -rf build/
allow? [y]es / [a]lways / [N]o: y
✓ done
(continue with: capd run --session s_824067bfb24f2c25 "...")
Useful flags and companions:
capd run --agent opencode "..." # pick the agent
capd run --agent codex --account codex-acct # use an imported Codex account
capd run --agent codex --account auto --require-fresh-quota "..." # quota-aware Codex account
capd run --agent codex --account auto --profile work "..." # route inside a named account profile
capd run --model gpt-5.3-codex --effort high "..."
capd run --permission acceptEdits "..." # default | acceptEdits | full
capd run --image diagram.png "what's wrong in this architecture?"
capd run --session s_xxx "follow-up..." # multi-turn, survives restarts
capd sessions # all sessions: live / stored / ended, plus pending approvals
capd watch s_xxx # re-join a long-running task: replay + follow
capd agents usage codex # plan, rate-limit windows, reset times
capd agents usage codex --account codex-acct
capd agents usage codex --account auto
capd agents route --account auto --require-fresh-quota --json
capd agents route --account auto --profile work --json # route inside a named account profile
capd accounts codex import # import local ~/.codex/auth.json into capd
capd accounts codex import --auth /tmp/a/auth.json --auth /tmp/b/auth.json # batch import explicit paths
CAPD_CODEX_AUTH_PATHS="/tmp/a/auth.json:/tmp/b/auth.json" capd accounts codex import # batch import on macOS/Linux
CAPD_CODEX_AUTH_PATHS="C:\tmp\a\auth.json;C:\tmp\b\auth.json" capd accounts codex import # batch import on Windows
capd accounts codex list --json # imported accounts, current marker, safe secret backend and quota metadata
capd accounts profile create work --description "Work Codex accounts"
capd accounts profile add work codex-acct-a codex-acct-b
capd accounts profile current work
capd accounts profile show work --json # safe profile members for account-pool routing
# The Web Console can create profiles, add/remove members, and route with --account auto + profile.
capd accounts codex project # create a per-account CODEX_HOME projection
capd accounts codex migrate-secrets --from file --to native --dry-run # preview moving older imports to native SecretStore
capd accounts codex migrate-secrets --from file --to native --timeout 2m # update refs after native secrets are written and read back
capd accounts codex quota # refresh quota and print a safe summary
capd accounts codex quota auto
CAPD_SECRET_BACKEND=native capd accounts --secret-backend native codex quota all --timeout 2m
CAPD_SECRET_BACKEND=native capd accounts --secret-backend native codex smoke --json --quota --require-multiple --require-fresh-quota --require-all-fresh-quota --require-secret-backend native --timeout 2m
CAPD_SECRET_BACKEND=native capd secretstore check --json --roundtrip --require-backend native --timeout 2m # verify native SecretStore directly
CAPD_SECRET_BACKEND=native capd doctor --json --fail --verify-secretstore --require-secret-backend native --timeout 2m # readiness gate
CAPD_SECRET_BACKEND=native capd doctor --repair-plan --prompt-free --require-secret-backend native # repair commands only
CAPD_SECRET_BACKEND=native capd doctor --evolution-backlog --prompt-free --require-secret-backend native # token-free next product demands
make live-codex-repair-plan # same repair plan using LIVE_SECRET_BACKEND/CAPD_BIN
make live-codex-repair-commands # one repair command per line, no jq required
make live-codex-repair-run # dry-run approval-gated repair runner with LIVE_SECRET_BACKEND/CAPD_BIN
make live-codex-repair-execute # execute only runnable repair steps with LIVE_SECRET_BACKEND/CAPD_BIN
make live-codex-evolution-backlog # same P0/P1/P2 backlog using LIVE_SECRET_BACKEND/CAPD_BIN
make live-agent-calibration # execute one bounded adapter smoke; override with LIVE_AGENT=cursor-agent
CAPD_SECRET_BACKEND=native capd repair run --require-secret-backend native # dry-run approval-gated repair steps
CAPD_SECRET_BACKEND=native capd repair run --execute --yes --require-secret-backend native # execute only runnable non-placeholder steps
capd start --secret-backend native # keep running in another terminal for CAP/WebSocket checks
capd console --probe --require-secret-backend native # simple web data probe; opens with daemon token without printing it
capd probe data --json --readiness --require-secret-backend native --timeout 2m --fail # same probe diagnostics for automation
curl -H "Authorization: Bearer $(cat ~/.capd/token)" http://127.0.0.1:7777/probe/data # safe JSON diagnostics
capd probe evidence --manifest /tmp/capd-live-evidence/manifest.json --require-live-complete --fail # validate saved live selftest evidence artifacts
capd support bundle --out /tmp/capd-support --require-secret-backend native # collect safe support/evidence JSON, agents-calibration-report.json, evolution-backlog.json, plus report.html
capd health --summary --require-secret-backend native # human daemon/runtime/session/backlog/metrics summary
capd health --json --require-secret-backend native # machine-readable /healthz version/protocol/backend/runtime counters
capd accounts import --auth /tmp/a/auth.json --auth /tmp/b/auth.json # daemon-side CAP import
CAPD_CODEX_AUTH_PATHS="/tmp/a/auth.json:/tmp/b/auth.json" capd accounts import # daemon-side CAP batch import on macOS/Linux
CAPD_CODEX_AUTH_PATHS="C:\tmp\a\auth.json;C:\tmp\b\auth.json" capd accounts import # daemon-side CAP batch import on Windows
capd accounts check --json # daemon-side accounts/check smoke evidence with compact summary
capd accounts check --json --readiness # daemon-side multi-account readiness gate with repairPlan on failure
capd agents route --account auto --require-fresh-quota --json
For the full local Codex account-plane audit, run make verify-codex-goal.
For deterministic local regression, run make verify; for native SecretStore
coverage, run make verify-secretstore; for a no-real-account Codex
multi-account quota/routing/readiness regression, run
make verify-codex-readiness-sim. That simulated gate also covers the safe Web
Console/Probe prompt-free refresh contract, Web probe summaries, probe
readiness SecretStore defaults, SecretStore recovery next steps, /healthz
backend requirement, and direct SecretStore JSON roundtrip without touching live
Codex accounts.
capd doctor --prompt-free --json --fail is the fastest safe metadata/quota/routing
audit for live Codex work; it does not read account SecretStore credentials.
capd doctor --json --fail --timeout 2m is the deeper audit: it checks daemon
health, Codex CLI availability, imported account count, per-account SecretStore
credential readability, quota freshness, auto-route freshness, the active
SecretStore backend, and daemon-side CAP accounts/check reachability without
printing token material. Add --verify-secretstore before native live runs to
write, read, and delete a diagnostic secret in the active backend. When secretState
is access-denied, macOS denied or canceled Keychain access; approve the prompt,
or use the file SecretStore for local no-prompt testing. When accounts are
missing, use
capd accounts import --auth ... or CAPD_CODEX_AUTH_PATHS=... capd accounts import to exercise the same daemon-side CAP path as the Web Console. Use
capd accounts check --json --readiness for the
daemon-side refresh-and-verify gate after fixing quota or account issues. After
importing multiple Codex accounts and starting capd start with the same
backend in another terminal, make live-codex-preflight first prints safe
account metadata and fails fast on missing second accounts before native
SecretStore roundtrip prompts. It then verifies SecretStore, refreshes every
Codex quota, runs doctor against fresh local evidence, and checks the tokenized
Web probe URL plus daemon/Web quota/routing/readiness without sending a prompt.
Doctor JSON also includes repairPlan: an ordered, token-redacted list of
runnable commands plus expected evidence for fixing daemon, account import,
SecretStore, quota freshness, auto-route freshness, installed adapter live
calibration, and final live preflight gates. Adapter calibration repair steps
reuse capd agents calibrate --execute --yes --agent <id> --json, so execution
goes through the same bounded smoke runner and safe audit path as manual
calibration. It also includes evolutionBacklog, a bounded P0/P1/P2 list of
product demands inferred from the same evidence, so CLI automation can tell
whether the next move is importing another account, refreshing quota, proving
native SecretStore, running the repair plan, calibrating an installed adapter,
or archiving a live evidence package. The plan entries use the public
protocol.RepairStep shape shared with
/probe/data, so CLI, Web, CI, and future autopilot clients can consume one
stable contract. Text output prints the same plan under repair plan: and
prints backlog entries as evolve: lines for copy/paste debugging. Use
capd doctor --repair-plan --prompt-free when CI or a
long task only needs the ordered repair plan JSON array, or
make live-codex-repair-plan when it should use the same LIVE_SECRET_BACKEND
and CAPD_BIN knobs as the live preflight. Use
capd doctor --repair-commands --prompt-free or
make live-codex-repair-commands when a shell log needs one command per line
without jq. Use capd doctor --evolution-backlog --prompt-free or
make live-codex-evolution-backlog when automation only needs the token-free
P0/P1/P2 product demand list. Use capd repair run for the approval-gated autopilot path:
it is dry-run by default, and --execute --yes runs only non-placeholder,
non-foreground repair commands. The Makefile shortcuts
make live-codex-repair-run and make live-codex-repair-execute run those
same dry-run and approved-execution paths with the shared LIVE_SECRET_BACKEND
and CAPD_BIN knobs. make live-agent-calibration runs
capd agents calibrate --execute --yes --agent $(LIVE_AGENT) --json --report --fail
for one installed CLI with bounded output capture, giving CI and live handoffs
a small pass/fail adapter smoke outside the broader account readiness chain. It
leaves daemon startup, shell export
commands, auth path placeholders, and the final live preflight for explicit
manual action unless the command is made runnable and, for the final gate,
--include-final is supplied. If the same plan includes a manual daemon startup
step, later requiresDaemon commands stay manual until the daemon is started
and the plan is rebuilt, so --execute --yes does not burn a run on predictable
connection failures. Repair execution is bounded to 20 steps, 4096
byte commands, and 8192 bytes of captured output per step; truncated JSON rows
set outputTruncated:true. Repair-run JSON also includes per-step and summary
startedAt/finishedAt timing plus separate timedOut and canceled
counters for deadline and cancellation diagnosis; /probe/data projects the
same safe aggregate repair-history counts for Web/CI timelines. /probe/data and
capd repair run --json
attach execution.runnable plus execution.reason to repair steps; the Web
Console and compact Probe render that server-provided classification, with a
local fallback for older daemons. The Console renders repair plans returned by
both /probe/data deep verification and direct accounts/check readiness.
It can also export a prompt-free browser evidence package with inline health,
probe, route, account-check, and account-health artifacts for local QA handoff.
For unattended release checks, make live-codex-selftest starts a temporary daemon when needed, waits for health,
runs the same preflight, and cleans up only the daemon it started. The final
route gate runs as JSON so the log keeps the complete routeCandidates
ordering used for account-aware selection. If selftest preflight fails, it first
prints a prompt-free readiness gap summary, then daemon health, account
metadata, repair-run dry-run JSON, fresh route gate JSON, prompt-free probe data
JSON, and smoke JSON; set LIVE_DIAGNOSE_SECRETSTORE=1 for the heavier native
SecretStore doctor, daemon-side accounts/check, and probe diagnostics. Set
CAPD_LIVE_SUMMARY=/tmp/capd-live-summary.json to emit a compact status/stage
artifact with timestamp, daemon mode, binary, log path, and optional repair-plan
path for CI or
long-running tasks; the file is updated with status:"running" as each stage
starts, then overwritten by the final result. Set
CAPD_LIVE_EVIDENCE_DIR=/tmp/capd-live-evidence to persist safe JSON evidence
from the final route gate, /probe/data readiness gate, and prompt-free doctor
report; the directory also gets a manifest.json index and the summary includes
the manifest, generated report.html, and primary evidence paths so long tasks
can prove account count, fresh quota, route policy, route candidates, and
SecretStore backend without scraping shell logs. The summary keeps absolute
paths for local CI lookup, while manifest.json records artifacts relative to
the evidence directory so the package stays portable after upload or archive.
On preflight failure the directory also captures repair-run-dry-run.json, a
prompt-free capd repair run dry run that records runnable/manual repair
actions without executing approval-gated fixes.
On successful selftest runs, the script also validates that package and writes
the standalone HTML report before reporting status:"passed".
make live-codex-readiness runs the
same preflight and then sends the final live prompt. Override the final prompt with
LIVE_PROMPT="..." make live-codex-readiness; override the backend only for
intentional testing with LIVE_SECRET_BACKEND=file. The target runs every live
command with the same CAPD_SECRET_BACKEND value, and the daemon-side
readiness step uses capd accounts check --json --readiness, so failing gates
still print safe partial evidence and a compact summary under data for
quota, account, and SecretStore diagnostics.
Set CAPD_LIVE_REPAIR_PLAN=/tmp/capd-live-repair.json with
make live-codex-selftest to persist the prompt-free doctor report, including
its ordered repairPlan, when daemon startup, backend alignment, preflight, or
the optional live prompt fails.
capd health --summary --require-secret-backend <file|native> reads the same
safe /healthz?format=json runtime data as --json, but prints a compact
human summary for daemon uptime, client count, session states, longest live
session age, pending approvals, buffered events, subscriber overflows, adapter
start/failure counts, route failures, SecretStore access-denied totals, and
grouped route decisions.
Both health modes fail early if the daemon was started with the wrong backend
and never expose token material.
capd secretstore check --roundtrip --require-backend <file|native> --timeout 2m is the
smallest direct SecretStore gate: it opens the selected backend, optionally
writes/reads/deletes a diagnostic secret, prints no token material, and fails
before account checks when native storage is unavailable, mismatched, or stuck
behind an OS credential prompt.
capd probe data --json --readiness --timeout 2m --fail calls the same authenticated
/probe/data endpoint used by the lightweight web probe, so live preflight also
verifies the Web diagnostics path with header auth and safe partial evidence.
The full Web Console's ordinary diagnostic cards and the compact Probe's
ordinary validation rows stay prompt-free and label SecretStore credentials and
projected runtimes as not checked in prompt-free refresh. Their ordinary next
steps point first to capd doctor --prompt-free; 深度验证, 就绪门禁, or the
Probe Readiness button are explicit deeper checks that may read account
SecretStore credentials. The console's 深度验证 button runs that same
header-authenticated readiness probe and renders the returned checks, errors,
auto-route, route-candidate evidence, and repair-plan commands in place.
It can also paste a live selftest manifest.json or summary.json into the
diagnostic package viewer to inspect recorded route, probe, doctor, and smoke
evidence paths, including the generated report.html, without reading local
files or exposing daemon tokens.
Pasting the matching artifact JSON from agents-route.json,
probe-data-readiness.json, doctor-prompt-free.json,
repair-run-dry-run.json, agents-calibration-report.json, or
evolution-backlog.json turns that same viewer
into a compact QA report for route policy, route decision, route candidates,
quota freshness, repair-plan evidence, and adapter calibration readiness.
For CI or long-running tasks, capd probe evidence --manifest /tmp/capd-live-evidence/manifest.json --require-live-complete --fail reads the
same manifest and its listed artifacts locally, then fails if route policy,
route candidates, fresh quota evidence, route decision evidence, native backend,
daemon mode, passed selftest status, readiness summary, two-account evidence,
all-fresh quota evidence, or a safe audit artifact is missing.
Add --html /tmp/capd-live-evidence/report.html to write a standalone QA
report from the same safe summary without embedding raw artifact JSON or local
artifact absolute paths.
New evidence manifests include collection traits such as promptFree,
secretReading, runtimeProjecting, and quotaRefreshing, so archived support
and live selftest packages explain how they were collected.
The endpoint bounds server-side work too: ordinary probes get 12s and readiness
probes get 2m. Its JSON includes a compact summary for account counts, quota
freshness, auto-route freshness, route-decision status, and SecretStore backend
status, plus repairPlan entries with runnable commands and expected evidence
for Web/CI clients that want the same ordered autopilot view as capd doctor.
It also returns evolutionBacklog, the same bounded, token-free P0/P1/P2
product demand contract exposed by capd doctor, with Web-specific evidence
such as repair history and route/quota audit history included when available.
The same JSON includes a safe agents array with adapter mode, readiness,
family, calibration, and next-step hints, and raises installed adapter
live-calibration gaps into evolutionBacklog so the Web Console can surface
CLI translator smoke needs without reading credentials.
Both agents/route --account auto --json and daemon-side accounts/check
include routeCandidates, sorted by the same conservative quota score used for
auto routing, with each parseable candidate carrying the safe secretBackend
enum (file or native) so clients can verify why one account was selected
and which readiness backend applies. The
capd probe data --readiness text view also prints the same safe route
candidate summary when the Web diagnostics path has partial evidence. The
accounts/check.summary object is the shared machine-readable readiness view
for CLI, Web, Probe, and automation clients.
Local capd accounts codex smoke --json uses the same safe secretState
vocabulary, so SecretStore read failures still return partial account evidence
without token material. Its secretChecked and runtimeChecked booleans make
early prompt-free failures distinguishable from actual credential or projection
failures.
Every flag, protocol field, and event is documented in docs/reference.md. The forward plan is tracked in docs/roadmap.md, with concrete acceptance gates for account intelligence, security hardening, performance, and adapter extensibility. The current goal-to-evidence audit lives in docs/evidence-matrix.md.
Permission modes
| Mode | Meaning (codex mapping) |
|---|---|
default | read-only sandbox; every write needs an approval |
acceptEdits | workspace-write; actions outside the workspace need approval |
full | no sandbox, no prompts — you opted in |
capd sets these explicitly per session and never silently inherits a permissive user config.
Supported agents
| Agent | Mode | Streaming | Approvals | Steer | Fork/Rollback | Usage data |
|---|---|---|---|---|---|---|
| Codex CLI | app-server engine | ✅ deltas | ✅ | ✅ | ✅ | ✅ |
| Claude Code | headless exec | block | — | — | — | — |
| OpenCode | headless exec; live smoke hint after install/login | block | — | — | — | — |
| Xiaomi MiMo Code | opencode-family translator; discovered as mimo-code when mimo is installed; live smoke hint after install/login | block | — | — | — | — |
| Gemini CLI | headless exec | login + live calibration recommended | ||||
| Cursor CLI | headless exec | login + live calibration recommended | ||||
| Qwen Code, iFlow | gemini-family translators; discovered when installed; live calibration recommended | |||||
| CodeBuddy | claude-family translator; discovered when installed; live smoke hint after install/login | |||||
| Kimi CLI | ACP stdio agent server via kimi acp; discovered when installed; live smoke hint after install/login | ✅ chunks | ✅ CAP approval bridge | — | — | — |
Use capd agents calibrate --json to turn those adapter hints into a safe
dry-run plan with runnable, command, and reason fields before routing
production work to a newly installed CLI. Plain text includes a safe aggregate
calibration summary; --report --json returns {ok, summary, steps} for CI
and repair automation while legacy --json remains a steps array. The default
view stays focused on calibration gaps; --include-ready or an explicit
--agent <id> can also surface an installed ready adapter, such as Codex, as a
runnable smoke candidate. When you intentionally want to smoke a logged-in adapter,
capd agents calibrate --execute --yes --agent <id> --json runs one bounded
capd run --agent <id> "hello" check and returns captured, truncated evidence.
The CLI stores only safe count/status metadata in the local audit log, and
/probe/data exposes safe repair-run and adapter smoke summaries as
repairHistory and calibrationHistory for the Console, compact Probe, and CI
text output.
Adding a fork-family CLI is one registry line; a brand-new headless dialect is two pure functions (build the command, translate its stream). ACP-compatible agents reuse the shared stdio JSON-RPC adapter.
The protocol
JSON-RPC 2.0 over ws://127.0.0.1:7777/ws. Browser clients authenticate with
Sec-WebSocket-Protocol: capd.auth.<base64url-token>; non-browser clients can
use Authorization: Bearer, and ?token= remains supported for older local
clients. The raw daemon token is still full-scope for backward compatibility;
console and probe URLs generated by capd console use signed, short-lived
console or probe:read scoped tokens. console is the interactive local
cockpit scope for account diagnostics plus session task control; probe:read
stays diagnostic-only. First call must be initialize (version negotiation).
| Group | Methods |
|---|---|
| agents | agents/list, agents/route, agents/usage |
| accounts | accounts/list, accounts/quota |
| session | session/create, session/list, session/attach, session/history, session/fork, session/rollback, session/close |
| task | task/send (text + image attachments), task/steer, task/cancel, task/review |
| approval | approval/reply (approve / approveAlways / deny) |
Session activity streams back as event notifications, each stamped with a
per-session monotonic seq — reconnect with session/attach {fromSeq} and
miss nothing. The unified event model (10 types: output.text with deltas,
tool.use/tool.result, approval.needed, usage.updated, task.done,
…) lives in pkg/protocol, the only public Go package and
the protocol's source of truth.
A dependency-free browser client demonstrating the full surface — agent
picker, project directory, streaming, approval buttons — is in
examples/web.
Resilience model
Any single link can die without losing a conversation:
sequenceDiagram
participant Client
participant Server as capd server
participant Session as session manager
participant DB as SQLite event log
participant Agent as agent CLI
Client->>Server: session/create
Server->>Session: create live session
Session->>Agent: start native session
Agent-->>Session: streamed events
Session-->>DB: persist seq events
Session-->>Client: event notifications
Client--xServer: disconnect
Agent-->>Session: keeps running
Session-->>DB: keeps appending events
Client->>Server: session/attach fromSeq
Server->>Session: resolve or revive
Session-->>DB: load missed events
Session-->>Client: replay + live follow
Agent--xSession: engine exits
Session-->>Client: error + task.done engineDied
Client->>Server: next touch
Session->>Agent: fresh process + native resume
- Client drops → events keep accumulating; re-attach replays from your
last
seq. - Slow watcher overflow → the daemon sends
overflow:truewith a safenextSeqreconnect hint;capd watchprintscapd watch <session-id> --from <nextSeq>so you can resume without replaying everything. - Daemon restarts → session identity and the event log live in SQLite
(
~/.capd/capd.db); the next touch revives the session and resumes the agent's native conversation. - Agent engine crashes → detected instantly on pipe EOF; sessions get an error event and revive on a fresh engine, history intact.
- WebSocket heartbeat (30 s ping) reaps dead client connections;
GET /healthz?format=jsonexposes safe aggregate runtime counters, including pending approval counts for monitors.
Security
flowchart TB
client["Client request"]
auth["daemon auth\nCAPD token\nconstant-time compare"]
origin["browser origin allowlist\nlocalhost by default"]
policy["request policy\ncwd, permission mode,\nattachments, approvals"]
headers["header guard\nno client Authorization/Cookie/X-API-Key\nCRLF rejection"]
redact["redaction\nmask secrets\nshorten account ids"]
account["account control plane\nSQLite metadata only\nno tokens"]
secret["secret plane\nSecretStore\nnative OS backend / file fallback"]
runtime["runtime projection\nper-account CODEX_HOME\nCodex app-server profile"]
upstream["agent / OpenAI upstream"]
client --> auth --> origin --> policy --> headers
headers --> redact
headers --> runtime --> upstream
account -. secret ref only .-> secret
account --> runtime
- Binds
127.0.0.1by default; remote exposure is an explicit choice (--host, TLS via your reverse proxy). - Token auth on every connection (
~/.capd/token, 0600, generated on first run); browser URLs use signed scoped tokens derived from it. - Browser
Originallowlist: localhost always, anything else via--origins/CAPD_ORIGINS— never default-open. - Sessions declare sandbox and approval policy explicitly; unknown approval requests are denied by default.
- Client-supplied sensitive headers (
Authorization,Cookie,X-API-Key,Proxy-Authorization, …) are rejected at trust boundaries. - Header values are checked for newline injection; diagnostics use redacted headers so access tokens never land in logs or protocol events.
- See docs/testing.md for standard regression, native SecretStore, and live Codex account smoke commands.
capd accounts check --jsonexercises the running daemon's CAPaccounts/checkRPC and therefore requirescapd start;capd accounts codex smokeperforms a direct local CLI smoke check without the daemon.capd accounts check --json --readinessis the recommended daemon-side shortcut for live Codex work: it refreshes quota, requires multiple accounts, requires fresh auto-route and per-account quota evidence, and requires native SecretStore by default while preserving safe partial evidence on failure.- The Web Console's ordinary diagnostic refresh is prompt-free (
accounts/listplus route evidence). Its explicitaccounts/checkreadiness gate covers multi-account, fresh-quota, and optional native SecretStore checks; that gate can refresh quota for every imported Codex account before it validates freshness. - Codex account support is split into a control plane and a runtime plane:
SQLite stores account metadata and quota snapshots, while each runtime can
use its own
CODEX_HOMEand app-server profile. capd accounts codex importcopies token material into capd's secret store, records only metadata in SQLite, and never writes back to the user's original~/.codex.- Codex owns the ChatGPT OAuth refresh flow. When Codex refreshes a
capd-managed per-account
auth.json, capd syncs the newer projected token bundle back into SecretStore before the next projection, with per-account runtime locking to avoid concurrent refresh-file races. - Secret storage defaults to the local file backend (
0600). SetCAPD_SECRET_BACKEND=nativeto use the OS secret backend where implemented; macOS stores bundles in the user Keychain, Windows uses Credential Manager, Linux uses Secret Service viasecret-tool, and unsupported platforms fail closed instead of silently falling back. - New Codex sessions can opt into an imported account with
--accountor protocolsession/create.accountId;accountId:"auto"uses conservative quota scoring. Fresh cached quota is scored by the highest pressure across primary, secondary, and code-review windows, while rows older than 30 minutes or missing quota are treated like unknown usage so stale low-usage snapshots do not dominate routing. The daemon projects that account into a dedicatedCODEX_HOME.agents/routeandaccounts/checkreturnrouteCandidatessorted by the same score rule with safereason, limiting quota-window evidence, structuredscoreInputsfor each quota window, a saferoutePolicysummary, and safesecretBackendenum for each parseable candidate.agents/route --task-classandsession/create.taskClasscan pass task intent (review,long-running,interactive, orvision);capd runand the Web Console infer a conservative task class from the prompt when task intent is left on automatic. Review tasks weightcode_reviewquota, long-running and interactive tasks weight secondary quota differently, vision tasks weight primary/secondary quota, and the selected route reason reports the active task adjustment.session/createreturns the resolvedaccountIdso clients can audit auto-route choices without another lookup. The Codex app-server profile pool keeps it isolated from other accounts.
Repository layout
| Path | Role |
|---|---|
pkg/protocol/ | CAP wire format — public contract; SDKs build against this |
internal/server/ | WebSocket, auth, dispatch, per-connection fan-out |
internal/session/ | Session registry, seq event log, SQLite store |
internal/account/ | Account metadata, quota snapshots, safe Codex header builders |
internal/adapter/ | Adapter engine + one package per agent dialect |
internal/discovery/ | Probes which CLIs are installed |
internal/proc/ | Subprocess lifecycle and line-stream plumbing |
internal/daemon/ | Hand-written assembly of all of the above |
cmd/capd/ | CLI: start, run, agents, sessions, service |
examples/web/ | Browser client demo |
Dependency direction is strictly one-way: cmd → daemon → server → session → adapter → proc; everyone may import pkg/protocol, never upward.
Development
go build ./... && go vet ./... && go test ./...
capd run --json "..." # raw event stream for debugging
The test suite covers translators (calibrated against captured real CLI streams), the session store, and a protocol-level integration suite that drives a real WebSocket server against a scripted adapter.
Status and roadmap
v0.1.0, verified end to end against live agents. Next: the inspector web console, Claude Code deep alignment (interactive approvals via its stream-json control protocol), and an out-of-process adapter SDK so the community can add agents in any language.
Self-evolution backlog for the Codex account plane:
- Readiness autopilot: turn
doctor,probe/data, andaccounts/checkfindings into ranked repair plans with exact commands, expected evidence, and a final gate to rerun. Doctor,/probe/data, and the Web Console now share the publicprotocol.RepairStepshape, the CLI has an approval-gated repair runner, and browser diagnostics classify each step as runnable or manual. The Console can dry-run the whole plan and run the ordered runnable subset through the daemonrepair/runRPC, then render pending, summary, and per-step result cards for the repair run./probe/dataand the Console also expose a safe recent repair timeline from audit metadata without commands or output; the timeline includes 5/10/20 retention controls and retry buttons that rerun the current safe repair plan. Doctor now folds installed adapter live-calibration gaps into the same token-free evolution backlog and points the next step at the dry-runcapd repair run --prompt-free --jsoncommand and the executablecapd repair run --execute --yes --prompt-free --jsoncommand, so the backlog leads directly to the bounded repair runner path. - Account-aware routing policy:
internal/account.RoutePolicynow centralizes quota freshness, unknown-score risk, recent-failure health, task class, and current-account tie-break tuning while keeping the conservative default deterministic. The Web Console exposes task intent controls for route preview and session creation. - Token health timeline: recent route decisions are now projected into
/probe/dataand the Console as saferouteHistoryfrom append-only audit metadata, without token material. Quota refreshes now also append bounded safequotaHistoryrows without raw JSON, and the Console renders per-account drift cards plus longer-horizon mini charts with latest, previous, delta, sample count, and oldest-to-newest pressure bars./probe/dataand the Console now surface non-blocking account-health alerts for recent failures and active health penalties. - SecretStore hardening: add backend migration dry-run reports, stale secret detection, and platform-specific recovery hints for macOS Keychain denial, non-interactive or missing Keychain items, Linux Secret Service/DBus failures, and Windows Credential Manager/vault failures.
- Web console operations: continue hardening one-click import/check/route
workflows over CAP with bounded timeouts, redacted logs, and downloadable
browser evidence packages. The simulated readiness gate now serves
/console/with a scoped token, verifies token cleanup/security headers, and drives task create/send/cancel over WebSocket before live UI testing. A DOM-click contract smoke also proves prompt-free diagnostic buttons and Enter-to-send wiring stay attached. - Release gates: promote live multi-account readiness into a CI-friendly selftest artifact that proves account count, fresh quotas, native SecretStore, prompt-free Web probe, and fresh auto-route selection before a live run.
- Adapter SDK boundary: move Codex-specific subprocess assumptions behind the adapter/proc boundary and prepare the same account contract for future out-of-process adapters.
The protocol specification lives in coding-agent-protocol.
License
MIT