ai-cli-mcp 2.14.1 → 2.15.0

package/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    target-branch: "develop"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      npm-production:
+        dependency-type: "production"
+        patterns:
+          - "*"
+      npm-development:
+        dependency-type: "development"
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "develop"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 2
+    groups:
+      github-actions:
+        patterns:
+          - "*"

package/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [20.19.0, 22.12.0, 24.x]
 
     steps:
     - name: Checkout repository
@@ -29,3 +29,6 @@ jobs:
 
     - name: Build project
       run: npm run build
+
+    - name: Run unit tests
+      run: npm run test:unit

package/.github/workflows/dependency-review.yml

@@ -0,0 +1,22 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches:
+      - develop
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: moderate
+          fail-on-scopes: runtime

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.15.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.14.1...v2.15.0) (2026-04-09)
+
+
+### Features
+
+* OpenCode CLIを新しいAIバックエンドとして追加 ([0677c57](https://github.com/mkXultra/ai-cli-mcp/commit/0677c57659b36fd1083cd96166c2c608c45038b3))
+
 ## [2.14.1](https://github.com/mkXultra/ai-cli-mcp/compare/v2.14.0...v2.14.1) (2026-04-07)
 
 

package/README.ja.md

@@ -5,7 +5,7 @@
 
 > **📦 パッケージ移行のお知らせ**: 本パッケージは旧名 `@mkxultra/claude-code-mcp` から `ai-cli-mcp` に名称変更されました。これは、複数のAI CLIツールのサポート拡大を反映したものです。
 
-AI CLIツール（Claude, Codex, Gemini, Forge）をバックグラウンドプロセスとして実行し、権限処理を自動化するMCP（Model Context Protocol）サーバーです。
+AI CLIツール（Claude, Codex, Gemini, Forge, OpenCode）をバックグラウンドプロセスとして実行し、権限処理を自動化するMCP（Model Context Protocol）サーバーです。
 
 Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦戦していることに気づいたことはありませんか？このサーバーは、強力な統合 `run` ツールを提供し、複数のAIエージェントを活用してコーディングタスクをより効果的に処理できるようにします。
 
@@ -21,11 +21,13 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 - 自動承認モードでCodex CLIを実行（`--full-auto` を使用）
 - 自動承認モードでGemini CLIを実行（`-y` を使用）
 - Forge CLI を非対話モードで実行（`forge -C <workFolder> -p <prompt>` を使用）
+- OpenCode を非対話 JSON モードで実行（`opencode run --format json --dir <workFolder> <prompt>` を使用）
 - 複数のAIモデルのサポート：
     - Claude (sonnet, sonnet[1m], opus, opusplan, haiku)
     - Codex (gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, など)
     - Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview)
     - Forge (`forge`)
+    - OpenCode (`opencode` と `oc-<provider/model>` ラッパー。例: `oc-openai/gpt-5.4`)
 - PID追跡によるバックグラウンドプロセスの管理
 - ツールからの構造化された出力の解析と返却
 
@@ -67,6 +69,7 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 - **Codex CLI**（オプション）: インストール済みで、ログインなどの初期設定が完了していること。
 - **Gemini CLI**（オプション）: インストール済みで、ログインなどの初期設定が完了していること。
 - **Forge CLI**（オプション）: インストール済みで、初期設定が完了していること。
+- **OpenCode**（オプション）: インストール済みで、設定が完了していること。この統合では `opencode run --format json` を使用し、明示的なモデル指定は `ai-cli models` が公開する `oc-<provider/model>` 構文に従います。
 
 ## インストールと使い方
 
@@ -116,6 +119,8 @@ npm install -g ai-cli-mcp
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli run --cwd "$PWD" --model opencode --prompt "OpenCode のデフォルト設定でこのリポジトリを要約して"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "明示モデル付きでこの OpenCode セッションを続けて"
 ai-cli ps
 ai-cli result 12345
 ai-cli result 12345 --verbose
@@ -132,6 +137,7 @@ ai-cli-mcp
 
 ```bash
 npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "OpenCode で hello"
 ```
 
 ## 重要な初回セットアップ
@@ -185,6 +191,8 @@ macOSでは、これらのツールを初めて実行する際にフォルダへ
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "この OpenCode セッションを継続して"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "明示的な OpenCode モデルで実行"
 ai-cli ps
 ai-cli wait 12345
 ai-cli wait 12345 --verbose
@@ -195,6 +203,13 @@ ai-cli cleanup
 
 `run` の作業ディレクトリ指定は `--cwd` が基本です。互換性のために `--workFolder` / `--work-folder` も受け付けます。
 
+OpenCode のモデル指定は次の 2 つを受け付けます。
+
+- `opencode`: OpenCode 側で設定されたデフォルトモデルを使用
+- `oc-<provider/model>`: 明示的な OpenCode の provider/model を指定。例: `oc-openai/gpt-5.4`
+
+`ai-cli models` は OpenCode を機械可読に `opencode: ["opencode"]` と `dynamicModelBackends.opencode` で公開します。実際に利用可能なバックエンドネイティブなモデル一覧は `opencode models` で確認してください。
+
 `doctor` は CLI バイナリの存在確認と path 解決だけを行います。ログイン状態や利用規約同意までは確認しません。
 
 ## CLI の状態保存先
@@ -210,12 +225,13 @@ ai-cli cleanup
 - `meta.json`
 - `stdout.log`
 - `stderr.log`
+- `exit-status.json`（detached な OpenCode 実行用）
 
 完了済み・失敗済みの実行は `ai-cli cleanup` で削除できます。`running` のものは保持されます。
 
 ## 既知の制約
 
-detached 実行された `ai-cli` の自然終了 exit code は、まだ永続化していません。そのため、CLI は出力と running/completed 状態は返せますが、自然終了したバックグラウンド実行の `exitCode` は現時点では保証しません。
+detached 実行された `ai-cli` では、OpenCode バックエンドに限り自然終了時の exit status を永続化します。そのため OpenCode の失敗終了は非ゼロ exit code を含めて `failed` として扱われ、結果では生の `stdout` / `stderr` を保持します。一方、他の detached バックエンドでは従来どおり、より広い exit-status 追跡が追加されるまでは自然終了した実行が信頼できる exit code なしで `completed` と見なされる制約が残ります。
 
 ## MCPクライアントへの接続
 
@@ -229,7 +245,7 @@ detached 実行された `ai-cli` の自然終了 exit code は、まだ永続
 
 ### `run`
 
-Claude CLI、Codex CLI、Gemini CLI、または Forge CLI を使用してプロンプトを実行します。モデル名に基づいて適切なCLIが自動的に選択されます。
+Claude CLI、Codex CLI、Gemini CLI、Forge CLI、または OpenCode を使用してプロンプトを実行します。モデル名に基づいて適切なCLIが自動的に選択されます。
 
 **引数:**
 - `prompt` (string, 任意): AIエージェントに送信するプロンプト。`prompt` または `prompt_file` のいずれかが必須です。
@@ -241,8 +257,9 @@ Claude CLI、Codex CLI、Gemini CLI、または Forge CLI を使用してプロ
     - Codex: `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
     - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
     - Forge: `forge`
-- `reasoning_effort` (string, 任意): Claude と Codex の推論制御。Claude では `--effort` を使います（許容値: "low", "medium", "high"）。Codex では `model_reasoning_effort` を使います（許容値: "low", "medium", "high", "xhigh"）。Forge では `reasoning_effort` はサポートしません。
-- `session_id` (string, 任意): 以前のセッションを再開するためのセッションID。対応モデル: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview, forge。
+    - OpenCode: `opencode`（設定済みのデフォルトモデル）および `oc-openai/gpt-5.4` のような明示ラッパー
+- `reasoning_effort` (string, 任意): Claude と Codex の推論制御。Claude では `--effort` を使います（許容値: "low", "medium", "high"）。Codex では `model_reasoning_effort` を使います（許容値: "low", "medium", "high", "xhigh"）。Gemini、Forge、OpenCode では `reasoning_effort` はサポートしません。
+- `session_id` (string, 任意): 以前のセッションを再開するためのセッションID。Claude、Codex、Gemini、Forge、OpenCode でサポートされます。OpenCode は `--session` による in-place resume で再開し、`oc-<provider/model>` の明示指定と併用できます。
 
 ### `wait`
 
@@ -311,6 +328,7 @@ npm run test:e2e
 - `CODEX_CLI_NAME`: Codex CLIのバイナリ名または絶対パスを上書き（デフォルト: `codex`）
 - `GEMINI_CLI_NAME`: Gemini CLIのバイナリ名または絶対パスを上書き（デフォルト: `gemini`）
 - `FORGE_CLI_NAME`: Forge CLIのバイナリ名または絶対パスを上書き（デフォルト: `forge`）
+- `OPENCODE_CLI_NAME`: OpenCode CLIのバイナリ名または絶対パスを上書き（デフォルト: `opencode`）
 - `MCP_CLAUDE_DEBUG`: デバッグログを有効化（`true` に設定すると詳細な出力が表示されます）
 
 **CLI名の指定方法:**
@@ -329,7 +347,8 @@ npm run test:e2e
       ],
       "env": {
         "CLAUDE_CLI_NAME": "claude-custom",
-        "CODEX_CLI_NAME": "codex-custom"
+        "CODEX_CLI_NAME": "codex-custom",
+        "OPENCODE_CLI_NAME": "opencode-custom"
       }
     },
 ```

package/README.md

@@ -7,7 +7,7 @@
 
 > **📦 Package Migration Notice**: This package was formerly `@mkxultra/claude-code-mcp` and has been renamed to `ai-cli-mcp` to reflect its expanded support for multiple AI CLI tools.
 
-An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, Gemini, and Forge) in background processes with automatic permission handling.
+An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, Gemini, Forge, and OpenCode) in background processes with automatic permission handling.
 
 Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified `run` tool, enables multiple AI agents to handle your coding tasks more effectively.
 
