chorus CLI

chorus コマンド（@chorus-aidlc/chorus として公開）は 3 つの役割を担います。Chorus サーバーを 実行し、マシン上のコーディングエージェントを設定し、シェルから Chorus の MCP エンドポイントを 呼び出します。グローバルにインストールします。

npm install --global @chorus-aidlc/chorus
chorus --version

完全なフラグ一覧は、chorus --help または chorus <command> --help を実行してください。

コマンド一覧

コマンド	何をするか
chorus	Chorus サーバーを起動します（サブコマンドなしの既定）。Docker でデプロイを参照。
chorus upgrade / chorus update	npm グローバル CLI を更新。--plugins で設定済み Chorus プラグインも更新。
chorus agents	このマシンのエージェントを設定します — list（既定）、add、remove、そして run（1 つ起動）。
chorus mcp	ネイティブ MCP クライアント — ツールを call し、自分の UUID を表示（whoami）し、呼び出せるツールを list します。
chorus login	エージェントとして認証し、接続を ~/.chorus/daemon.json に保存します。
chorus daemon	Chorus が起動できるようにランタイムをオンラインに保ちます。Chorus デーモンを運用するを参照。

0.17.0 での名称変更

chorus init は chorus agents add になりました（フラグは同じ）。エージェントごとの install-*.sh スクリプトは廃止され、いまは chorus agents add を案内するだけになっています。

CLI とプラグインを更新する

Chorus 0.20.0 から次のコマンドを使えます。

chorus upgrade             # CLI のみ
chorus upgrade --plugins   # CLI、続いて設定済みの Chorus プラグイン
chorus update --plugins    # upgrade の別名

このコマンドは @chorus-aidlc/chorus を npm でグローバルインストール した場合にのみ使えます。npm の最新安定版を確認し、現在のインストールと同じ npm prefix 内で更新したうえで、インストールされたバージョンを検証します。すでに同じか新しいバージョンなら再インストールもダウングレードもしませんが、--plugins は実行します。ソースのチェックアウト、リンク、他のパッケージマネージャーによるインストールには対応しません。このコマンドがない旧 CLI では、先に npm install --global @chorus-aidlc/chorus@latest で新版を導入してください。

--plugins の更新対象

~/.chorus/daemon.json を読み、種別が Claude Code、Codex、Kiro、Pi と明示されたエージェント設定を処理します。デーモン起動が無効な設定も対象です。各設定の env、PATH、独自の設定ホームから更新先を決めます。共有の更新先は一度だけ、異なるホームは個別に処理します。現時点では既定のファイルだけを読み、CHORUS_DAEMON_CONFIG_PATH は参照しません。

• Claude Code と Codex：ホストのプラグイン機構で Chorus プラグインを更新します。
• Kiro：設定された Chorus インスタンスからテンプレートを取得します。新版テンプレートを取得するには、先にそのサーバーを更新してください。一つの共有の更新先に異なるインスタンス URL が指定されている場合は、未完了として報告されます。
• Pi：安定版 >=0.99.0 <2.0.0 はネイティブ MCP を使い、対象の @chorus-aidlc/chorus-pi のみ更新します。0.84.4–0.98.x は検証済み pi-mcp-adapter@5.0.0 の固定を保持します。他のアダプター制約や Chorus の固定版・範囲・タグも保持するため、設定や最新版への更新が未完了になる場合があります。全拡張や Pi 本体の更新、既存アダプターの自動削除は行いません。Pi の設定と移行を参照してください。

ホスト CLI がインストールされていて Chorus プラグインがない場合は、プラグインをインストールします。登録情報と認証情報は保持し、ホスト CLI 自体のインストールや更新は行いません。設定ファイルを変更する前に、そのコピーを <file>.chorus-upgrade.bak として保存します（次回の更新で上書きされます）。種別が offline または未知の場合（既定の OpenCode、OpenClaw、dsh の設定を含む）や、各設定の PATH にホスト CLI がない場合はスキップし、INCOMPLETE と表示します。これらのホストについては、エージェントプラットフォームにある設定・更新手順に従ってください。

