chorus-cli — using the chorus CLI
chorus (published as @chorus-aidlc/chorus) is the one command that configures this
machine's coding agents for Chorus and talks to the Chorus MCP endpoint from the shell.
This is a concise reference — run chorus --help and chorus <command> --help for the
full flag surface. On Hermes, run these commands with the terminal tool.
1. Install
npm install -g @chorus-aidlc/chorus # unpinned — always installs the latest
chorus --version # must be >= 0.17.0 (provides `chorus agents` + `chorus mcp`)
2. Configure agents — chorus agents
Agent configuration lives in ~/.chorus/daemon.json; chorus agents is the CRUD group:
chorus agents (or chorus agents list) — list configured agents (name, UUID, backend).
The API key is never printed; the agent named by CHORUS_AGENT_PROFILE is marked.
chorus agents add [--agents <ids>] [--all] [--url <u>] [--api-key <cho_…>] [--yes] [--dsh-profile <name>]
— detect installed coding agents, install each one's Chorus plugin, and seed credentials
(this is the former chorus init). Idempotent; safe to re-run. --help lists every flag.
For Hermes, chorus agents add --agents hermes resolves the release tag to its commit SHA,
installs both Hermes plugin directories (chorus and chorus-mcp) pinned to it with
hermes plugins install … --ref <sha> --enable, and — when CHORUS_URL is not the loopback
default — writes the native mcp_servers.chorus entry into $HERMES_HOME/config.yaml
(literal <CHORUS_URL>/api/mcp URL, header kept as the Bearer ${CHORUS_API_KEY} placeholder).
A Hermes agent is stored as offline: its presence and wakes come from the plugin's own
hermes gateway connection, not the Chorus daemon.
chorus agents remove <name|uuid> — remove a configured agent from ~/.chorus/daemon.json
(matched by UUID or name; an ambiguous name → use the UUID).
chorus agents run --name <name|uuid> [--type <type>] [--idea <uuid>] [--no-sync] [--] [agent args…] — launch a
configured agent's binary in the FOREGROUND with its Chorus connection injected into the
child only (CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE; nothing is exported to
the parent shell, and the key is never printed). Agent selection: single agent by default; else --name, else CHORUS_AGENT_PROFILE; ambiguous/none →
error. Backend defaults to the agent's stored agentType, overridable with --type.
Everything after -- is passed to the agent verbatim (never inspected). Type → binary:
claude-code/claude→claude, codex→codex, kiro→kiro-cli, pi→pi,
opencode→opencode, openclaw→openclaw, dsh→dsh. Agents added as
opencode/openclaw/dsh are stored as offline → pass --type explicitly to launch them.
Session sync (default on). Each run is registered as a Chorus daemon conversation for
that agent: the user/assistant text (no tool calls or thinking) appears live in Chorus
(Kiro uploads on exit). While the terminal run is active the conversation shows
"Running in terminal", and messages sent from Chorus are queued, never injected into
the TUI. When the run exits (or dies — the server lease expires within ~60 s), the local
chorus daemon serving the same machine + directory resumes the SAME backend
conversation and answers the queued messages. No daemon running there → one warning line
at launch; the session becomes continuable once a daemon starts in that directory.
--idea <uuid> anchors the conversation to an Idea (default: ad-hoc).
--no-sync registers nothing (zero Chorus session calls) — the plain foreground launch.
- Claude Code / Pi get a derived session id injected; passing your own session flag
after
-- (e.g. --session-id, --resume, --continue) keeps the run visible but not
continuable. Codex / TRAE / Kiro ids are discovered after launch. opencode / openclaw /
dsh are visible only (not continuable).
- Sync never blocks the agent: problems print at most one warning line; details go to
~/.chorus/logs/cli-session-sync.log (the API key is never logged).
For Hermes, check chorus agents run --help for a hermes type; otherwise start it directly
with hermes (interactive) or hermes gateway (stay online for Chorus wakes), with
CHORUS_URL / CHORUS_API_KEY in the environment or ~/.hermes/.env.
3. Connection environment variables
CHORUS_URL — the Chorus instance URL.
CHORUS_API_KEY — an agent API key (cho_…).
CHORUS_AGENT_PROFILE — optional name or UUID of the agent to act as. When set, chorus mcp
resolves that agent's key from ~/.chorus/daemon.json, so you need not export
CHORUS_API_KEY for the CLI path. Daemon-woken sessions receive it automatically.
The Chorus Hermes plugin itself does not read it: the plugin and its MCP entry use CHORUS_URL +
CHORUS_API_KEY from the environment or ~/.hermes/.env.
4. MCP operations — chorus mcp
Call any Chorus MCP tool from the shell — a byte-exact, token-free path for large content:
chorus mcp call <tool> ['<json>'] [--arg-file key=<file>] [--agent <name|uuid>] — call a tool.
--arg-file content=<file> streams a file's raw bytes into the JSON content string (no
re-typing through the model). Identity resolves from --agent → CHORUS_AGENT_PROFILE →
CHORUS_URL+CHORUS_API_KEY → a single configured agent.
chorus mcp whoami — print this agent's own UUID.
chorus mcp list — list the tools this agent may call.
Requires chorus >= 0.17.0 (the chorus mcp subcommand). See chorus mcp --help.
When chorus is not on PATH, Hermes has no bundled shell wrapper: call the native MCP tool
directly (e.g. mcp__chorus__chorus_pm_add_document_draft) with the content read from the file
via read_file.
1---2name: chorus-cli-43description: How to install, configure, and use the `chorus` CLI — install it, manage agents with `chorus agents` (add/remove/list), the connection environment variables, and MCP operations via `chorus mcp`. A concise shared reference for any Hermes flow that drives Chorus from the shell (via `terminal`).4license: AGPL-3.05metadata:6 source: https://skillmd.com/skills/chorus-aidlc/chorus-cli-47 author: chorus8 version: "0.24.1"9 category: project-management10 mcp_server: chorus11---1213# chorus-cli — using the `chorus` CLI1415`chorus` (published as `@chorus-aidlc/chorus`) is the one command that configures this16machine's coding agents for Chorus and talks to the Chorus MCP endpoint from the shell.17This is a concise reference — run `chorus --help` and `chorus <command> --help` for the18full flag surface. On Hermes, run these commands with the `terminal` tool.1920## 1. Install2122```bash23npm install -g @chorus-aidlc/chorus # unpinned — always installs the latest24chorus --version # must be >= 0.17.0 (provides `chorus agents` + `chorus mcp`)25```2627## 2. Configure agents — `chorus agents`2829Agent configuration lives in `~/.chorus/daemon.json`; `chorus agents` is the CRUD group:3031- `chorus agents` (or `chorus agents list`) — list configured agents (name, UUID, backend).32 The API key is never printed; the agent named by `CHORUS_AGENT_PROFILE` is marked.33- `chorus agents add [--agents <ids>] [--all] [--url <u>] [--api-key <cho_…>] [--yes] [--dsh-profile <name>]`34 — detect installed coding agents, install each one's Chorus plugin, and seed credentials35 (this is the former `chorus init`). Idempotent; safe to re-run. `--help` lists every flag.36 For Hermes, `chorus agents add --agents hermes` resolves the release tag to its commit SHA,37 installs both Hermes plugin directories (`chorus` and `chorus-mcp`) pinned to it with38 `hermes plugins install … --ref <sha> --enable`, and — when `CHORUS_URL` is not the loopback39 default — writes the native `mcp_servers.chorus` entry into `$HERMES_HOME/config.yaml`40 (literal `<CHORUS_URL>/api/mcp` URL, header kept as the `Bearer ${CHORUS_API_KEY}` placeholder).41 A Hermes agent is stored as `offline`: its presence and wakes come from the plugin's own42 `hermes gateway` connection, not the Chorus daemon.43- `chorus agents remove <name|uuid>` — remove a configured agent from `~/.chorus/daemon.json`44 (matched by UUID or name; an ambiguous name → use the UUID).4546- `chorus agents run --name <name|uuid> [--type <type>] [--idea <uuid>] [--no-sync] [--] [agent args…]` — launch a47 configured agent's binary in the FOREGROUND with its Chorus connection injected into the48 child only (`CHORUS_URL` / `CHORUS_API_KEY` / `CHORUS_AGENT_PROFILE`; nothing is exported to49 the parent shell, and the key is never printed). Agent selection: single agent by default; else `--name`, else `CHORUS_AGENT_PROFILE`; ambiguous/none →50 error. Backend defaults to the agent's stored `agentType`, overridable with `--type`.51 Everything after `--` is passed to the agent **verbatim** (never inspected). Type → binary:52 `claude-code`/`claude`→`claude`, `codex`→`codex`, `kiro`→`kiro-cli`, `pi`→`pi`,53 `opencode`→`opencode`, `openclaw`→`openclaw`, `dsh`→`dsh`. Agents added as54 opencode/openclaw/dsh are stored as `offline` → pass `--type` explicitly to launch them.5556 **Session sync (default on).** Each run is registered as a Chorus daemon conversation for57 that agent: the user/assistant text (no tool calls or thinking) appears live in Chorus58 (Kiro uploads on exit). While the terminal run is active the conversation shows59 "Running in terminal", and messages sent from Chorus are **queued**, never injected into60 the TUI. When the run exits (or dies — the server lease expires within ~60 s), the local61 `chorus daemon` serving the **same machine + directory** resumes the SAME backend62 conversation and answers the queued messages. No daemon running there → one warning line63 at launch; the session becomes continuable once a daemon starts in that directory.64 - `--idea <uuid>` anchors the conversation to an Idea (default: ad-hoc).65 - `--no-sync` registers nothing (zero Chorus session calls) — the plain foreground launch.66 - Claude Code / Pi get a derived session id injected; passing your own session flag67 after `--` (e.g. `--session-id`, `--resume`, `--continue`) keeps the run visible but not68 continuable. Codex / TRAE / Kiro ids are discovered after launch. opencode / openclaw /69 dsh are visible only (not continuable).70 - Sync never blocks the agent: problems print at most one warning line; details go to71 `~/.chorus/logs/cli-session-sync.log` (the API key is never logged).72 For Hermes, check `chorus agents run --help` for a `hermes` type; otherwise start it directly73 with `hermes` (interactive) or `hermes gateway` (stay online for Chorus wakes), with74 `CHORUS_URL` / `CHORUS_API_KEY` in the environment or `~/.hermes/.env`.7576## 3. Connection environment variables7778- `CHORUS_URL` — the Chorus instance URL.79- `CHORUS_API_KEY` — an agent API key (`cho_…`).80- `CHORUS_AGENT_PROFILE` — optional name or UUID of the agent to act as. When set, `chorus mcp`81 resolves that agent's key from `~/.chorus/daemon.json`, so you need not export82 `CHORUS_API_KEY` for the CLI path. Daemon-woken sessions receive it automatically.83 The Chorus Hermes plugin itself does not read it: the plugin and its MCP entry use `CHORUS_URL` +84 `CHORUS_API_KEY` from the environment or `~/.hermes/.env`.8586## 4. MCP operations — `chorus mcp`8788Call any Chorus MCP tool from the shell — a byte-exact, token-free path for large content:8990- `chorus mcp call <tool> ['<json>'] [--arg-file key=<file>] [--agent <name|uuid>]` — call a tool.91 `--arg-file content=<file>` streams a file's raw bytes into the JSON `content` string (no92 re-typing through the model). Identity resolves from `--agent` → `CHORUS_AGENT_PROFILE` →93 `CHORUS_URL`+`CHORUS_API_KEY` → a single configured agent.94- `chorus mcp whoami` — print this agent's own UUID.95- `chorus mcp list` — list the tools this agent may call.9697Requires `chorus >= 0.17.0` (the `chorus mcp` subcommand). See `chorus mcp --help`.9899When `chorus` is not on PATH, Hermes has no bundled shell wrapper: call the native MCP tool100directly (e.g. `mcp__chorus__chorus_pm_add_document_draft`) with the content read from the file101via `read_file`.