ai-cli-mcp 2.10.0 → 2.12.0

package/.github/workflows/watch-session-prs.yml

@@ -0,0 +1,276 @@
+name: Watch Session PRs
+
+on:
+  schedule:
+    - cron: '17 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  watch-codex-fork:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check Codex fork PR and update issue
+        uses: actions/github-script@v7
+        env:
+          UPSTREAM_OWNER: openai
+          UPSTREAM_REPO: codex
+          UPSTREAM_PR_NUMBER: '13537'
+          TARGET_ISSUE_NUMBER: '7'
+          COMMENT_MARKER: '<!-- codex-fork-pr-13537-status -->'
+          READY_LABEL: '[ready]'
+          STOP_LABEL: '[stop]'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = process.env.UPSTREAM_OWNER;
+            const repo = process.env.UPSTREAM_REPO;
+            const pull_number = Number(process.env.UPSTREAM_PR_NUMBER);
+            const issue_number = Number(process.env.TARGET_ISSUE_NUMBER);
+            const marker = process.env.COMMENT_MARKER;
+            const readyLabel = process.env.READY_LABEL;
+            const stopLabel = process.env.STOP_LABEL;
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number });
+            const desiredLabel = pr.merged_at ? readyLabel : stopLabel;
+            const staleLabel = pr.merged_at ? stopLabel : readyLabel;
+            const { data: issue } = await github.rest.issues.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+            });
+
+            if (!issue.labels.some((label) => label.name === desiredLabel)) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number,
+                labels: [desiredLabel],
+              });
+              core.info(`Added label ${desiredLabel} to issue #${issue_number}.`);
+            }
+
+            if (issue.labels.some((label) => label.name === staleLabel)) {
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number,
+                  name: staleLabel,
+                });
+                core.info(`Removed label ${staleLabel} from issue #${issue_number}.`);
+              } catch (error) {
+                core.warning(`Failed to remove label ${staleLabel}: ${error.message}`);
+              }
+            }
+
+            core.summary
+              .addHeading('Codex PR status')
+              .addTable([
+                [
+                  { data: 'Field', header: true },
+                  { data: 'Value', header: true },
+                ],
+                ['PR', `${owner}/${repo}#${pr.number}`],
+                ['Title', pr.title],
+                ['State', pr.state],
+                ['Merged', pr.merged_at ? 'yes' : 'no'],
+                ['Merged at', pr.merged_at ?? 'not merged'],
+                ['Updated at', pr.updated_at],
+                ['URL', pr.html_url],
+              ]);
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              per_page: 100,
+            });
+
+            const existingComment = comments.find((comment) => comment.body?.includes(marker));
+            const body = [
+              marker,
+              'upstream PR `openai/codex#13537` status watcher',
+              '',
+              `- PR: ${pr.html_url}`,
+              `- State: ${pr.state}`,
+              `- Merged: ${pr.merged_at ? 'yes' : 'no'}`,
+              `- Merged at: ${pr.merged_at ?? 'not merged'}`,
+              `- Updated at: ${pr.updated_at}`,
+              '',
+              pr.merged_at
+                ? 'This PR has been merged. `codex exec --fork <SESSION_ID> [PROMPT]` should become available once the change lands in the installed Codex version.'
+                : 'This PR is not merged yet. Non-interactive forking is still not available in released Codex builds.',
+              'A new session ID is expected when using `--fork`; `resume` itself continues the same session.',
+            ].join('\n');
+
+            if (existingComment?.body === body) {
+              core.info(`Issue #${issue_number} status comment is already up to date.`);
+              await core.summary.addRaw(`No update needed: ${existingComment.html_url}\n`).write();
+              return;
+            }
+
+            if (existingComment) {
+              const { data: comment } = await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existingComment.id,
+                body,
+              });
+              core.info(`Updated issue #${issue_number}: ${comment.html_url}`);
+              await core.summary.addRaw(`Updated status comment: ${comment.html_url}\n`).write();
+              return;
+            }
+
+            const { data: comment } = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              body,
+            });
+            core.info(`Created issue #${issue_number} status comment: ${comment.html_url}`);
+            await core.summary.addRaw(`Created status comment: ${comment.html_url}\n`).write();
+
+  watch-gemini-session-work:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check Gemini session PRs and update issue
+        uses: actions/github-script@v7
+        env:
+          UPSTREAM_OWNER: google-gemini
+          UPSTREAM_REPO: gemini-cli
+          TARGET_ISSUE_NUMBER: '16'
+          COMMENT_MARKER: '<!-- gemini-session-pr-status -->'
+          WATCH_PR_NUMBERS: '17921,19629,19994'
+          READY_PR_NUMBERS: '17921,19629'
+          READY_LABEL: '[ready]'
+          STOP_LABEL: '[stop]'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = process.env.UPSTREAM_OWNER;
+            const repo = process.env.UPSTREAM_REPO;
+            const issue_number = Number(process.env.TARGET_ISSUE_NUMBER);
+            const marker = process.env.COMMENT_MARKER;
+            const pullNumbers = process.env.WATCH_PR_NUMBERS.split(',').map((value) => Number(value.trim()));
+            const readyPullNumbers = process.env.READY_PR_NUMBERS.split(',').map((value) => Number(value.trim()));
+            const readyLabel = process.env.READY_LABEL;
+            const stopLabel = process.env.STOP_LABEL;
+
+            const pulls = await Promise.all(
+              pullNumbers.map(async (pull_number) => {
+                const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number });
+                return pr;
+              }),
+            );
+            const isReady = pulls.some((pr) => readyPullNumbers.includes(pr.number) && Boolean(pr.merged_at));
+            const desiredLabel = isReady ? readyLabel : stopLabel;
+            const staleLabel = isReady ? stopLabel : readyLabel;
+
+            const { data: issue } = await github.rest.issues.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+            });
+
+            if (!issue.labels.some((label) => label.name === desiredLabel)) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number,
+                labels: [desiredLabel],
+              });
+              core.info(`Added label ${desiredLabel} to issue #${issue_number}.`);
+            }
+
+            if (issue.labels.some((label) => label.name === staleLabel)) {
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number,
+                  name: staleLabel,
+                });
+                core.info(`Removed label ${staleLabel} from issue #${issue_number}.`);
+              } catch (error) {
+                core.warning(`Failed to remove label ${staleLabel}: ${error.message}`);
+              }
+            }
+
+            const lines = pulls.flatMap((pr) => [
+              `- \`${owner}/${repo}#${pr.number}\` ${pr.title}`,
+              `  - State: ${pr.state}`,
+              `  - Merged: ${pr.merged_at ? 'yes' : 'no'}`,
+              `  - Merged at: ${pr.merged_at ?? 'not merged'}`,
+              `  - Updated at: ${pr.updated_at}`,
+              `  - URL: ${pr.html_url}`,
+            ]);
+
+            core.summary
+              .addHeading('Gemini PR status')
+              .addTable([
+                [
+                  { data: 'PR', header: true },
+                  { data: 'State', header: true },
+                  { data: 'Merged', header: true },
+                  { data: 'Updated at', header: true },
+                ],
+                ...pulls.map((pr) => [
+                  `${owner}/${repo}#${pr.number}`,
+                  pr.state,
+                  pr.merged_at ? 'yes' : 'no',
+                  pr.updated_at,
+                ]),
+              ]);
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              per_page: 100,
+            });
+
+            const existingComment = comments.find((comment) => comment.body?.includes(marker));
+            const body = [
+              marker,
+              'upstream Gemini CLI session-related PR status watcher',
+              '',
+              'Tracked PRs:',
+              ...lines,
+              '',
+              'Interpretation:',
+              '- `#19994` is a fix for resumed session ID stats mismatch, not a fork/new-session feature.',
+              '- `#17921` is the `/new` command proposal for starting a fresh session while preserving the previous one.',
+              '- `#19629` is the `--session-id` proposal for explicit session UUID control.',
+              '- Even if these land, that still does not automatically imply Codex-style headless fork semantics from `--resume` alone.',
+            ].join('\n');
+
+            if (existingComment?.body === body) {
+              core.info(`Issue #${issue_number} Gemini status comment is already up to date.`);
+              await core.summary.addRaw(`No update needed: ${existingComment.html_url}\n`).write();
+              return;
+            }
+
+            if (existingComment) {
+              const { data: comment } = await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existingComment.id,
+                body,
+              });
+              core.info(`Updated issue #${issue_number}: ${comment.html_url}`);
+              await core.summary.addRaw(`Updated status comment: ${comment.html_url}\n`).write();
+              return;
+            }
+
+            const { data: comment } = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              body,
+            });
+            core.info(`Created issue #${issue_number} status comment: ${comment.html_url}`);
+            await core.summary.addRaw(`Created status comment: ${comment.html_url}\n`).write();

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [2.12.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.11.0...v2.12.0) (2026-03-12)
+
+
+### Features
+
+* ai-cliコマンドを追加しアーキテクチャをリファクタリング ([10a1209](https://github.com/mkXultra/ai-cli-mcp/commit/10a120933d5893d47e47001a165f0abc5e4557aa))
+* CliProcessServiceとCLIサブコマンドを追加 ([0043ee4](https://github.com/mkXultra/ai-cli-mcp/commit/0043ee4a73bbf2d48f57b0b0ded8f12e29e8ebf2))
+* CLIサブコマンドhelpとcleanupを追加し状態保存先を再設計 ([63dc1a2](https://github.com/mkXultra/ai-cli-mcp/commit/63dc1a238e9883cab04e818413576ad265b600ab))
+* doctorとmodelsサブコマンドを追加しモデルカタログをモジュール化 ([15222e3](https://github.com/mkXultra/ai-cli-mcp/commit/15222e3c29c18bc16fa0bc7d6c4f3bdc621f6ff6))
+
+# [2.11.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.10.0...v2.11.0) (2026-03-08)
+
+
+### Features
+
+* ClaudeモデルへのReasoning Effort（--effort）サポートを追加 ([ac6b8cc](https://github.com/mkXultra/ai-cli-mcp/commit/ac6b8cc47a06a2d207258e85cc21b1d4ce83e5b2))
+
 # [2.10.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.9.1...v2.10.0) (2026-03-07)
 
 

package/README.ja.md

@@ -9,6 +9,10 @@ AI CLIツール（Claude, Codex, Gemini）をバックグラウンドプロセ
 
 Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦戦していることに気づいたことはありませんか？このサーバーは、強力な統合 `run` ツールを提供し、複数のAIエージェントを活用してコーディングタスクをより効果的に処理できるようにします。
 
+## デモ
+
+[![デモ](docs/assets/demo-jp.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo-jp.mp4)
+
 ## 概要
 
 このMCPサーバーは、LLMがAI CLIツールと対話するためのツールを提供します。MCPクライアントと統合することで、LLMは以下のことが可能になります：
@@ -45,6 +49,8 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 >    - `gpt-5.2-codex` で `README.md` にアーキテクチャの解説を追記
 > 4. 最後に再び `wait` して、両方の結果をまとめてください。
 
+[![セッション再開デモ](docs/assets/demo-resume-jp.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo-resume-jp.mp4)
+
 ## メリット
 
 - **真の非同期マルチタスク**: エージェントの実行はバックグラウンドで行われ、即座に制御が戻ります。呼び出し元のAIは実行完了を待つことなく、並行して次のタスクの実行や別のエージェントの呼び出しを行うことができます。
@@ -61,9 +67,16 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 
 ## インストールと使い方
 
-推奨される使用方法は、`npx` を使用してインストールすることです。
+現在の主な使い方は 2 つあります。
+
+- `ai-cli-mcp`: MCP サーバーの起動
+- `ai-cli`: 人間向け CLI
+
+### MCP 利用 (`npx`)
 
-### MCP設定ファイルでnpxを使用する場合:
+MCP サーバーとして使う場合は、`npx` 経由が推奨です。
+
+#### MCP設定ファイルでnpxを使用する場合:
 
 ```json
     "ai-cli-mcp": {
@@ -75,12 +88,47 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
     },
 ```
 
-### Claude CLI mcp add コマンドを使用する場合:
+#### Claude CLI mcp add コマンドを使用する場合:
 
 ```bash
 claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
 ```
 
+### 人間向け CLI 利用 (グローバルインストール)
+
+シェルから `ai-cli` を直接使いたい場合は、グローバルインストールしてください。
+
+```bash
+npm install -g ai-cli-mcp
+```
+
+これで以下の 2 つのコマンドが使えるようになります。
+
+- `ai-cli`
+- `ai-cli-mcp`
+
+例:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli ps
+ai-cli result 12345
+ai-cli wait 12345 --timeout 300
+ai-cli kill 12345
+ai-cli cleanup
+ai-cli-mcp
+```
+
+### 人間向け CLI 利用 (`npx`)
+
+公開パッケージ名はまだ `ai-cli-mcp` のままなので、`npx` で `ai-cli` を使う場合は次の形になります。
+
+```bash
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+```
+
 ## 重要な初回セットアップ
 
 ### Claude CLIの場合:
@@ -112,6 +160,56 @@ gemini auth login
 
 macOSでは、これらのツールを初めて実行する際にフォルダへのアクセス許可を求められる場合があります。最初の実行が失敗しても、2回目以降は動作するはずです。
 
+## CLI コマンド
+
+`ai-cli` は現在以下をサポートしています。
+
+- `run`
+- `ps`
+- `result`
+- `wait`
+- `kill`
+- `cleanup`
+- `doctor`
+- `models`
+- `mcp`
+
+基本的な流れ:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli ps
+ai-cli wait 12345
+ai-cli result 12345
+ai-cli cleanup
+```
+
+`run` の作業ディレクトリ指定は `--cwd` が基本です。互換性のために `--workFolder` / `--work-folder` も受け付けます。
+
+`doctor` は CLI バイナリの存在確認と path 解決だけを行います。ログイン状態や利用規約同意までは確認しません。
+
+## CLI の状態保存先
+
+バックグラウンド実行した `ai-cli` の状態は、次のディレクトリに保存されます。
+
+```text
+~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/
+```
+
+各 PID ディレクトリには以下が入ります。
+
+- `meta.json`
+- `stdout.log`
+- `stderr.log`
+
+完了済み・失敗済みの実行は `ai-cli cleanup` で削除できます。`running` のものは保持されます。
+
+## 既知の制約
+
+detached 実行された `ai-cli` の自然終了 exit code は、まだ永続化していません。そのため、CLI は出力と running/completed 状態は返せますが、自然終了したバックグラウンド実行の `exitCode` は現時点では保証しません。
+
 ## MCPクライアントへの接続
 
 サーバーのセットアップ後、MCPクライアント（CursorやWindsurfなど）の設定ファイル（`mcp.json` や `mcp_config.json`）に設定を追加してください。
@@ -131,11 +229,11 @@ Claude CLI、Codex CLI、またはGemini CLIを使用してプロンプトを実
 - `prompt_file` (string, 任意): プロンプトを含むファイルへのパス。`prompt` または `prompt_file` のいずれかが必須です。絶対パス、または `workFolder` からの相対パスが指定可能です。
 - `workFolder` (string, 必須): CLIを実行する作業ディレクトリ。絶対パスである必要があります。
 - **モデル (Models):**
-    - **Ultra エイリアス:** `claude-ultra`, `codex-ultra` (自動的に high-reasoning に設定), `gemini-ultra`
+    - **Ultra エイリアス:** `claude-ultra` (自動的に high effort に設定), `codex-ultra` (自動的に xhigh reasoning に設定), `gemini-ultra`
     - 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`
     - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
-- `reasoning_effort` (string, 任意): Codex専用。`model_reasoning_effort` を設定します（許容値: "low", "medium", "high", "xhigh"）。
+- `reasoning_effort` (string, 任意): Claude と Codex の推論制御。Claude では `--effort` を使います（許容値: "low", "medium", "high"）。Codex では `model_reasoning_effort` を使います（許容値: "low", "medium", "high", "xhigh"）。
 - `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。
 
 ### `wait`
@@ -167,6 +265,7 @@ PIDを指定して、実行中のAIエージェントプロセスを終了しま
 ## トラブルシューティング
 
 - **"Command not found" (claude-code-mcp):** グローバルにインストールした場合、npmのグローバルbinディレクトリがシステムのPATHに含まれているか確認してください。`npx` を使用している場合、`npx` 自体が機能しているか確認してください。
+- **"Command not found" (`ai-cli`):** グローバルインストール時は npm のグローバル bin ディレクトリが `PATH` に入っているか確認してください。`npx` の場合は `npx -y --package ai-cli-mcp@latest ai-cli ...` を使ってください。
 - **"Command not found" (claude または ~/.claude/local/claude):** Claude CLIが正しくインストールされていることを確認してください。`claude/doctor` を実行するか、公式ドキュメントを確認してください。
 - **権限の問題:** 「重要な初回セットアップ」の手順を実行したか確認してください。
 - **サーバーからのJSONエラー:** `MCP_CLAUDE_DEBUG` が `true` の場合、エラーメッセージやログがMCPのJSON解析を妨げる可能性があります。通常動作時は `false` に設定してください。

package/README.md

@@ -11,6 +11,10 @@ An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude,
 
 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.
 
+## Demo
+
+[![Demo](docs/assets/demo.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo.mp4)
+
 ## Overview
 
 This MCP server provides tools that can be used by LLMs to interact with AI CLI tools. When integrated with MCP clients, it allows LLMs to:
@@ -44,6 +48,8 @@ You can reuse heavy context (like large codebases) using session IDs to save cos
 >    - Add architecture documentation to `README.md` using `gpt-5.2-codex`
 > 4. Finally, `wait` again to combine both results.
 
+[![Session Resume Demo](docs/assets/demo-resume.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo-resume.mp4)
+
 ## Benefits
 
 - **True Async Multitasking**: Agent execution happens in the background, returning control immediately. The calling AI can proceed with the next task or invoke another agent without waiting for completion.
@@ -60,9 +66,16 @@ The only prerequisite is that the AI CLI tools you want to use are locally insta
 
 ## Installation & Usage
 
-The recommended way to use this server is by installing it by using `npx`.
+There are now two primary ways to use this package:
+
+- `ai-cli-mcp`: MCP server entrypoint
+- `ai-cli`: human-facing CLI for background AI runs
+
+### MCP usage with `npx`
 
-### Using npx in your MCP configuration:
+The recommended way to use the MCP server is via `npx`.
+
+#### Using npx in your MCP configuration:
 
 ```json
     "ai-cli-mcp": {
@@ -74,12 +87,47 @@ The recommended way to use this server is by installing it by using `npx`.
     },
 ```
 
-### Using Claude CLI mcp add command:
+#### Using Claude CLI mcp add command:
 
 ```bash
 claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
 ```
 
+### Human CLI usage with global install
+
+If you want to use the production CLI directly from your shell, install the package globally:
+
+```bash
+npm install -g ai-cli-mcp
+```
+
+This exposes both commands:
+
+- `ai-cli`
+- `ai-cli-mcp`
+
+Examples:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli ps
+ai-cli result 12345
+ai-cli wait 12345 --timeout 300
+ai-cli kill 12345
+ai-cli cleanup
+ai-cli-mcp
+```
+
+### Human CLI usage with `npx`
+
+Because the published package name is still `ai-cli-mcp`, the shortest `npx` form for the CLI is:
+
+```bash
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+```
+
 ## Important First-Time Setup
 
 ### For Claude CLI:
@@ -111,6 +159,56 @@ gemini auth login
 
 macOS might ask for folder permissions the first time any of these tools run. If the first run fails, subsequent runs should work.
 
+## CLI Commands
+
+`ai-cli` currently supports:
+
+- `run`
+- `ps`
+- `result`
+- `wait`
+- `kill`
+- `cleanup`
+- `doctor`
+- `models`
+- `mcp`
+
+Example flow:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli ps
+ai-cli wait 12345
+ai-cli result 12345
+ai-cli cleanup
+```
+
+`run` accepts `--cwd` as the primary working-directory flag and also accepts the older aliases `--workFolder` / `--work-folder` for compatibility.
+
+`doctor` checks only binary existence and path resolution. It does not verify login state or terms acceptance.
+
+## CLI State Storage
+
+Background CLI runs are stored under:
+
+```text
+~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/
+```
+
+Each PID directory contains:
+
+- `meta.json`
+- `stdout.log`
+- `stderr.log`
+
+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.
+
 ## Connecting to Your MCP Client
 
 After setting up the server, add the configuration to your MCP client's settings file (e.g., `mcp.json` for Cursor, `mcp_config.json` for Windsurf).
@@ -130,11 +228,11 @@ Executes a prompt using Claude CLI, Codex CLI, or Gemini CLI. The appropriate CL
 - `prompt_file` (string, optional): Path to a file containing the prompt. Either `prompt` or `prompt_file` is required. Can be absolute path or relative to `workFolder`.
 - `workFolder` (string, required): The working directory for the CLI execution. Must be an absolute path.
 **Models:**
-- **Ultra Aliases:** `claude-ultra`, `codex-ultra` (defaults to high-reasoning), `gemini-ultra`
+- **Ultra Aliases:** `claude-ultra` (defaults to high effort), `codex-ultra` (defaults to xhigh reasoning), `gemini-ultra`
 - 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`
 - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
-- `reasoning_effort` (string, optional): Codex only. Sets `model_reasoning_effort` (allowed: "low", "medium", "high", "xhigh").
+- `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").
 - `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.
 
 ### `wait`
@@ -166,6 +264,7 @@ Terminates a running AI agent process by PID.
 ## Troubleshooting
 
 - **"Command not found" (claude-code-mcp):** If installed globally, ensure the npm global bin directory is in your system's PATH. If using `npx`, ensure `npx` itself is working.
+- **"Command not found" (`ai-cli`):** If installed globally, ensure your npm global bin directory is in `PATH`. If using `npx`, use `npx -y --package ai-cli-mcp@latest ai-cli ...`.
 - **"Command not found" (claude or ~/.claude/local/claude):** Ensure the Claude CLI is installed correctly. Run `claude/doctor` or check its documentation.
 - **Permissions Issues:** Make sure you've run the "Important First-Time Setup" step.
 - **JSON Errors from Server:** If `MCP_CLAUDE_DEBUG` is `true`, error messages or logs might interfere with MCP's JSON parsing. Set to `false` for normal operation.