完了状態と反映

コマンドは対話なしで動きます。終了コード 0 は全処理の完了、1 は失敗または未完了です。デーモンファイルがない場合やエージェント一覧が空の場合は、更新対象がないため成功として扱います。読み取れないファイルや形式が不正なファイルは失敗になります。CLI の更新に失敗するとプラグイン処理は行いません。個別のプラグインが失敗しても後続は処理し、完了した更新は保持します。自動ロールバックはありません。

npm のインストールは進捗を表示し、インストールのタイムアウトは設けません。失敗時は表示された npm エラーを確認してください。EACCES や EPERM なら、ユーザー所有の Node を使うか、管理者にシステムの npm prefix の更新を依頼します。Chorus は自動昇格しません。更新後は新しいエージェントセッションを開始し、都合のよい時に chorus daemon restart を実行してください。デーモンや実行中のセッションは自動再起動されません。

エージェントを設定する — chorus agents

chorus agents add は、マシンのコーディングエージェントを Chorus に接続する唯一のコマンドです。 すでにインストールしているエージェントを検出し、それぞれの Chorus プラグインをそのエージェント自身の プラグイン機構を通じてインストールし、Chorus の URL と API キーを一度だけ ~/.chorus/daemon.json に取り込みます。Claude Code、Codex、Hermes、DeepSeek Harness については、認証情報を そのエージェント自身の設定にも書き込むため、対話的なセッションが手動の環境設定なしで認証されます （認証情報の保存先を参照）。

chorus agents add                     # interactive: detect, pick, configure
chorus agents add --all --yes         # configure every detected agent, no prompts
chorus agents add --agents claude,codex \
  --url https://chorus.example.com --api-key cho_xxx

設定はエージェント追加や認証情報更新のために再実行できます。Claude Code、Codex、Kiro、Pi、OpenCode、OpenClaw、Hermes、DeepSeek Harness（dsh）に対応します。Pi 安定版 >=0.99.0 <2.0.0 はネイティブ MCP、0.84.4–0.98.x は pi-mcp-adapter@5.0.0 を選び、chorus-pi もインストールします。Pi が未導入、非対応、バージョン不明の場合は案内を表示し、一律に MCP 設定完了とは報告しません。Piを参照してください。

主なフラグ（全フラグは chorus agents add --help で確認できます）。

• --agents <a,b> / --all — どのエージェントを設定するか。
• --url / --api-key — 認証情報を非対話的に指定します（環境変数：CHORUS_URL / CHORUS_API_KEY）。
• --update-installed — 既存のインストールを更新します。Pi では pi update --extensions を実行します。 pi install の繰り返しだけではインストール済みパッケージは更新されません。
• --dsh-profile <name> — バンドルをインストールする DeepSeek Harness のプロファイル。
• --daemon-wake <a,b> / --daemon-wake-all — 指定したエージェント（または起動できるすべてのエージェント）をデーモンの起動対象にします。起動できるエージェント（Claude Code、Codex、Kiro、Pi）は既定で「パーク」状態で追加されます。chorus mcp からは到達できますが、ここで明示的に選ぶ（または TTY で各エージェントのプロンプトに答える）まではデーモンに起動されません。
• --daemon-autostart — デーモンの起動サービスもインストールして有効化します（Linux systemd / macOS launchd）。
• --no-linger：Linux systemd lingering の設定・修復を省略します。既存設定は無効にしません。デーモン運用を参照してください。
• -y, --yes — 確認をスキップします（TTY でないときは暗黙的に有効になり、その場合は --agents または --all を渡す必要があります）。

設定済みのエージェントを一覧・削除します。

chorus agents                     # list configured agents (name, UUID, backend)
chorus agents remove <name|uuid>  # remove one (match by name or UUID)

