From iterm2-controller
This skill should be used when the user asks to "run something in iTerm", "open a terminal", "create a new tab", "split a pane", "run a background task", "monitor a process", "watch a running process", "check terminal output", "send a command to iTerm", "send ctrl+c", "set up a terminal layout", or when working with iTerm2 MCP tools (iterm_*). Also applies when orchestrating multi-terminal workflows or long-running processes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/iterm2-controller:using-iterm2The summary Claude sees in its skill listing — used to decide when to auto-load this skill
This plugin provides MCP tools to control iTerm2 terminals via AppleScript. Use these tools to create tabs, split panes, send commands, read output, and monitor sessions — all without leaving Claude Code.
This plugin provides MCP tools to control iTerm2 terminals via AppleScript. Use these tools to create tabs, split panes, send commands, read output, and monitor sessions — all without leaving Claude Code.
Before using any tools, register the current terminal session. The SessionStart hook displays the TTY path automatically:
iTerm2 session TTY: /dev/ttys004 — call iterm_register_session with this path to link this terminal.
Call iterm_register_session with that TTY path. This links the terminal to the session state so other tools can find it.
All tools that take an identifier parameter accept three formats:
w0t0p0:9B2F...)/dev/ttys004)"server" matches "dev-server")Prefer names for readability. Name sessions when creating them to make subsequent commands clearer.
| Tool | Purpose | Key Args |
|---|---|---|
iterm_new_tab | Create a new tab | command, name, window_identifier |
iterm_split_pane | Split current/specified pane | direction (vertical/horizontal), command, name, identifier |
New tabs get a purple tab color; split panes get blue. Both accept an optional command to run immediately and a name for identification.
| Tool | Purpose | Key Args |
|---|---|---|
iterm_send_command | Send a command + Enter | identifier, command |
iterm_send_keys | Send special keys/combos | identifier, keys |
iterm_send_keys supports: enter, tab, escape, ctrl+c, ctrl+d, ctrl+z, ctrl+l, ctrl+a, ctrl+e, ctrl+k, ctrl+u, ctrl+w, ctrl+r, up, down, left, right, backspace, space, and any ctrl+<letter>. Combine multiple keys with spaces: "up up enter".
| Tool | Purpose | Key Args |
|---|---|---|
iterm_read_output | Read last N lines of visible output | identifier, lines (default 50) |
iterm_watch_session | Get only new output since last call | identifier |
Use iterm_read_output for one-off checks. Use iterm_watch_session for polling long-running processes — it returns only lines added since the previous call.
| Tool | Purpose | Key Args |
|---|---|---|
iterm_register_session | Register a TTY to session state | tty_path |
iterm_list_sessions | List all sessions across all windows/tabs | — |
iterm_focus_session | Bring a session to the foreground | identifier |
iterm_get_session_by_name | Fuzzy-search sessions by name | name |
iterm_set_session_name | Rename a session | identifier, new_name |
Run a long-running process in a separate tab, then poll for output:
iterm_new_tab(command="npm run dev", name="dev-server")iterm_watch_session(identifier="dev-server")Set up a split layout for development:
iterm_split_pane(direction="vertical", command="npm run dev", name="server")iterm_split_pane(direction="horizontal", command="npm test -- --watch", name="tests")iterm_watch_session(identifier="server") and iterm_watch_session(identifier="tests")Send keystrokes to an interactive program:
iterm_send_command(identifier="server", command="node inspect app.js")iterm_send_keys(identifier="server", keys="ctrl+c") — to interruptiterm_send_keys(identifier="server", keys="up enter") — re-run last commandRead recent output without disrupting:
iterm_read_output(identifier="server", lines=20) — last 20 linesiterm_watch_session(identifier="server") — only what's newiterm_list_sessions to discover existing sessions if unsure what's runningiterm_watch_session resets its cursor on each unique session — first call returns the full bufferiterm_send_keys(keys="ctrl+c") over sending raw escape characterscommand parameter on iterm_new_tab and iterm_split_pane runs after tab creation — use it to immediately start processesFor the complete list of supported key names and detailed tool parameters:
references/tool-details.md — Full parameter documentation and return value schemasnpx claudepluginhub tinycamera/iterm2-controller --plugin iterm2-controllerManages tmux sessions, windows, and panes for persistent remote workflows and shell scripting automation. Useful for long-running processes, SSH disconnects, and multi-pane terminal layouts.
Automates interactive terminal programs (REPLs, debuggers, TUIs) via PTY. Start sessions, type text/keystrokes, wait for screen stability, snapshot output, and manage multiple sessions.