iTerm2's Claude Code Integration: What It Does and How to Set It Up

People search for "iterm2 claude code" and land on our comparison of AgentsRoom and iTerm2. That page answers a different question. This one answers theirs: what the Claude Code integration in iTerm2 does, how you install it, what it changes on your Mac, and where it stops.

We build AgentsRoom, an app for running coding agents, so we are not neutral. We wrote this from iTerm2's own pages, read on October 19, 2026: the Claude Code integration page, the Session Status documentation, and the release notes of iTerm2 3.7.0 to 3.7.6. We did not install iTerm2 for this article. Every menu name below is quoted from those pages.

The short answer

• What it is: an optional setup that ships with iTerm2 3.7.0 (September 8, 2026). It hooks Claude Code into iTerm2's Session Status, so every Claude session shows whether it is working, waiting for you or done.
• How to install: iTerm2 > Install Claude Code Integration, then follow the setup window.
• What it needs: Claude Code installed as claude, iTerm2's Python API turned on, and macOS 13 or later for iTerm2 3.7.6.
• What you get: a status on each tab, a list of every session sorted by urgency, a Claude Code workgroup with Chat, Diff and Code Review side by side, and review comments you can send back to Claude.
• Codex: followed since 3.7.5 (October 14, 2026), set up by hand.
• Undo: iTerm2 > Uninstall Claude Code Integration.

What the setup changes on your Mac

The menu item opens a setup window with five steps. Each one is optional except the first.

1. Enable Python API. Required. The hook uses it to send each status to iTerm2, and Code Review uses it to add findings to the Clippings panel. macOS asks you to confirm.
2. Install Hook. Adds hooks to ~/.claude/settings.json. The hook points to a stable path inside iTerm2's configuration folder.
3. Show Toolbelt. The same as View > Toolbelt > Show Toolbelt, or Cmd+Shift+B.
4. Install Workgroup. Adds a Claude Code workgroup, editable later in Settings > Arrangements > Workgroups.
5. Auto-Enter Workgroup. You pick the profiles that get Enter and Exit triggers.

So two places change: your Claude Code settings file, and iTerm2's own settings (Python API, toolbelt, Session Status, the workgroup, triggers on the profiles you chose).

Two fixes from 3.7.5 matter if your setup is not the default one. The installer now honors $CLAUDE_CONFIG_DIR, so the status works when Claude Code keeps its settings outside ~/.claude. And it no longer overwrites a settings.json that contains a syntax error, or replaces a symlinked one with a plain file. Before 3.7.5, the first case wiped your other Claude Code settings. If you are on an older 3.7, update before you install.

If you have not installed it, iTerm2 offers it once: a banner asks "Want to try the Claude Code integration?" when Claude runs. Try It Now enters the workgroup until Claude stops. Installing from the menu makes it permanent.

What you see: Session Status

Each Claude session reports one state, shown on its tab as a subtitle, a colored dot and a subtitle color:

Done and error sort just below waiting, and pressing a key in the session marks them as seen. With a recent Claude Code, a session stays working while its background agents or tasks run, so a short pause does not flip it to idle. And since 3.7.5, pressing Esc to interrupt Claude sets the status back to idle. Before that, the tab stayed on working until your next request.

You read the states in three places:

• The tab of each session.
• The Session Status tool, in View > Toolbelt > Session Status. It lists every session with its dot and label, sorts the ones that need you first, and jumps to a session when you click its row. A row can carry a detail line, such as the tool waiting for permission or a snippet of Claude's last message. You can snooze a row, which moves it below a divider until its status changes.
• The Cockpit, in Window > Cockpit, a floating panel with the status of every window. Since 3.7.5 it can also send one command to many sessions at once.

For an alert, Window > Notify on Status Change warns you at the next status change of one session or of the whole window.

The Claude Code workgroup

A workgroup turns one session into a set of related sessions, called peers. The Claude Code workgroup adds three next to the main one:

• Chat: the main Claude conversation.
• Diff: a side-by-side view of the changes in your working tree.
• Code Review: a separate session that reviews those changes.

You switch peers from the workgroup's toolbar. The review comments are stored as clippings, so they can be handed back to Claude in the chat. Since 3.7.5, that toolbar can also show an AI Usage gauge with your Claude subscription's session and weekly usage.

With Auto-Enter, triggers watch the claude job: the workgroup opens when claude starts in one of your chosen profiles and closes when the main session's claude stops. Only the leader's exit counts, so ending claude in a peer leaves the workgroup running. You can also enter by hand with Shell > Workgroups > Claude Code, and leave with Shell > Workgroups > Exit Workgroup.

When the status stops updating

The most common breakage has nothing to do with iTerm2. Claude Code can rewrite ~/.claude/settings.json and drop the cc-status hook. The tab then stops changing state, silently.

iTerm2 checks on the next Claude run and offers to put the hook back: choose Reinstall, or Not Now. You can do it yourself with iTerm2 > Reinstall Claude Code Integration. Since 3.7.5, if you edited the hook commands to use $HOME, ~ or a wrapper script, reinstalling keeps your commands instead of adding duplicates.

Two other cases look like breakage and are not:

