aiterm-mcp

> **From any MCP client, launch Claude, Codex, Grok, or Composer — cross-vendor or same-vendor — inside a persistent interactive TUI, with native features such as Codex slash commands and [`$imagegen`](https://learn.chatgpt.com/docs/image-generation#generate-or-edit-an-image) available.**

<p align="center">
  <img src=".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.** From any MCP client, one call spawns a coding agent (Claude, Codex, Grok, or Composer) inside a persistent terminal and hands you a session to drive: read what it's doing token-reduced, send it the next instruction. The caller and launched vendor are independent: Claude can launch Claude or Codex, and Codex can launch Claude or Codex.
>
> **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 vendor memory/configuration that a direct CLI launch would use.
>
> **No human at a tmux 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](https://x.com/QLyun35332) at [kitepon.dev](https://kitepon.dev/en).

## Install in your MCP client

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

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

Requires **Node.js ≥ 18** and **tmux**. 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 the persistent PTY and external-agent
execution lane. Cross-product installation and host integration are handled by
[dotagents](https://github.com/kitepon/dotagents), the internal development
toolchain behind kitepon.dev's products.

**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)

Fourteen tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, four **agent launchers** — `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, `agent_configure` to change a running Claude/Codex/Grok/Composer session's model and effort without restarting it, `claude_turn` for durable structured issue/recovery, `claude_approval` for correlated Claude approval prompts, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.

**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 vendor CLI fall back to another model.

**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 tmux server predates the MCP
process, so a stale tmux-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 vendor's
native controls to change the model and/or reasoning effort of a running Codex or Claude
session while preserving its PTY, vendor session, and conversation context.

**v0.23.0 adds a local, cross-vendor 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, vendor 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
vendor-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:
every send to an agent session is a non-blocking dispatch, completion is one
universal `aiterm-wait` waiter whose exit codes mirror the receipt outcome
(`0`=done / `3`=timeout, not finished / `4`=closed / `5`=running for a
zero-time observation), and a launch with an
initial prompt returns a ready-made `wait_command` in its structured receipt.
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 · the newcomer