@@ -23,7 +23,8 @@ This MCP server provides tools that can be used by LLMs to interact with AI CLI
 - Execute Codex CLI with automatic approval mode (using `--full-auto`)
 - Execute Gemini CLI with automatic approval mode (using `-y`)
 - Execute Forge CLI in non-interactive mode (using `forge -C <workFolder> -p <prompt>`)
-- Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, haiku), Codex (gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2, gpt-5.1, gpt-5.1-codex, gpt-5-codex, gpt-5-codex-mini, gpt-5), Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview), and Forge (`forge`)
+- Execute OpenCode in non-interactive JSON mode (using `opencode run --format json --dir <workFolder> <prompt>`)
+- Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, haiku), Codex (gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2, gpt-5.1, gpt-5.1-codex, gpt-5-codex, gpt-5-codex-mini, gpt-5), Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview), Forge (`forge`), and OpenCode (`opencode` plus explicit `oc-<provider/model>` wrappers such as `oc-openai/gpt-5.4`)
 - Manage background processes with PID tracking
 - Parse and return structured outputs from both tools
 
@@ -65,6 +66,7 @@ The only prerequisite is that the AI CLI tools you want to use are locally insta
 - **Codex CLI** (Optional): Installed and initial setup (login etc.) completed.
 - **Gemini CLI** (Optional): Installed and initial setup (login etc.) completed.
 - **Forge CLI** (Optional): Installed and initial setup completed.