• A plain tmux session. Since 3.7.5, iTerm2 does not report Claude Code's status from a pane of a tmux session that does not use tmux Integration, because it cannot tell which tab shows that pane. Sessions inside tmux Integration panes are listed.
• An old 3.7. The Esc fix above, the CLAUDE_CONFIG_DIR fix and the symlink fix all arrived in 3.7.5. Check your version first.

To remove everything, iTerm2 > Uninstall Claude Code Integration takes out the hook, the workgroup and the triggers on every profile. It asks whether to keep the Python API, in case other scripts use it.

Codex and the other agent CLIs

The integration is built for Claude Code. Since 3.7.5, the Session Status tool can also follow Codex CLI, but there is no installer: the release notes tell you to edit ~/.codex/hooks.json and point each hook event at the cc-status tool from the utilities folder inside iTerm2.app's Resources, with --agent codex, and a timeout of 3 on the Interrupt and SessionEnd hooks. The notes do not list the events, so you read Codex's hook documentation for the full set.

For any other CLI there is no integration, but there is a way in. A program can set its own status with an escape sequence (OSC 21337, or the Program Status Protocol, OSC 7501, since 3.7.5), with the it2 session set-status command, or with a Set Tab Status trigger that matches its output against a regular expression (Settings > Profiles > Advanced > Triggers). If your CLI has hooks, a short script that calls it2 from them gets you most of the way. Our guide to Claude Code hook events shows which events fire when, which is what you need to pick the right ones.

On your phone: iTerm2 Buddy

iTerm2 3.7.0 also brought iTerm2 Buddy, an iOS app that pairs with your Mac by scanning a QR code. It shows a live view of a session, receives iTerm2's alerts as push notifications and lets you continue iTerm2's AI chat. Since 3.7.5, the session list updates live, the it2 tool can send a push notification to the paired phone, and when iTerm2 shows a warning while you are away, Buddy stays connected, displays it and lets you answer it. Other dialogs cannot be answered from the phone. There is no Android version. Our comparison page has the details we checked on Buddy in September.

Where it stops

• A Mac only. iTerm2 is a macOS app, and 3.7.6 needs macOS 13 or later.
• Claude Code first. Codex is supported by hand since 3.7.5, everything else is do-it-yourself.
• One terminal on one Mac. The status lives in that iTerm2. A session on another computer, or in another terminal, is not in the list.
• The Python API stays on. That is the price of the hook. Local scripts can then drive iTerm2, which is why macOS asks you to confirm.
• Claude Code updates can drop the hook. Reinstall fixes it, but nothing tells you before the tab goes quiet, until the next Claude run.

None of this is a flaw for someone who lives in iTerm2 and runs Claude Code in a few tabs. It is a terminal that learned to read one agent very well.

What AgentsRoom does next to it

AgentsRoom starts from the agent instead of the terminal tab. Every agent has a status in the agent list (working, done, needs input, idle), whichever of the 14 supported CLIs runs it. The same statuses follow you to the phone app on iOS and Android, and the app runs on macOS, Windows and Linux.

Many people keep both: iTerm2 for the shell, SSH and scripts, and an agent app for the agents. If you are still choosing a terminal for agent work, this comparison of terminals covers tmux, Ghostty, Warp and cmux.

FAQ

Does iTerm2 have a Claude Code integration?

Yes, since iTerm2 3.7.0 (September 8, 2026). It is optional and reversible. It adds hooks to Claude Code that report each session's state to iTerm2, which shows it on the tab and in the Session Status tool, and it adds a Claude Code workgroup with Chat, Diff and Code Review peers. Review comments are stored as clippings you can send back to Claude.

How do I install the Claude Code integration in iTerm2?

Choose iTerm2 > Install Claude Code Integration. A setup window walks you through five steps: Enable Python API (required), Install Hook, Show Toolbelt, Install Workgroup and Auto-Enter Workgroup. Claude Code must be installed and runnable as claude. iTerm2 3.7.6 requires macOS 13 or later.

Why did the Claude Code status stop updating in iTerm2?

Usually because Claude Code rewrote ~/.claude/settings.json and dropped the cc-status hook. iTerm2 notices on the next Claude run and offers Reinstall. You can also choose iTerm2 > Reinstall Claude Code Integration. If you keep Claude Code's settings outside ~/.claude with CLAUDE_CONFIG_DIR, update to iTerm2 3.7.5 or later, which honors that variable.

Does iTerm2 Session Status work with Codex?

Since iTerm2 3.7.5, the Session Status tool can follow Codex CLI too, but there is no installer for it. You edit ~/.codex/hooks.json yourself and point the hook events at the cc-status tool shipped inside iTerm2.app, with --agent codex. Other agent CLIs have no integration; they can report a status through iTerm2's escape sequences, the it2 command or a trigger.

Why does the iTerm2 Claude Code integration need the Python API?

The Python API is how the hook carries each status to iTerm2, and how Code Review findings reach the Clippings panel. Setup cannot continue until it is enabled, and macOS asks you to confirm. When you uninstall, iTerm2 asks whether to keep the Python API, since other scripts may use it.

Is there an iTerm2 Claude Code integration for Windows or Linux?

No. iTerm2 is a macOS app, so the integration, the Session Status tool and the workgroup exist only on a Mac. On Windows or Linux you need another terminal or an app that tracks agent sessions on its own.