chorus agents は API キーを決して出力しません。一覧に表示された名前または UUID は、 chorus mcp --agent や CHORUS_AGENT_PROFILE 環境変数の有効な値です。

Codex の App Server 再起動は --yes では許可されません。認証情報と MCP 設定に成功した後、対話型端末だけで中断の警告と個別確認を表示します。Codexを参照してください。

Hermes の設定（0.22.0）

chorus agents add --agents hermes --hermes-cwd /path/to/repo は CLI のリリースタグから chorus と chorus-mcp をインストールし、$HERMES_HOME/.env、リポジトリ、未設定の承認項目を構成します。--hermes-cwd <path> が優先され、省略時は既存ディレクトリか現在の Git リポジトリを使います。タグがなければ失敗します。

Hermes は Chorus daemon では offline 登録です。chorus upgrade --plugins と chorus agents run --type hermes は対応しません。CLI 更新後、chorus agents add --agents hermes で両方を再インストールし、hermes gateway restart を実行します。リリースタグでのインストール、リモート MCP、スキル、所有者承認は Hermes Agent を参照してください。

エージェントを起動する — chorus agents run

chorus agents run は、設定済みのエージェントを Chorus 接続を組み込んだ状態でターミナル内に 起動します（デーモン起動のフォアグラウンド版）。子プロセスは親シェルの環境を変更できないため、 このコマンドは接続を起動するエージェントプロセスへ直接注入します。手動でエクスポートする必要は ありません。

chorus agents run --name work -- --model opus        # エージェント "work" を起動し、--model opus を渡す
chorus agents run                                    # 設定済みエージェントが 1 つだけならそれを起動
chorus agents run --name work --type codex -- resume # バックエンドを上書きし、`resume` を透過的に渡す

• どのエージェントか — --name <name|uuid> が ~/.chorus/daemon.json の agents[] から選びます。エージェントが 1 つだけなら省略可能です。複数ある場合は --name を渡す（または CHORUS_AGENT_PROFILE を設定する） 必要があり、そうしないとコマンドは推測せずエラーになります。
• 何が注入されるか（起動されたプロセスにのみ注入され、シェルには入らず、出力もされません）： CHORUS_URL、CHORUS_API_KEY、CHORUS_AGENT_PROFILE。
• どのバイナリか — 既定はエージェントに保存されたバックエンドで、--type で上書きできます。 種類はそれぞれ claude、codex、kiro-cli、pi、opencode、openclaw、dsh に 対応します。OpenCode / OpenClaw / DeepSeek Harness として追加したエージェントは offline として 保存される（デーモンが自動起動しない）ため、起動するには --type を明示してください。
• 透過渡し — -- の後のすべてはそのままエージェントへ渡されるため、すべてのフラグが利用できます。 エージェントはあなたのターミナルを引き継ぎ、chorus agents run はその終了コードで終了します。

永続的な args/env と一度きりの上書き

選択した agents[] の各エントリには args（文字列配列、既定値 []）と env（キーも値も文字列のオブジェクト、既定値 {}）を設定でき、デーモンによる起動とフォアグラウンドでの起動の両方で使われます。agents[] が空でない場合、各エントリはトップレベルの args / env を継承せず、トップレベルに設定するとエラーになります。コピーして使えるモデル/思考/env の例、フラットファイルからの移行、検証、シークレットの取り扱いの注意点はデーモンガイドを参照してください。

値はリテラルとして扱われ、シェル展開、dotenv の読み込み、シークレットの参照は行いません。env は起動されるエージェントだけに適用されます。CHORUS_* と、Claude Code のネスト検出用の変数 CLAUDECODE / CLAUDE_CODE_ENTRYPOINT は（大文字小文字を区別せず）予約済みで、設定すると黙って除外されるのではなくエラーになります。永続引数では Chorus が管理するオプション（セッション、プロンプト、プロトコル、作業ディレクトリ、MCP、権限の制御）を上書きできず、-- / - の区切りや、ヘルプやバージョン情報を表示して終了するだけのフラグも含められません。起動時に明示的に渡した引数は、ネイティブの再開コマンドも含めてそのまま転送されます。これらの検査は既知の衝突を防ぐためのもので、サンドボックスではありません。