+- **OpenCode** (Optional): Installed and configured. This integration uses `opencode run --format json`, and explicit provider/model selection follows the `oc-<provider/model>` wrapper syntax exposed by `ai-cli models`.
 
 ## Installation & Usage
 
@@ -114,6 +116,8 @@ Examples:
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli run --cwd "$PWD" --model opencode --prompt "summarize this repository with OpenCode defaults"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "continue this session with an explicit OpenCode model"
 ai-cli ps
 ai-cli result 12345
 ai-cli result 12345 --verbose
@@ -130,6 +134,7 @@ Because the published package name is still `ai-cli-mcp`, the shortest `npx` for
 
 ```bash
 npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "hello from OpenCode"
 ```
 
 ## Important First-Time Setup
@@ -183,6 +188,8 @@ Example flow:
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "continue this OpenCode session"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "run with an explicit OpenCode backend model"
 ai-cli ps
 ai-cli wait 12345
 ai-cli wait 12345 --verbose
@@ -193,6 +200,13 @@ ai-cli cleanup
 
 `run` accepts `--cwd` as the primary working-directory flag and also accepts the older aliases `--workFolder` / `--work-folder` for compatibility.
 
+OpenCode model selection accepts either:
+
+- `opencode` for the CLI's configured default model
+- `oc-<provider/model>` for an explicit OpenCode provider/model, for example `oc-openai/gpt-5.4`
+
+`ai-cli models` exposes OpenCode machine-readably via `opencode: ["opencode"]` plus `dynamicModelBackends.opencode`, which points users to `opencode models` for backend-native discovery.
+
 `doctor` checks only binary existence and path resolution. It does not verify login state or terms acceptance.
 
 ## CLI State Storage
