convez.ai
AgenteDevOps & InfraestruturaAvançado
codingagentprotocol

capd — Daemon do Protocolo de Agentes de Código

codingagentprotocol/capd

Protocolo unificado para controlar múltiplos agentes de código

Ver no GitHub
InicialPluginScore · de 0 a 100

capd é 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/capd

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 5 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
2

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

ModeMeaning (codex mapping)
defaultread-only sandbox; every write needs an approval
acceptEditsworkspace-write; actions outside the workspace need approval
fullno sandbox, no prompts — you opted in

capd sets these explicitly per session and never silently inherits a permissive user config.

Supported agents

AgentModeStreamingApprovalsSteerFork/RollbackUsage data
Codex CLIapp-server engine✅ deltas✅✅✅✅
Claude Codeheadless execblock————
OpenCodeheadless exec; live smoke hint after install/loginblock————
Xiaomi MiMo Codeopencode-family translator; discovered as mimo-code when mimo is installed; live smoke hint after install/loginblock————
Gemini CLIheadless execlogin + live calibration recommended
Cursor CLIheadless execlogin + live calibration recommended
Qwen Code, iFlowgemini-family translators; discovered when installed; live calibration recommended
CodeBuddyclaude-family translator; discovered when installed; live smoke hint after install/login
Kimi CLIACP 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).

GroupMethods
agentsagents/list, agents/route, agents/usage
accountsaccounts/list, accounts/quota
sessionsession/create, session/list, session/attach, session/history, session/fork, session/rollback, session/close
tasktask/send (text + image attachments), task/steer, task/cancel, task/review
approvalapproval/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:true with a safe nextSeq reconnect hint; capd watch prints capd 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=json exposes 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.1 by 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 Origin allowlist: 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 --json exercises the running daemon's CAP accounts/check RPC and therefore requires capd start; capd accounts codex smoke performs a direct local CLI smoke check without the daemon.
  • capd accounts check --json --readiness is 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/list plus route evidence). Its explicit accounts/check readiness 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_HOME and app-server profile.
  • capd accounts codex import copies 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). Set CAPD_SECRET_BACKEND=native to use the OS secret backend where implemented; macOS stores bundles in the user Keychain, Windows uses Credential Manager, Linux uses Secret Service via secret-tool, and unsupported platforms fail closed instead of silently falling back.
  • New Codex sessions can opt into an imported account with --account or protocol session/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 dedicated CODEX_HOME. agents/route and accounts/check return routeCandidates sorted by the same score rule with safe reason, limiting quota-window evidence, structured scoreInputs for each quota window, a safe routePolicy summary, and safe secretBackend enum for each parseable candidate. agents/route --task-class and session/create.taskClass can pass task intent (review, long-running, interactive, or vision); capd run and the Web Console infer a conservative task class from the prompt when task intent is left on automatic. Review tasks weight code_review quota, 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/create returns the resolved accountId so clients can audit auto-route choices without another lookup. The Codex app-server profile pool keeps it isolated from other accounts.

Repository layout

PathRole
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, and accounts/check findings 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 public protocol.RepairStep shape, 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 daemon repair/run RPC, then render pending, summary, and per-step result cards for the repair run. /probe/data and 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-run capd repair run --prompt-free --json command and the executable capd repair run --execute --yes --prompt-free --json command, so the backlog leads directly to the bounded repair runner path.
  • Account-aware routing policy: internal/account.RoutePolicy now 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/data and the Console as safe routeHistory from append-only audit metadata, without token material. Quota refreshes now also append bounded safe quotaHistory rows 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/data and 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

Ver o original no GitHub

Bom para

Relacionados