新しい chorus agents run は毎回ファイルを読み直します。デーモンが変更を反映するのは chorus daemon restart の後です。どちらの場合も、すでに実行中のエージェントには影響しません。--type は検証と上書き判定に使うバックエンドを選びますが、バックエンドのフラグを変換しません。

次のオプションに限り、選択したコマンドのスコープで明示的に指定すると、設定済みの同じオプションとその値が置き換えられます。

実効バックエンド	認識する上書き
claude-code / claude	--model、--effort
codex	--model / -m / 設定キー model、設定キー model_reasoning_effort
kiro	--model、--effort
pi	--model、--thinking、--provider
opencode	--model / -m
openclaw	agent の --model、--thinking（-m はメッセージでありモデルではありません）
dsh	なし。代わりに env の DSH_PROVIDER / DSH_MODEL を使います

判定は --option value、--option=value、表に -m がある場合の -mVALUE / -m=VALUE に対応します。Codex は -c key=value、-ckey=value、-c=key=value、--config key=value、--config=key=value に対応します。優先順位処理の対象は表の 2 つのキーだけで、無関係な設定は残ります。バックエンド自身もその表記に対応している必要があります。Pi 0.85.1 の --model、--thinking、--provider では等号形式ではなく値を分けて渡してください。

chorus agents run --name pi-worker -- --model anthropic/claude-sonnet-4-6 --thinking medium
chorus agents run --name codex-worker -- exec --model gpt-5.4 -c model_reasoning_effort=high

サブコマンド：永続引数は最も深い認識済みコマンドの後に入ります。対象は Codex の exec、exec resume、resume、Kiro の chat、OpenClaw の agent です。明示的な上書きも同じスコープに置いてください。--model chosen exec ではなく exec --model chosen とします。サブコマンドより前に置いたモデル指定は、サブコマンドの設定済みモデルを置き換えません。Codex の -c/--config キーはスコープをまたいで適用されます。認識されたコマンドがなければ、設定引数を先頭に置きます。その他のコマンドパスは推測しないため、そのようなパスでは互換性のない永続引数を外し、ネイティブの引数渡しを使ってください。

未知のオプション：永続 args は通常の未知フラグを受け付けますが、次の要素が値かプロンプトかは推測できません。バックエンドが対応していれば ["--future=value"] を使い、["--future", "value"] は避けてください。既知のオプションには必要な値を指定します。未知のオプションや繰り返し可能なオプションは、選択スコープ内で順序が保たれます（設定済みのものが先、明示したものが後）。一般的な後勝ちは保証されません。曖昧な明示オプション（インライン値のない未知のオプション）があると、Chorus はそれ以降の上書きを探しません。既知の上書きをその前に置くか、対応するインライン値を使ってください。外側の Chorus 区切りを除去した後、エージェント引数内の最初の単独 -- でも解析を停止します。コマンド探索は位置引数のプロンプト、未知コマンド、曖昧なオプションで止まり、既知のオプション値を飛ばします。明示的な引数はすべてそのまま転送されるため、バックエンドのフラグやバージョンとの互換性は自分で確認してください。Windows .cmd/.bat の制限はデーモンガイドを参照してください。

Codex デーモンでは、永続引数がさらにモデル指定と許可された -c / --config の上書きに限定されます。それ以外のフラグは、フォアグラウンドのセッションで動作するものであっても、デーモンがエージェントを起動する前にエラーになります。Codex デーモンの設定を参照してください。

シェルから MCP ツールを呼び出す — chorus mcp

