agentproto CLI

The agentproto binary is the reference host for AgentProto agent-CLI adapters. It installs adapter packages (claude-code, claude-sdk, hermes, opencode, jcode, codex, mastra-agent, openclaw, antigravity, grok-cli, copilot-cli, …), runs them locally for a single turn or a long-lived session, exposes them as a daemon over an outbound WebSocket tunnel, and orchestrates multi-agent swarms through the runtime kernel.

This tree is tool docs — what the binary does, what flags it takes, what files it touches. For the protocol it implements, see the AIPs at https://agentproto.sh/docs.

Status: alpha. The package is pre-1.0 (0.20.0). See ../../VERSIONING.md for what the alpha guarantees and what may change between minor releases.

Three ways inCopy Anchor Link

Pick whichever matches what you're trying to do:

• Run a Claude Code (or other) session locally — getting-started.md walks through install
  • run for a single turn. For a persistent session attached to your terminal, see verbs/sessions.md.
• Share your machine with a hosted agent (a self-hosted gateway, …) — see verbs/auth.md for the device flow, then verbs/serve.md for the daemon with --connect.
• Orchestrate a multi-agent swarm — concepts/swarms.md introduces the model, verbs/run-swarm.md covers the verb.

ReferenceCopy Anchor Link

VerbsCopy Anchor Link

• agentproto app — package, unpack, or serve an agentproto app bundle (.agentapp)
• agentproto acp — manage generic ACP agents (zero-code ACP CLIs)
• agentproto adapters — manage runtime adapters (swarm-kernel substrates/dispatchers/executors)
• agentproto auth — log in to a host (RFC 8628 device flow)
• agentproto brain — fuzzy (BM25) search over a workspace's ingested session transcripts
• agentproto browser — manage browser service sessions (Camofox, Bureau, Chromium)
• agentproto chat / chat-tui — interactive REPL on a daemon agent session
• agentproto config — read/write ~/.agentproto/config.json
• agentproto conversation — locate the native transcript behind a session, or the session behind a native transcript
• agentproto cron — durable cron jobs on the daemon (command, fresh agent, or re-prompt a live session)
• agentproto daemon — install/start/restart/stop the background service
• agentproto devices — list/rename/revoke devices known to this daemon
• agentproto doctor — read-only health check of the whole install (--json for bug reports)
• agentproto install — install an adapter or a runtime profile
• agentproto install-mcp — register the daemon's MCP server with installed coding CLIs
• agentproto mcp-bridge — stdio MCP proxy to the daemon /mcp endpoint
• agentproto mcp-app — stdio MCP server scoped to one installed app's tools
• agentproto mcp — imported-MCP maintenance: move secrets to the keychain, mount imports natively per adapter
• agentproto models — list runnable models per adapter with provider-key status
• agentproto onboard — alias of the setup wizard
• agentproto pack — generate a versioned skill pack from a manifest
• agentproto pair — end-to-end pairing with a daemon over an untrusted rendezvous
• agentproto permissions — held tool-permission requests: list, approve/deny, or auto-resolve with watch rules
• agentproto policy — CLI surface for the daemon's completion-policy engine (shell/judge gates, commit + human-ack)
• agentproto review — run, verify and scaffold REVIEW.md reviews (pre-push hook + GitHub Actions shim)
• agentproto provider-preset — list provider gateway definitions + key-env status
• agentproto preset — manage saved user spawn configurations
• agentproto remote — publish this gateway (or another local port) to the internet via Cloudflare, bearer-gated
• agentproto rendezvous — self-host the untrusted pairing broker
• agentproto run — one-shot adapter turn
• agentproto run-swarm — kernel-routed multi-agent loop
• agentproto sandbox — attach to an already-existing sandbox (Box/e2b) without tearing it down
• agentproto sentinel — watch a GitHub PR/subject, deliver matching events back into a session's inbox
• agentproto serve — daemon mode (local-only or tunnelled)
• agentproto sessions — browse/start/attach/stop daemon sessions
• agentproto setup — onboarding wizard (no slug), or re-run an adapter's post-install pipeline (setup <slug>)
• agentproto task — create/list/claim/update tasks on the daemon's Task ledger
• agentproto tunnel — manage public Cloudflare/Ngrok tunnels
• agentproto usage — local-derived, provider-agnostic spend estimate over a rolling window
• agentproto workflow — start, inspect, and cancel background workflow runs on the daemon
• agentproto workspace — register local workspaces
• agentproto worktree — git worktree lifecycle (provision under worktrees.root, status-aware ls, guarded/salvage removal, gc)
• agentproto branch — branch gc: classify local/remote/orphan refs as reclaim/review/hold, reversible apply, review queue
• agentproto maintain — plan/review (and optionally apply) branch + worktree gc for a repo, via the built-in repo-maintenance app's workflow
• agentproto steward — judge idle agent sessions, then close or flag them with a recorded outcome, via the built-in session-steward app's workflow (dry run by default)

ConceptsCopy Anchor Link

• Adapters — what @agentproto/adapter-* packages are
• Plugins — extending the swarm kernel
• Roles — spawn-time delegation gate, the privilege lattice, and role packs
• Runtime profiles — runtime-profile/<name> scaffolding
• Swarms — manifest + kernel cycle model
• Credentials — how host tokens are stored
• Device fleet — driving a fleet of paired hosts from one controller: the three capabilities, bring-up, addressing, and the F1–F12 failure taxonomy
• Hooks and sandbox — the two enforcement planes (ACP semantic gate vs. OS sandbox), the 3-tier cross-harness coverage matrix, and config surfaces (.agentproto/hooks.json, .agentproto/command-sandbox.json)
• Session transcripts — structured per-session capture, event kinds, native vs daemon export

GuidesCopy Anchor Link

• Use agentproto as an MCP server inside coding CLIs — register the daemon in Claude Code, Codex, and Hermes
• Agent tools inside your app's agent — the daemon MCP tools an app's spawned agents get, and how AGENT.md shapes the spawn
• Create an agentproto app — scaffold, build, and serve an app bundle end to end
• Build your own agent app — concepts, authoring, UI, data, lifecycle, testing, and packaging, end to end
• Sandboxes and rendezvous: boot-and-drive vs. attach — connection models, keeping a box reachable, and the cost tradeoffs
• Hand off from Claude Code to Codex — checkpoint a session and continue its work on another harness, with --dry-run

File referenceCopy Anchor Link

• ~/.agentproto/config.json schema
• ~/.agentproto/credentials.json format

InstallCopy Anchor Link

npm i -g @agentproto/cli
agentproto --version
agentproto --version --check-updates   # also compare against the published version on npm

--check-updates makes one npm registry call and prints an update hint only when a newer version is published; it prints nothing extra when already current or offline. --version alone stays instant and offline — safe in scripts and CI.

Node ≥ 20.9.0. Optional node-pty for terminal sessions — npm i -g node-pty if you want agentproto sessions terminal and PTY-backed agent attach.