@@ -208,12 +222,13 @@ Each PID directory contains:
 - `meta.json`
 - `stdout.log`
 - `stderr.log`
+- `exit-status.json` for detached OpenCode runs
 
 Use `ai-cli cleanup` to remove completed and failed runs. Running processes are preserved.
 
 ## Known Limitation
 
-Detached `ai-cli` runs do not currently persist natural process exit codes. As a result, the CLI can report process output and running/completed state, but it does not yet guarantee `exitCode` for naturally finished background runs.
+Detached `ai-cli` runs persist natural exit status for OpenCode-backed runs, including failed exit codes used to preserve raw OpenCode stdout/stderr in result output. Other detached backends still keep the pre-existing limitation: naturally finished runs may be surfaced as completed without a reliable persisted exit code until broader exit tracking is added.
 
 ## Connecting to Your MCP Client
 
@@ -227,7 +242,7 @@ This server exposes the following tools:
 
 ### `run`
 
-Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, or Forge CLI. The appropriate CLI is automatically selected based on the model name.
+Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, Forge CLI, or OpenCode. The appropriate CLI is automatically selected based on the model name.
 
 **Arguments:**
 - `prompt` (string, optional): The prompt to send to the AI agent. Either `prompt` or `prompt_file` is required.
@@ -239,8 +254,9 @@ Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, or Forge CLI. The app
 - Codex: `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
 - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
 - Forge: `forge`
-- `reasoning_effort` (string, optional): Reasoning control for Claude and Codex. Claude uses `--effort` (allowed: "low", "medium", "high"). Codex uses `model_reasoning_effort` (allowed: "low", "medium", "high", "xhigh"). Forge does not support `reasoning_effort`.
-- `session_id` (string, optional): Optional session ID to resume a previous session. Supported for: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview, forge.
+- OpenCode: `opencode` for the configured default backend model, plus explicit wrappers like `oc-openai/gpt-5.4`
+- `reasoning_effort` (string, optional): Reasoning control for Claude and Codex. Claude uses `--effort` (allowed: "low", "medium", "high"). Codex uses `model_reasoning_effort` (allowed: "low", "medium", "high", "xhigh"). Gemini, Forge, and OpenCode do not support `reasoning_effort`.
+- `session_id` (string, optional): Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, Forge, and OpenCode. OpenCode resumes in place via `--session` and may also be combined with an explicit `oc-<provider/model>` selection.
 
 ### `wait`
 
@@ -295,6 +311,7 @@ Normally not required, but useful for customizing CLI paths or debugging.
 - `CODEX_CLI_NAME`: Override the Codex CLI binary name or provide an absolute path (default: `codex`)
 - `GEMINI_CLI_NAME`: Override the Gemini CLI binary name or provide an absolute path (default: `gemini`)
 - `FORGE_CLI_NAME`: Override the Forge CLI binary name or provide an absolute path (default: `forge`)
+- `OPENCODE_CLI_NAME`: Override the OpenCode CLI binary name or provide an absolute path (default: `opencode`)
 - `MCP_CLAUDE_DEBUG`: Enable debug logging (set to `true` for verbose output)
 
 **CLI Name Specification:**
@@ -313,7 +330,8 @@ Normally not required, but useful for customizing CLI paths or debugging.
       ],
       "env": {
         "CLAUDE_CLI_NAME": "claude-custom",
-        "CODEX_CLI_NAME": "codex-custom"
+        "CODEX_CLI_NAME": "codex-custom",
+        "OPENCODE_CLI_NAME": "opencode-custom"
       }
     },
 ```