chorus mcp はネイティブ MCP クライアントで、スクリプトやターミナルから任意の Chorus ツールを 呼び出す、モデルのトークンを消費しない経路です。以前の chorus-api.sh / chorus-mcp-call.sh ラッパーを置き換えます。

chorus mcp call <tool> '<json>'                  # call a tool with a JSON argument object
chorus mcp call <tool> --arg key=value           # set one string argument
chorus mcp call <tool> --arg-file content=<path> # stream a file's raw bytes into an argument
chorus mcp whoami                                 # print this agent's own UUID
chorus mcp list                                   # list the tools this agent may call

--arg-file は、大きな内容（文書の本文や OpenSpec ファイル）をモデルで打ち直させることなく ツールへ届けるための手段です。成功すると、chorus mcp call はツールの結果をそのまま stdout に 出力します。ツールまたはトランスポートのエラーは、非ゼロの終了コードとともに stderr に出力されます。

どのエージェントとして動作するかは、次の順序で解決されます。--agent <name|uuid> → 明示的な --url + --api-key フラグ → CHORUS_AGENT_PROFILE → CHORUS_URL + CHORUS_API_KEY → 設定済みエージェントが 1 つだけのときはそのエージェント。

接続の環境変数

変数	意味
CHORUS_URL	Chorus インスタンスの URL。
CHORUS_API_KEY	エージェントの API キー（cho_…）。
CHORUS_AGENT_PROFILE	どの設定済みエージェントとして動作するか（名前または UUID、任意）。設定すると、chorus mcp は ~/.chorus/daemon.json からそのエージェントのキーを読むため、CHORUS_API_KEY をエクスポートする必要がありません。

デーモンが起動したセッションは CHORUS_AGENT_PROFILE を自動的に受け取ります。手動で設定するのは、 特定の設定済みエージェントとして振る舞わせたい対話的なシェルの場合だけです。

認証情報の保存先

chorus agents add は、検証済みの認証情報を常に ~/.chorus/daemon.json に書き込みます （モード 0600。キーがエコー表示されることはありません）。4 つのエージェントについては、 対話的なセッションが手動のエクスポートなしで認証されるよう、そのエージェント自身の設定にも 認証情報を埋め込みます。

エージェント	追加の認証情報の保存先
Claude Code	~/.claude/settings.json の env ブロック（CLAUDE_CONFIG_DIR に従う）。
Codex	~/.codex/.env（CODEX_HOME に従う）。Codex はキーレスの config.toml エントリを通じて、環境変数からキーを読みます。
DeepSeek Harness	$DSH_HOME/.env。
Hermes	$HERMES_HOME/.env（既定は ~/.hermes/.env、モード 0600）。リモート MCP 設定はキーのプレースホルダーを保存します。

Kiro、OpenCode、OpenClaw は、それぞれ自身のインストール済みの設定から認証情報を読みます。 デーモンが起動した Kiro は、デーモンが起動のたびにエクスポートする環境変数から読みます。

エージェント向け

• トリガー。 このページに来るのは、CLI をインストールまたはアップグレードするため、エージェントを 設定するため（chorus agents add）、あるいはシェルから Chorus ツールを呼び出すため （chorus mcp call）です。
• 制約。 文書ミラーやその他の大きな内容の呼び出しには、chorus mcp call <tool> '<json>' --arg-file content=<file> を優先してください。chorus が PATH にないときにのみ、chorus-api.sh / chorus-mcp-call.sh に フォールバックします。API キーをコマンドラインやシェル履歴に決して貼り付けず、 chorus agents add / chorus login に取り込ませてください。
• 出典。 正確なフラグ一覧については、chorus --help と chorus <command> --help を実行してください。 常にインストール済みのバージョンと一致します。

関連

• エージェントランタイムを接続する — 手順を追ったセットアップの解説。
• Chorus デーモンを運用する — ランタイムをオンラインに保つ。
• MCP ツールカタログ — chorus mcp が呼び出すツールのカタログ。