opencode

OpenCode CLI

OpenCode を Hermes のターミナル／プロセスツールでオーケストレーションされる自律型コーディングワーカーとして使用します。OpenCode は、TUI と CLI を備えた、プロバイダーに依存しないオープンソースの AI コーディングエージェントです。

使用する場面

• ユーザーから OpenCode の使用を明示的に求められた場合
• 外部のコーディングエージェントにコードの実装、リファクタリング、レビューを任せたい場合
• 進捗を確認しながら、長時間のコーディングセッションを行う必要がある場合
• 分離された作業ディレクトリ／ワークツリーで、タスクを並行して実行したい場合

前提条件

• OpenCode がインストールされていること：npm i -g opencode-ai@latest または brew install anomalyco/tap/opencode
• 認証が設定されていること：opencode auth login を実行するか、プロバイダーの環境変数（OPENROUTER_API_KEY など）を設定します
• 確認方法：opencode auth list に少なくとも 1 つのプロバイダーが表示されること
• コードの作業には Git リポジトリを用意すること（推奨）
• インタラクティブな TUI セッションでは pty=true を指定すること

バイナリの解決（重要）

シェル環境によって、異なる OpenCode バイナリが解決される場合があります。ターミナルと Hermes で動作が異なる場合は、次を確認してください。

terminal(command="which -a opencode")
terminal(command="opencode --version")

必要に応じて、明示的なバイナリパスを固定します。

terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)

単発タスク

範囲が限定された非インタラクティブなタスクには、opencode run を使用します。

terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")

-f でコンテキストファイルを添付します。

terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")

--thinking でモデルの思考を表示します。

terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")

特定のモデルを指定します。

terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")

インタラクティブセッション（バックグラウンド）

複数回のやり取りが必要な作業では、TUI をバックグラウンドで起動します。

terminal(command="opencode", workdir="~/project", background=true, pty=true)
# Returns session_id

# Send a prompt
process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send follow-up input
process(action="submit", session_id="<id>", data="Now add error handling for token expiry")

# Exit cleanly — Ctrl+C
process(action="write", session_id="<id>", data="\x03")
# Or just kill the process
process(action="kill", session_id="<id>")

重要： /exit は有効な OpenCode コマンドではなく、代わりにエージェント選択ダイアログが開くため、使用しないでください。終了するには Ctrl+C（\x03）または process(action="kill") を使用します。

TUI のキーバインド

キー	操作
Enter	メッセージを送信します（必要に応じて 2 回押します）
Tab	エージェント（build／plan）を切り替えます
Ctrl+P	コマンドパレットを開きます
Ctrl+X L	セッションを切り替えます
Ctrl+X M	モデルを切り替えます
Ctrl+X N	新しいセッションを開始します
Ctrl+X E	エディターを開きます
Ctrl+C	OpenCode を終了します

セッションの再開

終了後、OpenCode にセッション ID が表示されます。次のコマンドで再開します。

terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # Continue last session
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # Specific session

よく使うフラグ

フラグ	用途
run 'prompt'	単発で実行して終了します
--continue / -c	直前の OpenCode セッションを続行します
--session <id> / -s	指定したセッションを続行します
--agent <name>	OpenCode エージェント（build または plan）を選択します
--model provider/model	特定のモデルを指定します
--format json	機械可読形式で出力／イベントを表示します
--file <path> / -f	メッセージにファイルを添付します
--thinking	モデルの思考ブロックを表示します
--variant <level>	推論の強度（high、max、minimal）を指定します
--title <name>	セッションに名前を付けます
--attach <url>	実行中の opencode サーバーに接続します

手順

1. ツールが使用可能か確認します。
   • terminal(command="opencode --version")
   • terminal(command="opencode auth list")
2. 範囲が限定されたタスクには、opencode run '...' を使用します（pty は不要です）。
3. 繰り返しのやり取りが必要なタスクでは、background=true, pty=true を指定して opencode を起動します。
4. 長時間のタスクは process(action="poll"|"log") で監視します。
5. OpenCode から入力を求められた場合は、process(action="submit", ...) で応答します。
6. process(action="write", data="\x03") または process(action="kill") で終了します。
7. ファイルの変更内容、テスト結果、次の手順をユーザーに要約して伝えます。

PR レビューワークフロー

OpenCode には PR コマンドが組み込まれています。

terminal(command="opencode pr 42", workdir="~/project", pty=true)

または、分離するために一時的なクローンでレビューします。

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)

並行作業のパターン

競合を避けるため、別々の作業ディレクトリ／ワークツリーを使用します。

terminal(command="opencode run 'Fix issue #101 and commit'", workdir="~/.hermes/cache/scratch/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="~/.hermes/cache/scratch/issue-102", background=true, pty=true)
process(action="list")

セッションとコストの管理

過去のセッションを一覧表示します。

terminal(command="opencode session list")

トークン使用量とコストを確認します。

terminal(command="opencode stats")
terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")

落とし穴

• 対話型の opencode（TUI）セッションには pty=true が必要です。opencode run コマンドには pty は必要ありません。
• /exit は有効なコマンドではありません。エージェントセレクターが開きます。TUI を終了するには Ctrl+C を使用してください。
• PATH の不一致により、誤った OpenCode バイナリやモデル設定が選択されることがあります。
• OpenCode が応答しないように見える場合は、強制終了する前にログを確認してください。
  • process(action="log", session_id="<id>")
• 複数の OpenCode セッションで同じ作業ディレクトリを共有しないでください。
• TUI で送信するには、Enter キーを 2 回押す必要がある場合があります（1 回目でテキストを確定し、2 回目で送信します）。

検証

スモークテスト：

terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")

成功基準：

• 出力に OPENCODE_SMOKE_OK が含まれている
• コマンドがプロバイダー／モデルのエラーなしで終了する
• コードタスクの場合：想定したファイルが変更され、テストが合格する

ルール

1. 単発の自動化では opencode run を優先してください。よりシンプルで、pty も必要ありません。
2. 対話型のバックグラウンドモードは、反復作業が必要な場合にのみ使用してください。
3. OpenCode セッションは常に単一のリポジトリ／作業ディレクトリに限定してください。
4. 長時間のタスクでは、process のログをもとに進捗を報告してください。
5. 具体的な成果（変更したファイル、テスト、残るリスク）を報告してください。
6. 対話型セッションは Ctrl+C または kill で終了してください。/exit は使用しないでください。