> From any MCP client, launch Claude Code, Codex CLI, Grok CLI, or Cursor Agent CLI through one harness API inside a persistent interactive TUI.
This image represents different intelligences sharing one persistent workspace and advancing the same work from their own perspectives.
Aiterm
> (日本語: 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.
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秒かかる場合があります。
Codexのアプリは、見ていない会話を60秒で寝かせます。寝ている会話のキューは、その会話が開かれるまで動きません。
Aitermは、入れた約15秒後にまだ文が残っていて、番が普通に終わって寝ている会話なら、アプリにその会話を開かせて起こします(codex://threads/<会話>)。
その時、アプリの画面はその会話へ切り替わります。番の途中の会話、途中で止められた会話、CLIの席は起こしません。止める時は環境変数AITERM_STEER_CODEX_WAKE=0を立てます。
起こすのはmacOSとWindowsのアプリです。Linuxのアプリが寝かせた会話は、まだ起こしません(実物で確かめられていません。会話が開かれた時に届きます)。
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.
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
19 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_goal`; `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 idle session is therefore configured
directly; callers do not need to redraw the TUI, retry, or restart the agent.
**v0.24.0 adds in-place agent configuration.** `agent_configure` uses each harness's
native controls to change the model and/or reasoning effort of a running Codex or Claude
session while preserving its PTY, harness session, and conversation context.
**v0.23.0 adds a local, cross-harness portable fork.** Pass `throughline_source_session`
with a mission in `prompt` to any launcher, and aiterm asks the locally installed Throughline
for that session's read-only handoff context before creating the PTY. The exact returned memory
is prepended to the mission without moving or copying the source session's database ownership.
If Throughline is missing or returns an invalid/empty result, launch fails visibly with no clean
fallback. Omitting the field preserves the ordinary clean launch.
**v0.22.0 makes launched agents full project collaborators.** All four launchers now use the
same normal `HOME`, working tree, harness home, project/user/local configuration, MCP servers,
plugins, skills, permissions, trust, memory, and session history as a direct CLI launch. Aiterm
isolates only its own per-launch completion correlation state. Every child is told that it is a
sub-agent and receives its parent session, delegation depth, lineage, and
`delegation_allowed=true`; a child may delegate further, while the lineage makes reflexive
self-copy loops visible and avoidable. The historical `managed_completion` receipt field remains
for API compatibility and means “completion correlation enabled,” not environment isolation.
**v0.21.3 removes Codex Stop hooks from the completion path.** Codex completion and
final-message attribution now come from the root rollout transcript's durable
`task_complete.turn_id`, observed after the dispatch byte boundary. A broken or stale
hook executable can no longer strand `aiterm-wait`. v0.21.0 added explicit
`write_scope` declarations for external-agent launchers; v0.21.3 also fixes their
structured launch receipts so a supplied scope and its enforcement status are retained.
v0.20.3 prevents concurrent
correlated Claude/Fable sessions from turning one broken login into many competing login
flows. Every new Claude launch verifies the
harness-owned shared credential store before creating a PTY, while healthy credentials
remain reusable across concurrent and repeated sessions. The v0.20 line also distinguishes
a non-blocking `aiterm-wait --timeout 0` observation (`running`, exit 5) from a real timed-out
wait. The v0.19 line added the correlated Claude approval relay,
preserved multiline shell delivery, and extended factory diagnostics on native
Windows. As of v0.16/0.17 a parent agent never blocks on aiterm:
agent sessionへの送信は非ブロックdispatchであり、Codex/Claude Code親には回答本文を自動配送する。
それ以外の親はreceiptのprocess起動情報で`aiterm-wait`を実行する。
終了コードは`0`=done、`3`=timeout、`4`=closed、待機しない照会の`5`=runningを表す。
Factory diagnostics and the local runtime-error store collect only when
canonical dotagents config explicitly sets `collection.enabled: true`;
collection is off by default and performs no network I/O. It ships via
tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
Release re-registers the Official MCP Registry entry.
**Status:** actively maintained · current public release **v0.61.24** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible psmux on native Windows — no WSL required) · MIT · see the CHANGELOG.
### Update and rollback
The npm package is the standalone distribution; dotagents is not involved. For a global install,
update with `aiterm-update`. It reinstalls the requested version into the same npm prefix, then reruns the new version's
`aiterm-setup --json` to re-register and re-verify.```bash
aiterm-update # this machine to latest
aiterm-update --host rabbit --host win-test # this machine and SSH hosts to the same version
aiterm-update --version 0.39.0 --check # report current and target versions without changing anything
--host takes an ~/.ssh/config alias or host name; hosts are not stored. The version is resolved once on the calling
machine so every host lands on the same version. Hosts older than aiterm-update get it through npm first. When the
npm prefix is not writable, the result is permission_required with the command to run as an administrator. aiterm-mcp
servers that were already running keep the old code until their MCP client restarts (running_servers); tmux/psmux
sessions survive. Versions without aiterm-update use npm install -g aiterm-mcp@latest and aiterm-setup --json. To roll back, install a known-good immutable version,
for example npm install -g "aiterm-mcp@", then restart the MCP client. setupを持つ版では再起動前にaiterm-setup --jsonを再実行する。For an npx configuration,
use aiterm-mcp@latest to update or replace it with aiterm-mcp@ to pin or roll back.
Check the CHANGELOG for state/schema compatibility before downgrading. Maintainer
release and artifact rollback are specified in the product-owned release procedure.
Why now
A lot of 2026's agent tooling is converging on orchestration: a lead model delegating a mechanical refactor to Codex, running Composer on a bulk edit while it reviews the diff, fanning one task across several agents to spare its own context window. All of those agents already live in a terminal. aiterm makes that terminal a first-class, MCP-native tool — so the model doing the orchestrating can spawn and steer the others without a human wiring up panes.
Built with Codex and GPT-5.6 for OpenAI Build Week 2026
aiterm predates Build Week, so the event work is kept visible in dated commits. During the submission window (July 14–16, 2026), I extended it with safe serialized delivery for long PTY input, correlated operation IDs and bounded result recovery, machine-readable launch and idempotent close receipts, and a hardened readiness gate that prevents prompts from disappearing during TUI startup redraws. The public comparison from the pre-event release is v0.12.2...main.
I used Codex with GPT-5.6 as an engineering collaborator: it inspected the implementation, challenged the API and recovery contracts, generated focused regression cases, and helped verify race, security, timeout, and malformed-event paths. I reviewed the diffs and test evidence and retained the final product and architecture decisions. At that Build Week checkpoint, the regression suite contained 262 tests covering normal operation as well as failure and recovery behavior; current release receipts live in the CHANGELOG and release ADRs.
ClaudeがAPIエラーや安全判定の拒否で終了した時は、Stop hookが発火しなくても次のpty_sendを新しいturnとして扱う。現在のturn開始後のエラー記録だけを確認し、過去のエラーで実行中のturnを解除しない。上流の拒否はエラーのまま返す。
Codexがサービスの誤りや通信の失敗でturnを打ち切った時は、完了待ちがdoneではなくerrorを返す(aiterm-waitはexit 7、親への配送はoutcome=error)。errorは応答の本文とURLを落とした1行の文で、Codexが記録した種類(internal_server_error・http_connection_failedなど)はerror_kindに載る。利用上限は今までどおりrate_limited。誤りで終わった後の席は、次のpty_sendを新しいturnとして受ける。
Cursorが誤りでturnを終えた時(記録のturn_endedがstatus: "error")も同じで、完了待ちはerrorを返し、文の頭の角括弧の名前(unavailableなど)をerror_kindに載せる。利用上限の文はrate_limited、席で止めたturn(User aborted request)は今までどおりdone。
Two ways to use it
1. Drive SSH, containers, and REPLs in one persistent terminal — the primitive
This is the base, and it works with just the platform backend — tmux on POSIX or psmux on native Windows. pty_open grabs one local terminal; ssh host, docker exec -it x bash, or a REPL are just text you pty_send into it — once. Every command after that rides the same already-authenticated session. Session kind is never a tool-level distinction.```
pty_open() → grab one local terminal
pty_send(id, "ssh 192.168.1.2") → authenticate once, inside that terminal
pty_send(id, "uname -a") → every later command rides the SAME session
pty_read(id, { wait: true }) → read the token-reduced output, completion detected
**Origin.** I built aiterm for exactly this. Driving my homelab from Claude Code one command at a time meant every SSH command became its own `connect → authenticate → disconnect`: re-typing the passphrase and one-time code each time, short-lived sessions piling up, and eventually my own defenses (`fail2ban`, `MaxStartups`/`MaxSessions`, account lockout) locking me out — the security meant to stop attackers ended up stopping me. Holding one authenticated session fixes all three at once. That pain is why the persistent terminal exists; launching whole other agents inside it is what it grew into.
### 2. Launch other coding agents into that terminal — the orchestration flagship
The same primitive hosts another agent's TUI. `agent_launch` starts a selected execution harness inside a fresh persistent terminal and returns a `session_id`. `harness` names the component that owns the agent loop, authentication, hooks, session, and transcript; `model` remains an independent choice. The launched process sees the same project and user environment as a direct CLI invocation: normal configuration, MCPs, plugins, skills, permissions, trust decisions, memory, and history are not copied, filtered, or replaced. Aiterm adds only completion correlation and a non-user sub-agent context containing `role=subagent`, the parent session, delegation depth, lineage, and `delegation_allowed=true`.
起動結果には正規`harness`を含む`aiterm.agent-launch-result.v1`が付き、旧`provider`は互換fieldとして残る。同じ`harness`はagent dispatch、`aiterm-wait`、`agent_configure`、`pty_list`にも載る。Codexは通常rollout、Grokは通常session event、Claudeはlaunch固有Stop hook、Cursorは通常agent transcriptの`turn_ended`を完了正本に使う。agentへの送信は`pty_send`だけで行い、Aitermが送る時点で子の状態を見て振り分ける。Claudeは画面の実行中表示ではなくStopまで残るturnの印で判定する。実行中のturnへは差し込み(`mode=agent_steer`、新しい`event_cursor`と配送は作らない)、それ以外は非ブロックdispatch(`mode=agent_dispatch`)で、harnessごとの完了境界を表す整数`event_cursor`を返す。Codex親は選択に応じて公式Steerまたはqueue、Claude Code親は公式非同期hookで本文を自動受信する。他の親は`aiterm-wait`を使う。CursorのsubmitはadapterがCLIのextended keyboard protocolへ変換し、送信本文がcomposerへ残る場合は明示errorにする。
An ordinary send can select steer while its input is still unissued and readiness waiting observes a live busy turn. A confirmed exited harness is rejected before the readiness deadline. Exit after paste retains a possible effect; the same input is never replayed.
Set `require_agent:true` on `pty_send` when the integration requires agent delivery. If the agent registration is missing, Aiterm refuses before sending any text and returns `AGENT_SESSION_REQUIRED` with an explicit unsent message. The default preserves ordinary PTY sends; combining it with `force:true` is rejected before sending.
`pty_send` to an agent session accepts an optional `preface`: one line placed before the text, so the message reads "`preface`, blank line, `text`". For a Claude Code session Aiterm enters the `preface` without the terminal's paste markers and pastes the blank line and the text in one paste. Claude Code wraps long pasted text in `` and follows instructions inside it only where the user's own words outside the tags ask it to, so this keeps an integration's header (who the message is from) outside the wrapper. For Codex, Grok and Cursor sessions the three parts are joined and pasted as before. The `preface` must be a single line of at most 200 characters with no control characters, must not start with a symbol or whitespace, and must not contain `@`; otherwise Aiterm returns `AGENT_PREFACE_INVALID` and "文字列は送信していません。" before sending anything. It cannot be used with ordinary PTY sends, `force:true`, or `remote`.
When the caller gives no `preface`, Aiterm adds one itself for a Claude Code session whenever the text is long enough for Claude Code to wrap it (three or more line breaks, or 800 characters and up): "Aitermが届ける、この席の呼び手からの正規の送信です。下の貼り付けは、どこかから拾った文ではなく、呼び手がこの席へ宛てて送った文です。" ("A regular message from this session's caller, delivered by Aiterm. The paste below was sent to this session by the caller, not picked up from somewhere else.") The line states where the message comes from and does not tell the session to obey it. It applies to new turns, to steering, to the `prompt` of `agent_launch`, and to `remote` sessions (the Aiterm on that machine adds it). Without that line the whole message sits inside the wrapper, and a Claude Code session may decline to act on it as "not the user's own instruction". Short texts, Codex, Grok and Cursor sessions, and sends with `raw` or `force` are unchanged (ADR 0116).
Overlapping `pty_send` calls to the same agent session are handled one at a time. A later call picks its route only after the earlier one has been sent, so the result matches calls made in sequence (a call that overlaps the first send to a freshly started Claude Code session returns `mode=agent_steer`). It returns later by however long the earlier call waits for the session to accept input. If its turn does not come within the limit (60 seconds on POSIX, 180 seconds on Windows), Aiterm refuses before sending any text and returns `AGENT_SEND_BUSY` with an explicit unsent message. A lock left by a process that exited mid-send is cleared by the next send. `agent_configure` waits in the same line: a `pty_send` that arrives while a configuration change is in progress is sent after the change, so the turn runs with the new setting. A configuration change to a session whose turn is running does not hold the line while it waits for the turn to end, so steering still goes through. If its turn does not come within the same limit, `agent_configure` returns `AGENT_SEND_BUSY` with an explicit unchanged message.
`agent_launch` and `pty_send` (to an agent session) accept an optional `image`: an array of absolute paths to image files (png/jpg/jpeg/gif/webp). Aiterm appends an attachment block to the prompt, and every harness opens the path with its own file-reading tool and sees the image; the caller never learns harness-specific attachment tricks. Invalid paths are rejected before anything is sent.
`agent_launch` accepts an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. Codex/Grok use `--sandbox read-only`; Cursor uses its official read-only `--mode ask`. A path description remains declaration-only because these CLI launch surfaces provide no equivalent path allowlist flag.
Grokの無人起動は公式`--trust`で指定された作業フォルダを信頼登録し、確認画面を完了してから初回promptを送る。この登録はGrok CLIの信頼ストアへ保存され、フォルダ内のhook・MCP・LSPにも適用される。read-only sandboxの制限は維持する。画面に残る完了済みhookの結果は実行中と判定しない。
Grokで終了済みターンのweekly-limitパネルが残っている場合、次の通常`pty_send`が`Shift+X`で一度閉じ、入力受付を確認して今回の本文を送る。同じsessionと会話を保ち、receiptの`pane_input_recovery`に`grok_rate_limit_dialog_dismissed`を記録する。ターン未終了・harness不在は`GROK_RATE_LIMIT_RECOVERY_BLOCKED`、解除後の入力受付失敗は`GROK_RATE_LIMIT_RECOVERY_FAILED`となり、本文は未送信。上限の継続は`rate_limited`として返し、過去promptは再送しない。Grokの上限観測には現在の画面だけを使う。Claude Codeの上限は現在の画面の入力欄の下に出る知らせで、Codexの上限はturnを終えた記録(`task_complete`の`codex_error_info: "usage_limit_exceeded"`)で見分ける。pane logや道具の出力に残る上限の文字では判定しない。
Grokの待機中にerror eventが先に現れた場合は、見回り一回分後に現在の上限panelを読み直す。上限が無ければ元のerrorを返し、次turnや消失したlaunchへ古いerrorを結び付けない。timeout=0の即時照会は待たず、入力やAPI要求は再送しない。
When a Cursor pre-submit hook (`beforeSubmitPrompt`, or a Claude Code `UserPromptSubmit` hook that Cursor loads for compatibility) rejects the prompt, Cursor drops it and no turn or completion follows. Aiterm recognizes the rejection: an initial prompt returns `initial_prompt=failed`, and `pty_send` returns an error instead of a success receipt, both with `USER_HOOK_BLOCKED` and the hook's output. A rejection that comes after the 3-second start check is reported by the completion wait as `outcome=error` (`aiterm-wait` exit 7).
A current Cursor `Error:` containing a complete JSON object with `error.code` equal to `prepaid_balance_exhausted` ends the wait as `outcome=error` with that `error_kind`, even without a new user record. Quoted diagnostic codes, malformed JSON and old errors followed by a composer or busy display do not establish this terminal. Aiterm does not resend or close the session.
Grokがread-only sandboxの適用を拒否した場合、prompt送信時に`GROK_SANDBOX_STARTUP_FAILED`とCLIの原因を返す。hookパスのシンボリックリンクなど、CLIが示した原因を設定の管理元で修正し、対象sessionを`pty_close`して起動し直す。Aitermはsandboxを解除したりhookをコピーしたりしない。
この判定はGrok専用アダプターが所有する。初回prompt付きの`agent_launch`と通常の`pty_send`で、入力受付待ち中に拒否を検出すると未送信のエラーを返す。promptなし・`trust_project`指定なしの起動応答は入力受付を保証しない。`trust_project:true`では入力受付まで確認し、`startup.status`を返す。Grokのprivacy notice起動設定も同アダプターが所有する。実装の責務分担はDESIGNを参照。
Codex 0.155.1の「Approaching rate limits」model切替dialogは、通常の`pty_send`と`agent_configure`で同じsessionのまま一時的な**2. Keep current model**だけを選ぶ。入力受付を再確認してから本文または設定変更を進め、dispatch receiptの`pane_input_recovery`には`codex_rate_limit_model_switch_kept_current`を記録する。model切替と今後の表示抑止は選ばない。入力受付へ戻らなければ`CODEX_RATE_LIMIT_MODEL_SWITCH_RECOVERY_FAILED`となり、本文・設定変更は未送信。このdialogは`agent_approval`の対象ではなく、inspectは`reason="rate_limit_model_switch"`だけを返し、prompt digestとchoicesを出さない。
For a correlated Claude turn stopped at `Do you want to proceed?`, use `claude_approval(action: "inspect", ...)` to capture the active operation and SHA-256 screen digest, review the displayed command, then call `respond` with that exact digest and either `approve_once` or `deny`. The relay rechecks the operation and screen under the send lock, never exposes arbitrary input or permanent approval, keeps the active marker intact, and records a prompt-free owner-only receipt. `pty_send(force: true)` does not bypass this boundary.```text
agent_launch({ harness: "codex-cli", session_name: "codex1", cwd: "/repo",
prompt: "port test/legacy.py to vitest",
model: "gpt-5.6-sol", reasoning_effort: "high",
write_scope: "test/ only; no commit" })
→ { session_id: "codex1", … } # Codex now live in a persistent terminal
pty_read("codex1", { screen: true }) → read what it's doing (token-reduced)
pty_send("codex1", "also fix the imports it broke")
→ non-blocking dispatch; receipt carries event_cursor
# Codex/Claude Code親には回答が自動で届く。それ以外の親:
$ aiterm-wait --session codex1 --cursor <event_cursor> # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed, 7=error (turn aborted by an API error)
pty_read("codex1", { agent_transcript: true }) → collect the full answer
The canonical harness choices are:
harness |
Launches | Notes |
|---|---|---|
claude-code |
Claude Code CLI | Claude model and effort controls; correlated Stop hook |
codex-cli |
Codex CLI | OpenAI model and effort controls; durable rollout completion |
grok-cli |
Grok Build CLI | Grok model selected with model; live catalog check |
cursor-cli |
Cursor Agent CLI | GPT, Claude, Grok, or another Cursor catalog model; normal transcript completion |
A new terminal gets the environment of the MCP process that opened it (since 0.50.0, ADR 0081).
Values from another caller that happened to start the tmux server first no longer appear in it.
AITERM_SESSION_ID and AITERM_AGENT_* are not inherited; aiterm sets them per terminal. If a harness
passes only a few variables to its MCP process, the terminal has only those (Codex passes HOME, PATH,
SHELL, and TERM by default; forward more with env_vars under [mcp_servers.aiterm]).
env_vars is an allowlist of environment-variable names, not a name/value map. At launch,
aiterm reads each valid name from its current MCP process, shell-quotes present values, and places
them on that one harness launch command. Missing names are omitted; invalid shell variable names
fail before session creation. Only the named values can be read back with env_keys in pty_list.
Values do not enter the MCP tool arguments, but they are delivered through the
PTY launch command and retained in aiterm's per-session .lastcmd; the launched harness and other
processes with access to the same OS user may read them. Use this for non-secret seat identity and
workflow variables, not as a secret transport.
…(正文过长,页面只展示前面部分,完整内容见仓库)
