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

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

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:

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

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

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

Claude Desktop

Add this server to claude_desktop_config.json:

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

Cursor

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

{
  "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

Sixteen tools: six PTY tools — pty_open / pty_send / pty_read / pty_key / pty_close / pty_list — to open, drive, and read one persistent terminal; one canonical agent launcher, agent_launch, which selects claude-code, codex-cli, grok-cli, or cursor-cli as the execution harness; agent_steer for an active Codex or Grok turn; four deprecated launcher aliases kept for migration; agent_configure; 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. Grok Composer is a Grok CLI model preset, not another harness: use harness: "grok-cli", model: "grok-composer-2.5-fast". The old four 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.

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.