aiterm-mcp

> **From any MCP client, launch Claude Code, Codex CLI, Grok CLI, or Cursor Agent CLI through one harness API inside a persistent interactive TUI.**

<p align="center">
  <img src="https://raw.githubusercontent.com/kitepon/aiterm-mcp/main/.github/og.png" alt="Aiterm — a shared forest observatory where different intelligences work in one persistent execution space" width="100%">
  <br>
  <sub><em>This image represents different intelligences sharing one persistent workspace and advancing the same work from their own perspectives.</em></sub>
</p>

# Aiterm

[![CI](https://github.com/kitepon/aiterm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kitepon/aiterm-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
[![weekly downloads](https://img.shields.io/npm/dw/aiterm-mcp.svg)](https://www.npmjs.com/package/aiterm-mcp)
[![node](https://img.shields.io/node/v/aiterm-mcp)](https://nodejs.org)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> *(日本語: [README.ja.md](README.ja.md))*

> **Let your AI orchestrate other AIs.** One `agent_launch` call selects the execution harness separately from its model and hands you a persistent session to drive. Cursor can run GPT, Claude, or Grok while Cursor still owns the session, hooks, and transcript.
>
> **What it is:** one persistent MCP terminal your AI drives — and can launch other coding agents into. `ssh`, `docker exec`, a REPL, or another agent's TUI all nest inside that one terminal as just text you send in. The mechanism is deliberately plain — your MCP client drives the other agent's terminal turn by turn: no hidden protocol, no separate aiterm-owned shared-memory layer, no autonomous negotiation. Launched agents still read the normal project and harness memory/configuration that a direct CLI launch would use.
>
> **No human at a terminal required.** aiterm is driven programmatically over MCP, so an AI can launch and drive another agent with no one sitting in the terminal — from an orchestration loop, a CI step, or a cron job.
>
> *MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.*

Built and maintained by [Quo at kitepon.dev](https://kitepon.dev/en).

## Install in your MCP client

検出したClaude Code・Codex・Grok・Cursorのユーザー設定へ登録する標準入口:

```bash
npm install -g aiterm-mcp@latest
aiterm-setup --json
```

`aiterm-setup`は端末の依存準備、MCP経由の端末実行、登録と読戻しまでを一回で行う。
WindowsはwingetでPowerShell 7・Git for Windows・psmux、macOSはHomebrewでtmux、
Ubuntu／Debianはsudoとaptでtmuxを準備する。必要な公式package managerと実行権限は事前に必要。
他のLinuxでも既存tmuxを利用できるが、自動導入は`unsupported`で停止する。
既存設定の他サーバーを保持し、JSON設定は変更前の`.aiterm-backup`を残す。
結果の`status`は`ready`／`unsupported`／`failed`／`restart_required`。未検出のAIは`not_detected`とし、全AI未検出は成功にしない。
登録先はglobal packageのNodeとMCP入口の絶対パスで、npm一時cacheやsource checkoutは登録しない。
global packageは、npmの現在のglobal rootか、実行中のNodeの既定のglobal rootにあるものを指す。npmのprefixを利用者ごとの場所へ向けた環境でも、共通の場所へ導入したAitermを登録できる。
CodexとGrokは、登録が同じなら公式CLIで作り直さず、利用者が足した項目（待ち時間など）を保つ。
HomebrewのNodeは更新後も有効な`opt`のパスをMCP登録とCodexのhookに使う。旧版の登録でNode更新後に起動できなくなった場合も、更新後の`aiterm-setup --json`で修復できる。
更新後も同じ入口を実行し、MCP clientを再起動する。npm install自体はユーザー設定を変更しない。
公開JSONは`schema: "aiterm.setup-result.v1"`、全体の`status`、端末の`backend`、
AI別の`integrations`と選択機能の`codex_steer`を持つ。失敗時は`reason_code`を付け、終了コードはreadyなら0、再起動待ちは3、それ以外は2となる。

MCP登録を利用者や他の製品が管理する環境では、`aiterm-setup --hooks-only`でClaude Code・Cursorの親配送hookだけを登録できる。
依存準備、端末の実動作確認、MCP登録、Codex Steerには触れない。登録済みなら設定を書き換えない。
結果は`schema: "aiterm.parent-hooks-result.v1"`、全体の`status`（`ready`／`unsupported`／`failed`）、AI別の`hooks`（`configured`／`unchanged`／`not_detected`／`failed`）を持つ。終了コードはreadyなら0、それ以外は2となる。


### CodexへSteerを有効にする（macOS・Windows・Linux）

対話実行の`aiterm-setup`で「Aiterm単品」と「Steer付き」を選べます。無人導入では明示します。

```bash
aiterm-setup --json --codex-steer enable
```

公式キューと公式hookを使い、実行中の親には同じターンの次の推論へ回答を渡し、終了後は同じ会話を自動再開します。
Codexの起動プログラムと通常のstdio通信は変更しません。hookの実行ファイルが失われてもCodexの起動・応答は継続します。
終了後の再開は公式キューの監視周期に従い、約10秒かかる場合があります。

`aiterm-setup`は`CODEX_HOME/hooks.json`へ専用の`PostToolUse`と`Stop`を追加し、公式APIでその2件だけを承認・読戻しします。
他のhookや承認は保持します。選択と配送の所有記録は`~/.config/aiterm-mcp/codex-parent-hooks/`へ保存します。
同じ設定で再実行しても既存hookの順序を変えず、新たな再起動要求を発生させません。
WindowsのhookはPowerShell 7で実行します。更新後のsetupで、既存のAiterm hookコマンドも更新します。
既存の中継は新しいhookの確認後に解除し、保存していた`CODEX_CLI_PATH`を復元します。macOSの専用LaunchAgentも解除します。
移行前から動いているCodexがあれば`restart_required`（終了コード3）を返します。完全終了・再起動後に
`aiterm-setup --codex-steer status`で`ready`を確認してください。旧設定は移行を実行するまで維持します。

hookはAiterm自身の配送記録と本文が一致する回答だけを取り出し、利用者がキューに入れた入力は保持します。
取り出し中断や出力失敗は`parent_deliveries`に`unknown`と`CODEX_HOOK_DELIVERY_UNCONFIRMED`で現れ、本文を保存します。
自動再送はしません。長い回答はCodexの公式hook処理で抜粋と全文ファイルへの参照になる場合があります。

解除・hook未対応の旧版への巻き戻し前は`aiterm-setup --codex-steer disable`を実行してCodexを再起動してください。
公式Codex Desktop（macOS・Windows・Linux）の同梱CLIを先に使い、Desktopが無い端末では通常のCodex CLI（公式キュー・hookに対応する0.154以上）を使います。
When a Desktop update moves the bundled Codex CLI, Aiterm finds it again at use time and updates its configuration. If it cannot, it returns `CODEX_DESKTOP_BINARY_MOVED`; start Desktop and rerun setup.
Aiterm単品の公式キュー配送は従来どおり利用できます。

No clone or build is required. Each client launches the published package with:

```bash
npx -y aiterm-mcp
```

Requires **Node.js ≥ 18** and a supported multiplexer backend: **tmux** on POSIX or **psmux 3.3.8+** on native Windows. Driving Codex also requires the Codex CLI to be installed and authenticated.

### Claude Code

Add it for your user account:

```bash
claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
```

Or commit this as a project-scoped `.mcp.json`:

```json
{
  "mcpServers": {
    "aiterm": {
      "command": "npx",
      "args": ["-y", "aiterm-mcp"]
    }
  }
}
```

### Claude Desktop

Add this server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aiterm": {
      "command": "npx",
      "args": ["-y", "aiterm-mcp"]
    }
  }
}
```

### Cursor

Save this as `.cursor/mcp.json` for the project, or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "aiterm": {
      "command": "npx",
      "args": ["-y", "aiterm-mcp"]
    }
  }
}
```

**Ownership boundary:** this repository owns installation, configuration, persistent PTYs,
agent sessions, state/schema/migrations, diagnostics, recovery, updates, and releases. It can
be cloned and operated on its own using this README and the [product docs](docs/00_overview.md).
[dotagents](https://github.com/kitepon/dotagents) optionally integrates Aiterm into the wider
factory—host wiring, cross-product compatibility, and aggregate acceptance—but does not control
Aiterm and is not a runtime dependency.

**Measured, not claimed:** in the recorded 203-test benchmark, a `pty_read` puts **~7.1× fewer tokens** in your context than the raw log — and the pass/fail verdict survives the fold. → [When to reach for it vs. the built-in shell](#when-to-reach-for-it-vs-the-built-in-shell)

18 tools: seven **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` / `pty_observe` — to open, drive, read, and observe one persistent terminal; one canonical **agent launcher**, `agent_launch`, which selects `claude-code`, `codex-cli`, `grok-cli`, or `cursor-cli` as the execution harness; three deprecated launcher aliases kept for migration; `agent_models`; `agent_configure`; `agent_auth`; `agent_approval`; `claude_turn`; `claude_approval`; and `diagnostics`. The backend is **tmux on POSIX and psmux on native Windows**, so sessions survive even if the MCP server or the AI client restarts.

**v0.28.0 separates the execution harness from the model.** The harness owns the agent loop, authentication, hooks, session, and transcript; `model` is what that harness runs. Cursor Agent CLI can therefore select GPT, Claude, or Grok without changing the completion contract from Cursor hooks to another harness's. Composer is one of Cursor's models, not a harness and not a Grok model: use `harness: "cursor-cli", model: "composer-2.5-fast"` (or `composer-2.5`). The old launcher tools are thin compatibility aliases over the same implementation.

**v0.25.2 stabilizes repeated in-place configuration changes, including Grok 4.6.** If Grok Build
1.0.3 redraws before its `/model` success notice can be observed, aiterm confirms the requested model/effort
from the persistent footer when that state was absent before the command. Callers do not retry, restart, or
round a failure into success; explicit `grok-4.6` launch and configuration still pass the live catalog check.

**v0.25.0 gives Grok and Composer the same shared launcher controls.** Their launchers now pass
`reasoning_effort`, enforce `write_scope: "read-only"` with `--sandbox read-only`, and support
in-place model/effort changes through `agent_configure`. Before creating a PTY, aiterm checks an
explicit Grok/Composer model—and Composer's default model—against the live `grok models` catalog.
An unavailable model fails visibly instead of letting the harness CLI fall back to another model.
Composer has since left the Grok CLI and is now one of Cursor's models.

**v0.24.3 forwards explicitly selected launcher environment variables from the current MCP process.**
Pass variable names in `env_vars`; aiterm reads their current values at launch and injects only the
present ones into that agent. This works even when the persistent multiplexer server predates the MCP
process, so a stale backend-server environment cannot erase per-seat identity or workflow variables.
It also recognizes Codex v0.147's optional `fast` token in long-lived model/effort footers, keeping
`agent_configure` available on an idle `medium fast ·` session without redraw, retry, or restart.

**v0.24.2 keeps in-place configuration working in long-lived Codex sessions.** Once the
startup header has scrolled out of the captured pane, aiterm recognizes Codex by its persistent
model/effort footer together with the input prompt. An