Guide · Agent skill
How to use the iTerm2 Terminal Control agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The cli-anything-iterm2-ctl skill gives an AI agent a command-line tool that talks to your running iTerm2 app, so it can see and act on your real terminal panes instead of guessing. This guide is for developers on macOS who use iTerm2 and want an agent to work inside their existing workspace. By the end you will know what the skill does, how to install it, how to ask for things in plain language, and what safety limits to keep in mind.
iTerm2 Terminal ControlHKUDS/CLI-Anything · Apache-2.0 Download the skill Quick start
- 1Check the prerequisites. Confirm you are on macOS with iTerm2 installed. The source suggests brew install --cask iterm2 if you need it.
- 2Enable the Python API. In iTerm2, open Preferences → General → Magic and turn on Enable Python API.
- 3Install the Python package. Run pip install cli-anything-iterm2, or pip install -e . from source.
- 4Install the skill folder. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 5Ask for an iTerm2 action. Describe the goal in plain language, for example checking what is running in your panes.
- 6Review the snapshot. The agent runs app snapshot with --json to see every session's name, directory, process, role and last output line.
What is an agent skill, and what does this one let the agent do?
An agent skill is a folder with a SKILL.md file that tells an AI agent when to read it and what commands it can use. This skill provides the cli-anything-iterm2 commands, which control a live iTerm2 process through the iTerm2 Python API over WebSocket.
With the skill, the agent can take a snapshot of every session, send text into a chosen pane, read screen or scrollback text, split panes, manage windows and tabs, drive tmux -CC workflows, broadcast keystrokes to multiple panes, show macOS dialogs, and read or write iTerm2 preferences.
- app snapshot returns each session's name, current directory, foreground process, user.role label and last output line in one call.
- session send types a command into a session; session scrollback reads history.
- Broadcast, tmux and preference commands cover multi-pane and configuration tasks.
Install the skill from the ZIP download
Download the ZIP for this skill from this page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
Set up macOS, iTerm2 and the Python package
The skill needs macOS and iTerm2. The source suggests installing iTerm2 with Homebrew, and you must enable the Python API before the tool can connect.
Install the command-line package with pip. The source also notes that you can use pip install -e . from source.
- Install iTerm2 (optional, via Homebrew): brew install --cask iterm2
- Enable the API in iTerm2: Preferences → General → Magic → Enable Python API
- Install the tool: pip install cli-anything-iterm2
brew install --cask iterm2
pip install cli-anything-iterm2Ask for iTerm2 actions in natural language
You do not need to name commands. The skill is meant to be read whenever you want the agent to do something in iTerm2, such as orienting in an existing workspace, sending a command, checking what is running, reading output, setting up a layout, using tmux, or changing preferences. The agent should read the skill first rather than answer from memory.
Good requests name the goal and, if you have one, the pane. For example: "Check what is running in my iTerm2 windows", "Run git status in the pane labelled editor", or "Set up a server, log tail and editor side by side."
Run the core commands yourself
Commands follow the pattern cli-anything-iterm2 [--json] <group> <command>. The source says to always use --json for machine-readable output when an agent is involved. Run app snapshot first to orient, then app current to set context so later commands need no session ID.
To label panes so the snapshot identifies them later, use session set-var user.role. A typical sequence is to snapshot, set context, send a command, read recent scrollback, and create a split pane.
- Orient: snapshot every session
- Set context: save window, tab and session IDs
- Interact: send a command, then read the last 200 lines of scrollback with --strip
cli-anything-iterm2 --json app snapshot
cli-anything-iterm2 app current
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip
cli-anything-iterm2 session split --vertical --use-as-context
cli-anything-iterm2 session set-var user.role "http-server"Build a labelled multi-pane workspace
Label each pane when you set up a workspace. The source gives the example roles api-server, log-tail and editor. Once labelled, app snapshot reports these roles with each pane's process and path, so the agent can find the right pane without reading every screen.
The skill also documents a reference set for narrower tasks, such as session I/O, layouts, tmux and preferences. The agent reads only the file it needs.
- Use one role label per pane, for example api-server, log-tail or editor.
- Re-run app snapshot after changes to confirm the layout.
What people use it for
- Orienting an agent in an existing iTerm2 workspace before it acts, using app snapshot.
- Running a command such as git status in a chosen pane and reading the output back.
- Setting up a server, log tail and editor side by side, each labelled with user.role.
- Using tmux -CC inside iTerm2 with agent help to manage its windows and commands.
- Reading or changing an iTerm2 preference, or showing a macOS dialog from a script.
Frequently asked questions
Is the iTerm2 Terminal Control skill free to use?
The source states the item is licensed under Apache-2.0, which is the licence of the HKUDS/CLI-Anything repository. The source does not list a price, so check the repository's licence terms for details.
What do I need to install before using this skill?
You need macOS, iTerm2 with the Python API enabled, and the cli-anything-iterm2 Python package installed with pip. Homebrew is optional and only needed if you want to install iTerm2 with brew install --cask iterm2.
Does this skill work on Windows or Linux?
No. The source says the tool depends on macOS and iTerm2, so users on other systems are not a good fit for this skill.
Does the skill use the internet?
The source says the skill does not use the network. It does run scripts, so review what the commands do before you rely on them.
Is it safe to let an agent type commands into my terminal?
Text sent through the skill runs with your user's permissions. The source advises against letting an agent type into a shared or production terminal without review, so keep a human in the loop for those sessions.
How is this different from just asking the agent about terminals?
The skill is for taking actions in iTerm2. The source says the agent should read it instead of answering iTerm2 action requests from general knowledge, and it is not meant for general terminal questions.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a developer on macOS with iTerm2 who wants an agent to work inside your existing panes, tmux sessions or multi-pane setups. Skip it if you are not on macOS or iTerm2, want only general terminal answers, or need to run commands in a shared or production terminal without reviewing them first.
Download the skill