OpenCode CLI

OpenCode を Hermes ターミナル/プロセスツールで調整されたオートノーマスコーディングワーカーとして使用します。OpenCode はプロバイダー非依存のオープンソース AI コーディングエージェントで、TUI と CLI を備えています。

使用時期

• ユーザーが明示的に 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)
# session_id を返す

# プロンプト送信
process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")

# 進捗監視
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# フォローアップ入力送信
process(action="submit", session_id="<id>", data="Now add error handling for token expiry")

# クリーンに終了 — Ctrl+C
process(action="write", session_id="<id>", data="\x03")
# または単にプロセスを終了
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)  # 最後のセッション続行
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # 特定セッション

共通フラグ

フラグ	用途
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="/tmp/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/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 回、送信 1 回)。

検証

スモークテスト:

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

成功基準:

• 出力に OPENCODE_SMOKE_OK が含まれる
• コマンドがプロバイダー/モデルエラーなく終了
• コードタスク用: 予期されたファイルが変更され、テストが成功

リファレンスファイル

• references/testing-anthopic-proxies.md — カスタム Anthropic API プロキシエンドポイント (カスタム baseURL、モデル ID、思考サポート) を検証する方法。

ルール

1. ワンショット自動化には opencode run を優先 — よりシンプルで pty 不要。
2. インタラクティブバックグラウンドモードは反復が必要な場合のみ使用。
3. 常に OpenCode セッションを単一リポジトリ/ワークディレクトリにスコープ。
4. 長時間タスクについては、process ログから進捗更新を提供。
5. 具体的な成果を報告 (ファイル変更、テスト、残存リスク)。
6. インタラクティブセッションは Ctrl+C または kill で終了、/exit は絶対不可。