Iterm2 Agent

🚀 iterm2-agent

An MCP server for controlling iTerm2 terminal sessions via the iTerm2 Python API. It enables reading the screen, running commands, sending keystrokes, monitoring output, and managing panes through the Model Context Protocol.

🚀 Quick Start

To utilize iterm2-agent, you need to meet specific prerequisites and follow the installation steps. Here is a step-by-step guide to get you started.

✨ Features

• Comprehensive Control: Read the visible terminal content, execute shell commands, send text and control characters, monitor output, and manage iTerm2 sessions.
• Security Classification: Classify commands into SAFE, CAUTION, and DANGEROUS levels to ensure safe operation.
• Skill Integration: Integrate with AI agents through skills to provide reference guides for using tools effectively.

📦 Installation

Prerequisites

• macOS with iTerm2 installed.
• iTerm2 Python API enabled: Preferences → General → Magic → Enable Python API.
• Python 3.11+.
• uv (brew install uv).

MCP Server

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

Then register it in ~/.claude.json (see Usage with Claude Code below).

Skill (optional)

Install the agent skill via skills.sh:

npx skills add xjthy001/iterm2-agent

Or manually:

mkdir -p ~/.claude/skills/iterm2-agent
cp skills/iterm2-agent/SKILL.md ~/.claude/skills/iterm2-agent/SKILL.md

The skill gives your AI agent a reference guide for using the 6 tools effectively. It auto-activates when you mention iTerm2 or terminal control.

💻 Usage Examples

Tools

read_screen

Read the visible screen content of a session.

lines: int = -1          # Number of lines to read (-1 = all visible)
session_id: str = ""     # Target session (empty = active session)

run_command

Execute a command and capture output. Waits for output to stabilize (2s idle) before returning.

command: str             # Shell command to execute
timeout: int = 30        # Max seconds to wait
session_id: str = ""

Commands are classified by a security guard:

• SAFE — read-only commands (ls, pwd, git status, ...)
• CAUTION — modifying commands (mkdir, npm install, git push, ...)
• DANGEROUS — destructive commands (rm, sudo, kill, ...) — produces a warning

send_text

Send text to a session without automatically pressing Enter. Set press_enter=true to submit.

text: str                # Text to send
press_enter: bool = false
session_id: str = ""

send_control

Send a control character.

character: str           # One of: C, Z, D, L, ESCAPE, A, E, U, K, W, R
session_id: str = ""

watch_output

Block until a regex pattern appears on screen, or timeout.

pattern: str             # Regex pattern to match
timeout: int = 60        # Max seconds to wait
session_id: str = ""

manage_session

Manage iTerm2 sessions.

action: str              # list | create | split | close | focus
session_id: str = ""     # Required for close/focus, optional for split
direction: str = "horizontal"  # horizontal | vertical (split only)

📚 Documentation

Usage with Claude Code

1. Register the MCP server

Add the iterm2-agent entry to the mcpServers object in ~/.claude.json:

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

Replace /path/to/iterm2-agent with your actual clone path. The command must point to the Python binary inside the project's virtualenv so that dependencies are available.

⚠️ Important Note

If ~/.claude.json already has a mcpServers object, just add the "iterm2-agent": { ... } entry alongside existing servers. Don't overwrite the whole file.

Restart Claude Code after editing. The server connects to iTerm2 on startup — make sure iTerm2 is running and the Python API is enabled.

2. Install the skill (optional)

npx skills add xjthy001/iterm2-agent

Or manually copy from the repo:

mkdir -p ~/.claude/skills/iterm2-agent
cp skills/iterm2-agent/SKILL.md ~/.claude/skills/iterm2-agent/SKILL.md

After installing, invoke it with /iterm2-agent or it auto-activates when you mention terminal/iTerm2.

3. Verify

Start a new Claude Code session and try:

• "What's on my terminal right now?"
• "Run git status in iTerm2"
• "Split the terminal and run tests in the new pane"
• "Start the dev server and tell me when it's ready"
• "Send Ctrl+C to stop the running process"

🔧 Technical Details

Architecture

┌─────────────────────────────────────┐
│         MCP Client                  │
│   (Claude Code / Claude Desktop)    │
└──────────────┬──────────────────────┘
               │ stdio (JSON-RPC)
┌──────────────▼──────────────────────┐
│       iterm2-agent (MCP Server)     │
│                                     │
│  server.py        FastMCP + lifespan│
│  connection.py    Session resolver  │
│  security.py      Command classifier│
│  tools/                             │
│    read_screen.py                   │
│    run_command.py                   │
│    send_text.py                     │
│    send_control.py                  │
│    watch_output.py                  │
│    manage_session.py                │
└──────────────┬──────────────────────┘
               │ WebSocket
┌──────────────▼──────────────────────┐
│         iTerm2 Python API           │
│     (iterm2.Connection)             │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│           iTerm2.app                │
└─────────────────────────────────────┘

Project Structure

iterm2-agent/
├── pyproject.toml
├── config/
│   └── default.toml
├── src/iterm2_agent/
│   ├── __init__.py
│   ├── __main__.py           # Entry point: python -m iterm2_agent
│   ├── server.py             # FastMCP server with iTerm2 lifespan
│   ├── connection.py         # iTerm2Context, session resolution, screen reading
│   ├── security.py           # Command classification (SAFE/CAUTION/DANGEROUS)
│   └── tools/
│       ├── __init__.py       # Tool registration
│       ├── read_screen.py
│       ├── run_command.py
│       ├── send_text.py
│       ├── send_control.py
│       ├── watch_output.py
│       └── manage_session.py
├── tests/
│   ├── test_security.py      # Security guard unit tests
│   ├── test_read_screen.py   # Session resolution unit tests
│   ├── test_run_command.py   # Security integration tests
│   └── test_send_control.py  # Control character mapping tests
├── test_integration.py       # Live integration tests (requires iTerm2)
└── skills/iterm2-agent/
    └── SKILL.md              # Agent skill definition (skills.sh compatible)

📄 License

This project is licensed under the MIT license.