tools, agents & acp
MCP server introspection, the ACP agent catalog, and the per-session ACP substrate.
The command surfaces behind the Tools and Agents gateways: tools introspects the MCP upstreams declared under mcp_servers, agents manages the ACP agent catalog, and acp runs per-session headless agent sessions.
bitrouter tools
MCP server introspection — list/status/discover against the upstreams declared under mcp_servers in bitrouter.yaml. v1.0 does not maintain a global tool registry; these are one-shot queries
Usage: bitrouter tools [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter tools list
List tools advertised by every configured MCP server
Usage: bitrouter tools list [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter tools status
Health-check every configured MCP server with a tools/list round-trip
Usage: bitrouter tools status [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter tools discover
Connect to one MCP server and print a YAML stub suitable for pasting into mcp_servers:
Usage: bitrouter tools discover [OPTIONS] <SERVER>
Arguments
| Argument | Description |
|---|---|
<SERVER> | Server id (must exist under mcp_servers in the config) |
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
Probes each configured MCP server and reports the tools it actually exposes — the debugging step when a tool isn't reaching the model.
bitrouter agents
ACP agent lifecycle — list the catalog, check configured agents, print install stubs
Usage: bitrouter agents [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter agents list
Show the bundled catalog of well-known agents and which of them are present under agents: in the loaded config. With --remote, also fetch and list the official ACP agent registry
Usage: bitrouter agents list [OPTIONS]
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--remote | Also fetch the ACP agent registry (cdn.agentclientprotocol.com) and list its agents |
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter agents check
Spawn each configured agent and verify it answers initialize
Usage: bitrouter agents check [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml. When omitted, the binary resolves in this order: ./bitrouter.yaml → $BITROUTER_HOME/bitrouter.yaml → ~/.bitrouter/bitrouter.yaml → zero-config in-memory defaults (bitrouter init is the explicit way to scaffold a file) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
Spawns each configured agent and verifies it responds to initialize, printing latency or the error per agent.
bitrouter agents install
Print a YAML stub for an agent (paste under agents: in bitrouter.yaml). Resolves from the bundled catalog first, then the ACP registry (npx/uvx distributions only)
Usage: bitrouter agents install [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | Agent id (see bitrouter agents list / list --remote) |
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter acp
Per-session ACP substrate — headless agent session management.
serve exposes one agent session as a vanilla ACP Agent over stdio. prompt launches a session, sends one prompt, and streams NDJSON output.
Usage: bitrouter acp [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter acp serve
Serve one agent session as a vanilla ACP Agent over stdio until the manager disconnects. Intended for GUIs and orchestrating agents that speak ACP directly
Usage: bitrouter acp serve [OPTIONS] --agent <AGENT>
Options
| Flag | Description |
|---|---|
--agent <AGENT> | Agent id — must exist under agents: in the config |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--worktree <WORKTREE> | Name of a git worktree to provision inside the repo before launching (created, or reused when it already exists). When omitted the session runs in the current directory |
--rm-worktree | Remove the worktree when the session ends. Off by default: the worktree holds the agent's work, and removal discards anything uncommitted. Only a worktree created by this session is removed |
--no-transcript | Disable the durable session transcript (.bitrouter/sessions/<id>.transcript.ndjson, on by default) |
--turn-timeout <SECS> | Per-turn deadline in seconds. On elapse the agent is asked to cancel cooperatively; a turn that still doesn't finish errors |
--warm | Keep the session alive after the manager disconnects and accept reattach connections on .bitrouter/sessions/<record_id>.sock (same stdio JSON-RPC framing over a unix socket; reconnect with bitrouter acp attach <record> and rejoin history via session/load). Unix-only |
--idle-timeout <SECS> | Shut a warm session down after this many seconds with no manager attached [default: 1800] |
--direct | Do NOT route the sub-agent's LLM traffic through the daemon — let the harness use its own provider auth. Routing is on by default |
--base-url <BASE_URL> | Override the gateway base URL (else derived from server.listen) |
--model <MODEL> | Pin the harness's model (via its model env var / -c model=) |
--no-start | Never auto-start a local daemon when none is running — fail fast |
-c, --config <CONFIG> | Path to bitrouter.yaml. Resolves via the standard chain when omitted: ./bitrouter.yaml → $BITROUTER_HOME → ~/.bitrouter/bitrouter.yaml → zero-config defaults |
Exposes one agent session as a vanilla ACP Agent over stdio — how a parent agent delegates to a BitRouter-managed sub-agent.
bitrouter acp prompt
Launch a session, send one prompt, and stream NDJSON output to stdout.
Each streamed agent update is emitted as one JSON object per line with a type field (e.g. message_chunk, tool_call). The final line has type: result with a stop_reason field.
Usage: bitrouter acp prompt [OPTIONS] --agent <AGENT> <TEXT>
Arguments
| Argument | Description |
|---|---|
<TEXT> | The prompt text to send |
Options
| Flag | Description |
|---|---|
--agent <AGENT> | Agent id — must exist under agents: in the config |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--worktree <WORKTREE> | Name of a git worktree to provision inside the repo before launching (created, or reused when it already exists) |
--rm-worktree | Remove the worktree when the session ends. Off by default: the worktree holds the agent's work, and removal discards anything uncommitted. Only a worktree created by this session is removed |
--no-transcript | Disable the durable session transcript (.bitrouter/sessions/<id>.transcript.ndjson, on by default) |
--turn-timeout <SECS> | Per-turn deadline in seconds. On elapse the agent is asked to cancel cooperatively; a turn that still doesn't finish errors |
--no-wait | Return immediately after submitting the prompt (emit {"type":"submitted"}). The session is torn down after ack |
--direct | Do NOT route the sub-agent's LLM traffic through the daemon — let the harness use its own provider auth. Routing is on by default |
--base-url <BASE_URL> | Override the gateway base URL (else derived from server.listen) |
--model <MODEL> | Pin the harness's model (via its model env var / -c model=) |
--no-start | Never auto-start a local daemon when none is running — fail fast |
-c, --config <CONFIG> | Path to bitrouter.yaml. Resolves via the standard chain when omitted: ./bitrouter.yaml → $BITROUTER_HOME → ~/.bitrouter/bitrouter.yaml → zero-config defaults |
bitrouter acp sessions
List the session records under the current repo's .bitrouter/sessions/, newest first. A running record whose process no longer exists is shown as dead
Usage: bitrouter acp sessions [OPTIONS]
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter acp attach
Reattach to a warm session: bridge this terminal's stdio to the session's unix socket. Speak ACP as usual; session/load replays the conversation so far. Unix-only
Usage: bitrouter acp attach [OPTIONS] <RECORD>
Arguments
| Argument | Description |
|---|---|
<RECORD> | Session record id (or unique prefix) from bitrouter acp sessions |
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
How is this guide?