iTerm2 Terminal Control

Control iTerm2 sessions via the iterm2-agent MCP server. All tool names are prefixed with mcp__iterm2-agent__.

Prerequisites

Before using any tool, verify both conditions are met:

1. iTerm2 must be running

• iTerm2 app must be open with at least one terminal window.
• The Python API must be enabled. Check: iTerm2 → Settings → General → Magic → Enable Python API (checkbox must be on).
• How to verify: if mcp__iterm2-agent__read_screen returns a connection error, iTerm2 is either not running or the Python API is disabled. Ask the user to:
  1. Open iTerm2
  2. Go to iTerm2 → Settings → General → Magic
  3. Check Enable Python API
  4. Restart Claude Code (the MCP server connects on startup)

2. The iterm2-agent MCP server must be installed and registered

The MCP server must be cloned, installed, and registered in ~/.claude.json. How to check:

1. Is the repo cloned and dependencies installed? Look for the virtualenv at the clone path:

   ls /path/to/iterm2-agent/.venv/bin/python
   

   If missing, install:

   git clone git@github.com:xjthy001/iterm2-agent.git
   cd iterm2-agent
   uv venv && uv pip install -e .
   

2. Is it registered in ~/.claude.json? The file must contain an iterm2-agent entry under mcpServers:

   {
     "mcpServers": {
       "iterm2-agent": {
         "type": "stdio",
         "command": "/path/to/iterm2-agent/.venv/bin/python",
         "args": ["-m", "iterm2_agent"]
       }
     }
   }
   

   Replace /path/to/iterm2-agent with the actual clone path. If mcpServers already has other entries, add iterm2-agent alongside them.

3. Restart Claude Code after editing ~/.claude.json — the MCP server connects at session startup.

If a tool call fails with a connection error after both checks pass, ask the user to restart Claude Code.

Core Principle: Read Before You Act

ALWAYS call read_screen() before taking action. This tells you:

• What program is running (shell prompt? TUI? server logs?)
• The session ID to target
• Whether the session is idle or busy

Tool Reference

Tool Selection Guide

Workflow Recipes

1. Run a command and get output

1. read_screen()                           → get session state
2. run_command(command="git status")       → execute and capture output

2. Start a dev server and verify it’s running

1. read_screen()                                           → confirm shell is idle
2. send_text(text="npm run dev", press_enter=true)         → start server (don't wait)
3. watch_output(pattern="ready|listening|started", timeout=30)  → wait for ready signal

3. Split terminal and run tests in new pane

1. manage_session(action="split", direction="vertical")    → creates new pane, returns session_id
2. run_command(command="npm test", session_id="<new_id>")  → run tests in new pane

4. Stop a running process

1. read_screen()                        → see what's running
2. send_control(character="C")          → Ctrl+C to interrupt
3. read_screen()                        → verify process stopped

5. Interact with a REPL

1. run_command(command="python3")                          → launch REPL
2. send_text(text="import json", press_enter=true)         → send code
3. send_text(text="json.dumps({'a': 1})", press_enter=true)
4. read_screen()                                           → read output
5. send_control(character="D")                             → exit REPL (Ctrl+D)

Session ID Guidance

• Omit session_id (or pass "") to target the currently active session. This is the default and works for single-pane workflows.
• Use explicit session_id when working with multiple panes. Get IDs from manage_session(action="list") or from the return value of split/create.
• Session IDs look like: w0t0p0:A1B2C3D4-E5F6-...

Safety Rules

1. Respect security warnings. run_command classifies commands as SAFE, CAUTION, or DANGEROUS. If a DANGEROUS warning appears, confirm with the user before proceeding.
2. Confirm destructive commands. Before running rm, sudo, kill, git push --force, or similar — ask the user first.
3. Verify after control characters. After sending Ctrl+C/Z/D, always read_screen() to confirm the expected effect.
4. Don’t blindly retry. If a command fails or times out, read_screen() to understand the current state before retrying.

Troubleshooting