package/dist/__tests__/app-cli.test.js

@@ -180,11 +180,21 @@ describe('ai-cli app', () => {
         const stdout = vi.fn();
         const stderr = vi.fn();
         const exitCode = await runCli(['models'], { stdout, stderr });
+        const payload = JSON.parse(stdout.mock.calls[0][0]);
         expect(exitCode).toBe(0);
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"aliases"'));
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"claude-ultra"'));
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"gpt-5.4"'));
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"forge"'));
+        expect(payload.aliases).toEqual(expect.any(Array));
+        expect(payload.claude).toContain('sonnet');
+        expect(payload.codex).toContain('gpt-5.4');
+        expect(payload.forge).toEqual(['forge']);
+        expect(payload.opencode).toEqual(['opencode']);
+        expect(payload.dynamicModelBackends).toEqual({
+            opencode: {
+                explicitPrefix: 'oc-',
+                explicitPattern: 'oc-<provider/model>',
+                discoveryCommand: 'opencode models',
+                modelsAreDynamic: true,
+            },
+        });
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints doctor status as structured json', async () => {
@@ -215,6 +225,12 @@ describe('ai-cli app', () => {
                 available: true,
                 lookup: 'path',
             },
+            opencode: {
+                configuredCommand: 'opencode',
+                resolvedPath: '/tmp/bin/opencode',
+                available: true,
+                lookup: 'path',
+            },
         });
         const exitCode = await runCli(['doctor'], { stdout, stderr, getDoctorStatus });
         expect(exitCode).toBe(0);
@@ -241,6 +257,8 @@ describe('ai-cli app', () => {
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('gpt-5.2-codex'));
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('gemini-2.5-pro'));
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('forge'));
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('opencode'));
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('oc-openai/gpt-5.4'));
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints detailed help for result --help', async () => {
@@ -277,6 +295,7 @@ describe('ai-cli app', () => {
         const exitCode = await runCli(['doctor', '--help'], { stdout, stderr });
         expect(exitCode).toBe(0);
         expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('OpenCode'));
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints detailed help for doctor -h', async () => {
@@ -285,6 +304,7 @@ describe('ai-cli app', () => {
         const exitCode = await runCli(['doctor', '-h'], { stdout, stderr });
         expect(exitCode).toBe(0);
         expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('OpenCode'));
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints help for --help', async () => {

package/dist/__tests__/cli-bin-smoke.test.js

@@ -19,6 +19,44 @@ afterEach(() => {
         rmSync(dir, { recursive: true, force: true });
     }
 });
+describe('cli helper entrypoint smoke', () => {
+    it('prints help for cli.run with OpenCode examples', () => {
+        const output = execFileSync('node', ['--import', 'tsx', 'src/cli.ts', '--help'], {
+            cwd: process.cwd(),
+            encoding: 'utf8',
+            env: process.env,
+        });
+        expect(output).toContain('Usage: npm run -s cli.run -- --model <model> --workFolder <path> --prompt "..." [options]');
+        expect(output).toContain('opencode');
+        expect(output).toContain('oc-openai/gpt-5.4');
+        expect(output).toContain('OpenCode');
+        expect(output).toContain('npm run -s cli.run.parse -- --agent opencode < raw.txt');
+    });
+    it('prints help for cli.run.parse with OpenCode agent support', () => {
+        const output = execFileSync('node', ['--import', 'tsx', 'src/cli-parse.ts', '--help'], {
+            cwd: process.cwd(),
+            encoding: 'utf8',
+            env: process.env,
+        });
+        expect(output).toContain('Usage: npm run -s cli.run.parse -- --agent <claude|codex|gemini|forge|opencode>');
+        expect(output).toContain('Agent type: claude, codex, gemini, forge, or opencode');
+        expect(output).toContain('npm run -s cli.run.parse -- --agent opencode < raw.txt');
+    });
+    it('parses OpenCode NDJSON through cli.run.parse', () => {
+        const output = execFileSync('node', ['--import', 'tsx', 'src/cli-parse.ts', '--agent', 'opencode'], {
+            cwd: process.cwd(),
+            encoding: 'utf8',
+            env: process.env,
+            input: '{"type":"step_start","sessionID":"ses_cli_parse"}\n{"type":"text","sessionID":"ses_cli_parse","part":{"type":"text","text":"Hello from cli.parse"}}\n{"type":"step_finish","sessionID":"ses_cli_parse","part":{"type":"step-finish","tokens":{"total":9},"cost":1}}\n',
+        });
+        expect(JSON.parse(output)).toEqual({
+            message: 'Hello from cli.parse',
+            session_id: 'ses_cli_parse',
+            tokens: { total: 9 },
+            cost: 1,
+        });
+    });
+});
 describe('ai-cli entrypoint smoke', () => {
     it('prints doctor output for the ai-cli entrypoint', () => {
         const fakeBinDir = makeTempDir('ai-cli-bin-');
@@ -26,6 +64,7 @@ describe('ai-cli entrypoint smoke', () => {
         writeExecutable(fakeBinDir, 'codex');
         writeExecutable(fakeBinDir, 'gemini');
         writeExecutable(fakeBinDir, 'forge');
+        writeExecutable(fakeBinDir, 'opencode');
         const output = execFileSync('node', ['--import', 'tsx', 'src/bin/ai-cli.ts', 'doctor'], {
             cwd: process.cwd(),
             encoding: 'utf8',
@@ -36,12 +75,14 @@ describe('ai-cli entrypoint smoke', () => {
                 CODEX_CLI_NAME: 'codex',
                 GEMINI_CLI_NAME: 'gemini',
                 FORGE_CLI_NAME: 'forge',
+                OPENCODE_CLI_NAME: 'opencode',
             },
         });
         expect(output).toContain('"claude"');
         expect(output).toContain('"codex"');
         expect(output).toContain('"gemini"');
         expect(output).toContain('"forge"');
+        expect(output).toContain('"opencode"');
         expect(output).toContain('"available": true');
     });
     it('prints run help for the ai-cli entrypoint', () => {
@@ -54,5 +95,7 @@ describe('ai-cli entrypoint smoke', () => {
         expect(output).toContain('--model <model>');
         expect(output).toContain('claude-ultra');
         expect(output).toContain('forge');
+        expect(output).toContain('opencode');
+        expect(output).toContain('oc-openai/gpt-5.4');
     });
 });

package/dist/__tests__/cli-builder.test.js

@@ -15,6 +15,7 @@ const DEFAULT_CLI_PATHS = {
     codex: '/usr/bin/codex',
     gemini: '/usr/bin/gemini',
     forge: '/usr/bin/forge',
+    opencode: '/usr/bin/opencode',
 };
 describe('cli-builder', () => {
     beforeEach(() => {
@@ -74,6 +75,10 @@ describe('cli-builder', () => {
         it('should reject reasoning_effort for forge explicitly', () => {
             expect(() => getReasoningEffort('forge', 'high')).toThrow('reasoning_effort is not supported for forge.');
         });
+        it('should reject reasoning_effort for opencode explicitly', () => {
+            expect(() => getReasoningEffort('opencode', 'high')).toThrow('reasoning_effort is not supported for opencode.');
+            expect(() => getReasoningEffort('oc-openai/gpt-5.4', 'high')).toThrow('reasoning_effort is not supported for opencode.');
+        });
     });
     describe('buildCliCommand', () => {
         describe('validation', () => {
@@ -326,37 +331,110 @@ describe('cli-builder', () => {
                 expect(cmd.resolvedModel).toBe('gemini-3.1-pro-preview');
             });
         });
-        describe('forge agent', () => {
-            it('should build forge command without model flags', () => {
+        describe('opencode agent', () => {
+            it('should build default opencode command without --model', () => {
                 const cmd = buildCliCommand({
                     prompt: 'test',
                     workFolder: '/tmp',
-                    model: 'forge',
+                    model: 'opencode',
                     cliPaths: DEFAULT_CLI_PATHS,
                 });
-                expect(cmd.agent).toBe('forge');
-                expect(cmd.cliPath).toBe('/usr/bin/forge');
-                expect(cmd.resolvedModel).toBe('forge');
-                expect(cmd.args).toEqual(['-C', '/tmp', '-p', 'test']);
+                expect(cmd.agent).toBe('opencode');
+                expect(cmd.cliPath).toBe('/usr/bin/opencode');
+                expect(cmd.cwd).toBe('/tmp');
+                expect(cmd.args).toEqual(['run', '--format', 'json', '--dir', '/tmp', 'test']);
+                expect(cmd.args).not.toContain('--model');
             });
-            it('should map session_id to --conversation-id for forge', () => {
+            it('should route valid explicit OpenCode model syntax', () => {
                 const cmd = buildCliCommand({
                     prompt: 'test',
                     workFolder: '/tmp',
-                    model: 'forge',
-                    session_id: 'forge-conv-123',
+                    model: 'oc-openai/gpt-5.4',
                     cliPaths: DEFAULT_CLI_PATHS,
                 });
-                expect(cmd.args).toEqual(['-C', '/tmp', '--conversation-id', 'forge-conv-123', '-p', 'test']);
+                expect(cmd.agent).toBe('opencode');
+                expect(cmd.resolvedModel).toBe('oc-openai/gpt-5.4');
+                expect(cmd.args).toEqual([
+                    'run',
+                    '--format',
+                    'json',
+                    '--dir',
+                    '/tmp',
+                    '--model',
+                    'openai/gpt-5.4',
+                    'test',
+                ]);
+            });
+            it.each([
+                'oc-',
+                'oc-openai',
+                'oc-/gpt-5.4',
+                'oc-openai/',
+            ])('should reject invalid explicit OpenCode syntax: %s', (model) => {
+                expect(() => buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model,
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Invalid OpenCode model. Expected exact syntax oc-<provider/model>.');
             });
-            it('should reject reasoning_effort for forge in command building', () => {
+            it.each([' oc-openai/gpt-5.4', 'oc-openai/gpt-5.4 '])('should reject explicit OpenCode models with surrounding whitespace: %s', (model) => {
                 expect(() => buildCliCommand({
                     prompt: 'test',
                     workFolder: '/tmp',
-                    model: 'forge',
+                    model,
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Invalid OpenCode model. Expected exact syntax oc-<provider/model>.');
+            });
+            it('should reject reasoning_effort for OpenCode in command building', () => {
+                expect(() => buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'opencode',
                     reasoning_effort: 'high',
                     cliPaths: DEFAULT_CLI_PATHS,
-                })).toThrow('reasoning_effort is not supported for forge.');
+                })).toThrow('reasoning_effort is not supported for opencode.');
+            });
+            it('should build resumed default OpenCode command', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'resume prompt',
+                    workFolder: '/tmp',
+                    model: 'opencode',
+                    session_id: 'ses-123',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args).toEqual([
+                    'run',
+                    '--format',
+                    'json',
+                    '--dir',
+                    '/tmp',
+                    '--session',
+                    'ses-123',
+                    'resume prompt',
+                ]);
+                expect(cmd.args).not.toContain('--model');
+            });
+            it('should build resumed explicit OpenCode command', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'resume prompt',
+                    workFolder: '/tmp',
+                    model: 'oc-openai/gpt-5.4',
+                    session_id: 'ses-456',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args).toEqual([
+                    'run',
+                    '--format',
+                    'json',
+                    '--dir',
+                    '/tmp',
+                    '--session',
+                    'ses-456',
+                    '--model',
+                    'openai/gpt-5.4',
+                    'resume prompt',
+                ]);
             });
         });
     });