opencode-runner

OpenCode Runner

無料モデルを使用して、コーディングタスクを opencode に委任します。費用はゼロで、すべて自動化されます。

OpenCode（opencode.ai）は、複数のプロバイダーとモデルに対応したターミナル AI コーディングアシスタントです。このスキルは、利用可能な最適な無料モデルの選択、タスクの開始、進捗状況の報告を自動化します。

前提条件

• opencode がインストールされていること：which opencode が成功する必要があります。インストールされていない場合は、npm i -g opencode-ai@latest または brew install opencode でインストールしてください
• インターネット接続：OpenCode Zen 経由でクラウドモデルを選択し、タスクを実行するために必要です
• プロジェクトのコンテキスト：ファイルのコンテキストを必要とするタスクでは、現在の作業ディレクトリをプロジェクトのルートにしてください

重要なルール

1. タスクを自分で実行してはいけません。 このスキルは、作業を opencode に委任するためだけのものです。opencode がインストールされていない、実行に失敗する、または利用可能な無料クラウドモデルがない場合は、ユーザーに問題を報告して停止してください。ファイルを直接編集する、自分でコードを書く、またはユーザーのコーディングタスクを実行するために他のツールを使うなどの代替手段に切り替えてはいけません。作業を行うのは opencode です。

2. クラウドモデルのみを選択してください。 ローカルモデル（例：ollama/*、lmstudio/*、または localhost で実行されているモデル）は決して選択しないでください。OpenCode Zen でホストされているクラウドモデルである、opencode/* プロバイダーネームスペースのモデルのみを選択してください。ローカルモデルは利用可能性やパフォーマンスが予測できず、opencode が必要とするツール使用機能に対応していない場合があります。

3. 必ず後処理を行ってください。 opencode は、タスク終了後も残るバックグラウンドプロセス（LSP サーバー、MCP サーバー、node ワーカー）を起動します。成功、失敗、エラー、タイムアウトのいずれの場合も、実行後は必ずフェーズ 6 のクリーンアップ手順を行ってください。残された opencode プロセスは CPU とメモリを消費し続けるため、マシンの動作が極端に遅くなるまでユーザーが気づかないことがあります。

編集前のリポジトリ同期（必須）

既存のリポジトリ内のファイルを作成、更新、削除する前に、現在のブランチをリモートと同期してください。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーがクリーンでない場合は、まず stash し、同期してから復元してください。

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin がない場合、または競合が発生した場合は、停止して続行する前にユーザーに確認してください。

フェーズ 1：インストールの確認

opencode がインストールされていて、最新バージョンであることを確認してください。

ステップ 1：インストール済みか確認

which opencode && opencode --version

opencode が見つからない場合は、次のようにユーザーに伝えてください。

opencode がインストールされていません。次のいずれかのコマンドでインストールしてください。

curl -fsSL https://opencode.ai/install | bash

または

npm i -g opencode-ai@latest

または（macOS）

brew install opencode

その後、BLOCKED — opencode is not installed（最終レポート）として完全に停止してください。他のフェーズに進んだり、タスクを自分で実行したり、ファイルを編集したりしてはいけません。ユーザーが opencode をインストールし、このスキルを再度呼び出すまで待ってください。

ステップ 2：更新の確認

1. opencode upgrade を実行します。最新バージョンにアップグレードするか、インストール済みのバージョンが最新であることを確認します。
2. opencode upgrade がゼロ以外の終了コードを返した場合は、エラーをユーザーに伝え、opencode upgrade を手動で実行するよう提案してください。その後、項目 3 に進みます。
3. opencode --version を再度実行します。
4. opencode --version がゼロ以外の終了コードを返した場合は、BLOCKED — opencode does not start after the upgrade として停止してください。フェーズ 2 に進んではいけません。

フェーズ 2：無料モデルを見つけてユーザーに選んでもらう

利用可能なモデルを問い合わせ、無料モデルをユーザーに提示して選択してもらいます。ユーザーが選択しない場合は、優先順位に従って選択してください。

opencode models 2>/dev/null

無料モデルの優先リスト（ユーザーが選択を委ねた場合のデフォルト順）

優先度	モデル ID	備考
1	opencode/deepseek-v4-flash-free	最近の強力な無料コーディングモデル — デフォルトとして推奨
2	opencode/minimax-m2.5-free	MiniMax の無料プラン — 汎用用途に適しています
3	opencode/nemotron-3-super-free	NVIDIA Nemotron の無料プラン
4	opencode/big-pickle	無料の代替モデル
5	opencode/gpt-5-nano	小型の代替モデル。opencode models で価格が $0 と表示される場合のみ無料

モデル ID は変更されることがあります。ID が opencode/* 名前空間にあり、次のいずれかに該当するモデルは、無料プランの対象です。ID が -free で終わる、ID が opencode/big-pickle である、または opencode models の出力で価格が $0 と表示される。完全一致ではなく、サフィックスで照合してください。出力に $0 の価格が表示されない場合は、opencode/gpt-5-nano を候補から除外してください。

選択ロジック

1. opencode models を実行し、すべての項目を収集します。

2. opencode/* 以外のモデルをすべて除外します — ollama/*、lmstudio/*、nvidia/*、またはその他の名前空間のモデルは無視してください。クラウドでホストされている opencode/* モデルのみが対象です。

3. 残ったリストから、無料プランの対象モデルのみを残します。

4. 無料モデルを優先度順に番号付きの選択肢としてユーザーに提示し、優先度 1 のモデルをデフォルトとして示します。可能であれば <options> 形式を使用します。例：

   opencode で利用できる無料のクラウドモデルが見つかりました。いずれかを選ぶか、デフォルトを選択してください。

   1. opencode/deepseek-v4-flash-free (デフォルト — 優先度 1)
   2. opencode/minimax-m2.5-free
   3. opencode/nemotron-3-super-free
   4. opencode/big-pickle

5. ユーザーがモデル名を指定した場合は、そのモデルを使用します。ユーザーが「デフォルト」、「選んで」、「どれでも」と言った場合、または指定しなかった場合は、優先度 1 のモデル（利用可能な中で最も優先度の高い無料モデル）を使用します。

6. 無料プランの対象モデルが残っていない場合は、BLOCKED — no free cloud model available で停止します。ローカルモデル、有料モデル、または自分でタスクを実行する方法に切り替えてはいけません。

プライバシーに関する注意（モデル一覧とともに必ず表示）：OpenCode Zen の無料モデルでは、収集されたデータがモデルの改善に使用される場合があります。

フェーズ 3：実行前の確認

opencode を呼び出す前に、画面 1 枚に収まる概要をユーザーに提示し、明示的な確認を得てください。これにより、トークンを消費する前にモデルやプロンプトの誤りに気付けます。

次のブロックを提示します。

opencode への委任準備完了

• モデル： opencode/deepseek-v4-flash-free（無料プラン）
• 作業ディレクトリ： /Users/.../current-project
• コンテキストファイル： path/to/foo.py、path/to/bar.py（または「なし」）
• プロンプト： （プロンプトをそのまま引用。複数行でも可）
• 推定所要時間： 不明 — opencode の実行結果は非決定的です。タイムアウト時もクリーンアップは実行されます。

続行するには確認してください。または、変更する内容（モデル、プロンプト、ファイル）をお知らせください。

続いて、ユーザーに「Proceed」と「Change something」の 2 つの <options> を提示します。確認を待ってください。ユーザーが確認するまで、opencode run を実行してはいけません。

ユーザーが変更（別のモデル、プロンプトの編集、コンテキストファイルの追加または削除）を求めた場合は、最初に戻って該当の項目を更新し、概要を再提示して、もう一度確認を求めます。ユーザーがキャンセルした場合は、BLOCKED — the user cancelled before the run で停止します。

フェーズ 4：タスクの実行

確認済みのモデルでコーディングタスクを実行します。必ずバックグラウンドで実行し、出力をログファイルにリダイレクトしてください — これはフェーズ 5 の低トークン監視戦略で必要です。

RUN=/tmp/opencode-run-$(date +%s)
( opencode run -m "[confirmed-model-id]" "[confirmed prompt]" > "$RUN.log" 2>&1; echo $? > "$RUN.exit" ) &
echo $! > "$RUN.pid"
echo "opencode started: run=$RUN pid=$(cat "$RUN.pid")"

ここで出力される run= の値を記録し、後続のフェーズ 5 とフェーズ 6 のすべてのシェルで、その値を文字どおり置き換えてください。 Bash の呼び出しごとに新しいシェルが開始されるため、"$RUN.log"、"$RUN.pid"、または "$RUN.exit" を読み取る前に、記録したプレフィックスを RUN に再設定します。.pid ファイルは所有権の記録です。ラッパーサブシェルの ID が格納されており、その子プロセスが opencode run です。後続のシェルからは wait できないため、opencode の実行が終了すると、ラッパーは opencode の終了コードを .exit に書き込みます。

複数行または複雑なプロンプトの処理

ファイルを参照するタスクや、詳細なコンテキストが必要なタスクでは、--file フラグを使用します。

RUN=/tmp/opencode-run-$(date +%s)
( opencode run -m "[confirmed-model-id]" --file path/to/relevant-file.py "[task description]" > "$RUN.log" 2>&1; echo $? > "$RUN.exit" ) &
echo $! > "$RUN.pid"
echo "opencode started: run=$RUN pid=$(cat "$RUN.pid")"

フォアグラウンドでの実行は推奨されません。opencode の出力全体をストリーミングしてコンテキストに取り込むと、トークンを無駄に消費します。Phase 5 のモニターはログの末尾だけを読み取ります。

Phase 5：最小限のトークンでモニタリングする

opencode の出力は冗長です。ログ全体をストリーミングしてコンテキストに取り込むにはコストがかかります。1 回の長時間実行で、ストリームの冗長な出力が 10k トークンを簡単に超えることがあります。代わりに、以下の軽量なポーリング手順を使用してください。

ポーリング手順

確認ごとに、小さなステータスコマンドを1 つだけ実行します。最大約 200 バイトが返されます。ログ全体を取り込まずに、ステータス、経過時間、直近のアクティビティ行を把握できます。

RUN=/tmp/opencode-run-1234567890   # paste the run= value Phase 4 printed
status() {
  pid=$(cat "$RUN.pid" 2>/dev/null)
  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then s=running; else s=done; fi
  ec=$(cat "$RUN.exit" 2>/dev/null)
  bytes=$(wc -c < "$RUN.log" 2>/dev/null || echo 0)
  last=$(tail -n 1 "$RUN.log" 2>/dev/null | tr -d '\r' | cut -c1-160)
  printf 'status=%s pid=%s exit=%s bytes=%s last=%q\n' "$s" "${pid:-none}" "${ec:-none}" "$bytes" "$last"
}
status

この 1 行が進捗状況のサンプル全体です。tail -n 50 や cat "$RUN.log" を実行したり、stdout をストリーミングしたりしないでください。これらは目的に反します。

ポーリング間隔（必須）

• 1 回目と 2 回目のポーリング前は30 秒待ちます。それ以降は、各ポーリングの前に60～120 秒待ちます。
• 上限は 1 回の実行につき合計6 回です。6 回目のポーリングでも status=running の場合は、待ち続けるかプロセスを終了するかをユーザーに確認します。ユーザーが回答するまで、再度ポーリングしないでください。ユーザーが待ち続けるよう指示した場合は、同じルールで最大 6 回まで追加でポーリングできます。
• 連続する 2 回のポーリングで bytes= の値が同じ場合、実行は停滞しています。bytes= が 5 分間増加しない場合、実行はタイムアウトしています。停滞またはタイムアウトした場合は、待ち続けるかプロセスを終了するかをユーザーに確認します。ユーザーが承認した場合にのみ終了し、その後はエラー、停滞、タイムアウト時の対応に従います。

ポーリング間に報告する内容

status() の出力に基づき、確認ごとに短い行を 1 つ報告します。

ポーリング 2（t+60s）：実行中、4.2 KB 書き込み済み、直近の行："src/foo.py を編集中 …"

生のログを貼り付けないでください。opencode が「考えている」内容を要約しないでください。ログ末尾の行からは判断できません。ステータス、経過時間、バイト数の増加、直近の行だけを記載してください。

完了時

status=done になったら：

1. ログ全体ではなく、末尾だけを読み取ります：tail -n 40 "$RUN.log"。これは opencode が最後に出力する要約（変更されたファイル、使用トークン数、エラー）です。
2. 実行を分類します。exit=0 は成功です。それ以外の exit= 値は失敗です。exit=none は opencode の完了前にラッパーが終了されたことを意味するため、失敗として扱います。
3. 作業ディレクトリが git リポジトリの場合、git status --porcelain を実行して変更されたファイルを一覧表示します。これは読み取り専用です。ファイルを編集、ステージング、または元に戻さないでください。
4. ログ全体を貼り付けないでください。ユーザーがログを残すよう求めた場合は、Phase 6 のステップ 3 で "$RUN.log" を削除せず、最終報告にそのパスを記載します。
5. タスクが失敗した場合は、Phase 2 のリストから次に利用可能なモデルで再試行するよう提案します。
6. Phase 6 のクリーンアップを実行します。成功した場合も必須です。
7. 最終報告（Final Report）を出力します。

エラー、停滞、タイムアウト時の対応

1. エラーまたは停滞を、直近のポーリングに基づいて 1 行でユーザーに報告します。
2. 次に利用可能なクラウドモデルで再試行するよう提案します。
3. 利用可能なすべてのモデルを試した場合は、プロバイダーの認証を確認するために opencode auth list を実行するようユーザーに提案します。
4. 代替手段として、自分でタスクを実行しようとしてはいけません。
5. 必ず Phase 6 のクリーンアップを実行します。
6. 最終報告（Final Report）を出力します。

Phase 6：クリーンアップ（必須）

成功、失敗、エラー、タイムアウトにかかわらず、実行のたびに最後にクリーンアップを行う必要があります。opencode は子プロセス（LSP サーバー、MCP サーバー、node ワーカー）を起動し、メインプロセスの終了後もそれらが残ることがあります。クリーンアップを行わないと、こうした孤立プロセスが蓄積し、システムリソースを消費します。

ステップ 1：opencode のプロセスツリーを終了する

opencode をバックグラウンドで起動した場合は、記録された実行プレフィックスの pidfile を所有権の記録として使用します。

RUN=/tmp/opencode-run-1234567890   # paste the run= value Phase 4 printed
pid=$(cat "$RUN.pid" 2>/dev/null)
if [ -n "$pid" ]; then
  pkill -TERM -P "$pid" 2>/dev/null   # opencode runs as a child of the wrapper subshell
  kill "$pid" 2>/dev/null
  sleep 2
  pkill -KILL -P "$pid" 2>/dev/null
  kill -9 "$pid" 2>/dev/null
fi

ステップ 2：孤立した opencode プロセスを探して終了する

1. pgrep -fl "opencode run" を実行して、残存する opencode run プロセスを一覧表示します。
2. プロセスが表示された場合は、pkill -f "opencode run" を実行します。

このパターンは、サブコマンドのない opencode を実行しているユーザーの対話型 TUI セッションには一致しません。そのセッションには手を加えないでください。

Step 3: 一時ファイルをクリーンアップする

rm -f "$RUN.log" "$RUN.pid" "$RUN.exit" 2>/dev/null

ユーザーがログを残すよう依頼した場合（Phase 5 の 完了時 の項目 4）、このコマンドから "$RUN.log" を削除します。

Step 4: クリーンアップを確認する

1. pgrep -f "opencode run" >/dev/null && echo cleanup=incomplete || echo cleanup=complete を実行します。
2. cleanup=complete と表示された場合は、クリーンアップ完了 — opencode run プロセスが残っていないことを報告します。
3. cleanup=incomplete と表示された場合は、警告： opencode run プロセスがまだ実行中です。手動で pkill -f "opencode run" を実行してクリーンアップしてください。

最終レポート

Phase 6 の後、次の順序で簡潔なテキストの最終レポートを 1 つ出力します。Result:（COMPLETE、PARTIAL — <reason>、または BLOCKED — <reason>）、Evidence:（実行したチェックのみ）、Uncertainty:、続いて Decision:（必要な承認、または No approval needed.）。opencode run の開始前に停止した場合は、Phase 4～6 を省略し、レポートを直接出力します。ステータスのルール、例、および読み手向けチェックについては、references/final-report.md を参照してください。

期待される出力

各フェーズでユーザーに表示する一連の例のブロック（モデルピッカー、確認サマリー、トークン数が少ない場合の進捗確認、クリーンアップの確認）については、references/expected-output.md を参照してください。エラーまたはタイムアウトの場合も、クリーンアップの確認を実行します。最終レポートの例については、references/final-report.md を参照してください。

---

エッジケース

エッジケースが発生した場合は、references/edge-cases.md を読みます。対象となるのは、opencode が見つからない場合、アップグレードの失敗、利用可能な無料モデルがない場合、すべてのモデルが失敗する場合、処理の停止またはタイムアウト、確認の却下、TUI セッションが開いている場合、複数行のプロンプト、ゼロ以外の終了コード、ラッパーが強制終了された場合です。opencode コマンドのリファレンスも記載されています。

---

受け入れ基準

以下のすべてを検証できる場合、このスキルの実行は成功とみなされます。

• インストールの確認 — フェーズ 1 では、他の操作を行う前に opencode が PATH 上にあることを確認し、そのバージョンを報告します。
• クラウドの opencode/* モデルのみを対象にする — フィルターステップでは、ollama/*、lmstudio/*、nvidia/* およびその他すべての名前空間を除外します。ローカルモデルが選択されることはありません。
• 無料モデルをユーザーに提示する — フェーズ 2 では、利用可能なすべての無料の opencode/* モデルを優先度 1 のモデルをデフォルトとして一覧表示し、プライバシーに関する注意書きも示します。ユーザーはモデルを選択できます。選択を保留した場合は、優先度 1 のモデルを使用します。
• 実行前に確認を取得する — フェーズ 3 では、モデル、cwd、コンテキストファイル、プロンプトを表示し、opencode run を呼び出す前にユーザーの明示的な確認を待ちます。
• タスクを opencode に委任する — コーディングタスクは opencode run を通じて実行します。スキルが直接ファイルを編集したり、自らコードを書いたりすることはありません。
• トークン消費を抑えた監視を使用する — フェーズ 5 では、1 行の status() ヘルパーを使ってポーリングします。生ログをストリーミングで返すことはありません。各ポーリングでは最終行、バイト数、ステータスのみを報告します。1 回の実行につき、ポーリングは最大 6 回です。
• 停止／タイムアウトに対処する — 連続する 2 回のポーリングでバイト数が増加しない場合、またはバイト数が増加しないまま 5 分が経過した場合、ユーザーに確認し、承認された場合はプロセスを終了してクリーンアップします。
• 完了サマリーを提示する — status=done になったら、スキルは tail -n 40 "$RUN.log" のみを読み取り、exit= の値に基づいて実行を分類し、変更されたファイルとトークン使用量を要約します。
• すべての終了経路でクリーンアップを実行する — フェーズ 6 は、タスクの成功、失敗、エラー、停止、タイムアウトのいずれの場合も実行し、ステップ 4 では、レポートがクリーンアップ完了を示す前に cleanup=complete を出力します。
• 一時ファイルを削除する — ログを残すようユーザーが依頼した場合を除き、クリーンアップ時に "$RUN.log"、"$RUN.pid"、"$RUN.exit" を削除します。
• 自ら処理する代替手段に切り替えない — opencode を利用できない場合、ユーザーが確認を拒否した場合、またはすべての無料モデルで失敗した場合、スキルは停止します。ファイル編集やコード作成を自ら行うことに切り替えることはありません。
• 最終レポートを提示する — 停止した場合も含め、すべての実行の最後に Result:、Evidence:、Uncertainty:、Decision: を記載し、references/final-report.md にある 4 つの読者チェックを満たします。すなわち、結果が最初の行で見つけられること、事実と仮定が分けられていること、各主張の根拠となるチェックが実行済みであること、次の判断が明示されていることです。ユーザーがこれらのチェックに回答するまでは、人間が内容を理解したことは未確認のままです。

---

各ステップの完了レポート

各フェーズの後に、合否を一目で確認できるよう、簡潔なステータスブロックを出力します。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

合格には √、不合格には × を使い、簡単な補足には — を使います。フェーズごとのブロック例（インストール、モデルの検出、確認、実行、監視、クリーンアップ）は references/expected-output.md にあります。