Guide · Agent skill

How to use the iTerm2 Control Harness agent skill (cli-anything-iterm2)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The cli-anything-iterm2 skill gives an AI agent a command-line tool that controls a running iTerm2 app on macOS. Once it is installed, the agent can see what is running in each pane, type commands into a chosen pane, read the output, and set up windows, tabs, split panes, layouts and tmux sessions. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what to watch for before letting an agent type into your terminal.

iTerm2 Control HarnessHKUDS/CLI-Anything · Apache-2.0 Download the skill

Quick start

1Check the requirements. Confirm you are on macOS with iTerm2 installed and that you can use iTerm2 on this machine.
2Enable the Python API. In iTerm2, open Preferences, go to General, then Magic, and turn on Enable Python API.
3Install the command-line tool. Run pip install cli-anything-iterm2 in a Python environment you use.
4Download and unzip the skill. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
5Or upload it in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
6Ask for an action. Describe what you want done in an iTerm2 pane in plain words, such as checking a server log.

What the skill lets the agent do in iTerm2

Without this skill, an agent answering an iTerm2 question works from general knowledge. With the skill loaded, it is instructed to read the skill first and then act on the live app through the cli-anything-iterm2 commands. The source describes the tool as the way to actually send text to iTerm2 sessions, read live terminal output and scrollback history, manage windows, tabs and split panes, run tmux -CC workflows, broadcast to multiple panes, show macOS dialogs, and read or write iTerm2 preferences.

Orient: take a snapshot of every session's name, current directory, foreground process, role label and last output line in one call.
Act: send a command to a specific session, or inject raw bytes.
Read: fetch the visible screen or scrollback history, with an option to strip formatting.
Arrange: create, resize and close windows and tabs, split panes, and save and restore arrangements.
Automate: run tmux -CC workflows, broadcast keystrokes to several panes, and invoke menu items.
Configure: list profiles, apply color presets, and read or change global preferences.

Requirements before you install

The tool depends on the iTerm2 Python API, so it only works on macOS with iTerm2 running. Check each item below before installing.

macOS with iTerm2 running. The source gives the install command brew install --cask iterm2.
Python API enabled: in iTerm2, open Preferences, go to General, then Magic, and turn on Enable Python API.
Python with the pip package cli-anything-iterm2 (or pip install -e . from source).

Install the skill: download the ZIP and unzip it

Download the skill ZIP from this page and unzip it into one of two locations. Use ~/.claude/skills/ to make the skill available to all your projects, or a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead of Claude Code, you can upload the skill under Settings, then Capabilities, then Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into the project's .claude/skills/ folder
Claude apps: upload under Settings → Capabilities → Skills

Install the command-line tool

The skill itself only gives the agent instructions. The commands it calls come from the Python package. Install it with pip, then confirm that the command runs.

pip install cli-anything-iterm2

Ask for iTerm2 actions in plain language

You do not need to name the skill or its commands. Describe the goal in ordinary words. The skill's description tells the agent to read it for requests such as orienting in an existing workspace, sending a command, checking what is running, reading output, setting up a layout, using tmux through iTerm2, automating panes, or configuring preferences. It also covers questions about shell integration and scrollback.

Good requests name the pane or purpose so the agent can find the right session.

Check on my dev server pane and tell me the last few lines of output.
What is running in each of my iTerm2 panes right now?
Split this window vertically and start a python3 http.server on port 8000 in the new pane.
Send git status to the editor pane and show me the result.
Set up a three-pane layout with an API server, a log tail and an editor.

Label panes so the agent can find them

Labels make later work much easier. Setting the user.role session variable gives a pane a name that app snapshot shows alongside its path and process, so the agent can identify it in one call.

Set a label on the current pane and check it appears in the snapshot.

cli-anything-iterm2 session set-var user.role "api-server"

Typical agent workflow

A typical session starts with orientation, then saves context so later commands know which session to use, then interacts with panes. The agent usually runs these steps itself, but reading them helps you judge what it is doing.

Orient with a JSON snapshot of all sessions.
Run app current to save window, tab and session IDs as context.
Send a command with session send, then read recent output with scrollback.

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

What people use it for

Check whether a dev server, test watcher or log tail in another pane is still running and report its last output line.
Send a command such as git status to a named pane and return the result.
Create a multi-pane workspace with a server, a log tail and an editor, labelled so they can be found later.
Run the same command across several panes at once using broadcast, then clear broadcasting.
Save a window layout with an arrangement and restore it later.

Frequently asked questions

How do I install the iTerm2 agent skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills. You also need the pip package cli-anything-iterm2 installed.

What do I need to run cli-anything-iterm2?

You need macOS, iTerm2 (the source gives brew install --cask iterm2), the iTerm2 Python API enabled under General, then Magic, and Python with the pip package cli-anything-iterm2. The tool will not work on machines without macOS or iTerm2.

Is the iTerm2 agent skill free?

The source lists the project's licence as Apache-2.0. It does not state pricing, so check the project's repository for licence terms before using it.

Does the skill use the internet?

The source says the skill does not use the network. It does run scripts, and it controls your local iTerm2 app through the iTerm2 Python API.

Why won't the agent control iTerm2?

Check that you are on macOS, that iTerm2 is running, and that Enable Python API is turned on under Preferences, General, Magic. The tool depends on the iTerm2 Python API and will not work elsewhere.

How is this different from just asking an AI about iTerm2?

Without the skill, an agent answers from general knowledge. With the skill, it is directed to read your live panes, send real keystrokes and read real output. The skill sends real keystrokes into live sessions, so review what it plans to run.

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 keep several iTerm2 panes running servers, logs or editors on a Mac and want an agent to check them, run commands in a specific pane, or automate repeatable layouts and tmux setups. Skip it if you are not on macOS, if you are uncomfortable enabling the iTerm2 Python API, or if you work in shared or production terminals where unreviewed commands could do damage.

Download the skill