iterm-dash

Never leave a Claude waiting.

A live, keyboard-driven grid of every Claude Code session you already have open in iTerm2.
Press n to land in the next one that needs you.

Install · How it works · FAQ · Architecture

_{Recorded in a real iTerm2 window. The six sessions are scripted stand-ins, so no private work is on screen; the dashboard, their status and the tab switches are real.}

Why

I run eight or nine Claude Code sessions at once, each in its own iTerm2 tab, and two things kept going wrong.

A session would finish, or stop to ask me something, and then sit there until I happened to click past its tab. That's Claude Code time I wasn't using. And every so often I'd cycle through every tab just to glance at each one and check it was still on track, which is tedious with nine of them.

iterm-dash is one more iTerm2 tab that shows all the others live. The sessions that need you light up, and a single key takes you to them.

What you get

See who needs you

A session waiting on a question turns blue with Needs your input and shows the question under its title. A finished one turns green with Done · your turn. Every cell shows how long ago its status changed, so a session that has been waiting a while stands out. The header counts them, and the page title does too, for example (2) iterm-dash.

The real screen, not a summary

Each cell is the session's actual terminal screen at full width, colours and all, scaled to fit and updated as it changes. You can tell a session that's making progress from one that's going in circles without opening it.

Keyboard first

The mouse works too: click a cell to peek, double-click to jump.

Peek before you jump

Space opens the focused session full size, so you can read the question or the diff and decide whether it needs you now.

Works with the tabs you already have

There's no tmux, no wrapper command and nothing to relaunch. Start Claude Code however you like, in any window or tab. iterm-dash finds sessions as they open and close and keeps them in the order it first saw them.

Read-only by design

iterm-dash never types into, resizes or rearranges your sessions. Apart from managing its own dashboard tab, the only thing it does in iTerm2 is bring a session's tab to the front when you ask.

Install

You need macOS, iTerm2 3.7 or later, and uv. uv installs Python 3.12+ for you if you don't have it.

1. Turn on iTerm2's Claude Code integration: choose iTerm2 › Install Claude Code Integration and complete at least Enable Python API and Install Hook. The hook is how each session reports whether it's working, waiting or done.

2. Install iTerm2's browser plugin, which lets iTerm2 open a web page as a tab: download iTermBrowserPlugin-1.0.zip, unzip it and move iTermBrowserPlugin.app to /Applications. If it's missing, iterm-dash tells you so and prints these steps.

3. Install and run iterm-dash from any iTerm2 tab:

   uv tool install iterm-dash
   iterm-dash
   

The dashboard opens as a new iTerm2 tab. Run iterm-dash again at any time to bring it back to the front. The first run takes a few seconds longer while Python compiles, and iTerm2 may ask you to allow the API connection.

pipx install iterm-dash

uv tool install git+https://github.com/ritikrishu/iterm-dash

git clone https://github.com/ritikrishu/iterm-dash && cd iterm-dash
uv tool install --editable .

iterm-dash stop
uv tool upgrade iterm-dash

iterm-dash stop
uv tool uninstall iterm-dash

Usage

The server keeps running until iTerm2 quits or you run iterm-dash stop.

How it works

1. One background Python process holds a single connection to iTerm2's Python API.
2. Screens: it treats each session's screen stream only as a "something changed" signal, then fetches the raw screen buffer at a throttled rate. Lines are cached by their content, so a changed or scrolled frame only re-renders the lines that are new. Fetching a 214×57 screen takes about 1 ms, and re-rendering a changed frame about 0.5 ms (measured on iTerm2 3.7.6 with Claude Code 2.1.310).
3. Status comes from iTerm2's Claude Code integration (iterm2.get_session_status), the same source as iTerm2's Session Status tool.
4. The page is served on 127.0.0.1 with a per-run token and opened as an iTerm2 browser tab. A WebSocket sends it only the rows that changed, and it renders each screen at full width and scales it to fit the cell. Claude Code ends every row with a hard line break, so text can't be re-flowed into a narrower cell without breaking it.

In the same setup, with several sessions working, the server used about 1% CPU. The full design, including the edge cases that shaped it, is in docs/architecture.md.

Privacy and safety

Your terminals hold private work, so iterm-dash is built to keep it on your machine:

• The server only listens on 127.0.0.1. The page, its WebSocket and its control API all require a random token that changes on every start. Only the page's own JavaScript and CSS are served without it, and they contain no terminal data.
• The dashboard opens as an iTerm2 browser tab, never in your default browser, so that browser's extensions and sync never see your terminal contents or the token URL.
• It makes no outbound network requests and has no telemetry.
• Logs and iterm-dash smoke record metadata only (ids, titles, sizes, timings), never screen text.
• It never sends keystrokes to, resizes or closes your sessions.

See SECURITY.md to report a vulnerability.

How it compares

• iTerm2's Session Status tool (View › Toolbelt › Session Status) lists the same statuses and jumps to a session when you click it. If a status list is enough for you, you don't need iterm-dash. What iterm-dash adds is the live screen, so you can see whether a busy session is on track.
• Claude Code's agent view (claude agents) manages background sessions and shows a summary per session. Sessions open in other terminals only appear once you background them. iterm-dash shows the sessions you already have, as they are, without changing how you run them.
• Session managers such as claude-squad, agent-deck and ccmanager start and manage agent sessions for you and let you drive them from one place. Choose one of those if you want orchestration. iterm-dash doesn't start, stop or type into anything.

FAQ

Development

git clone https://github.com/ritikrishu/iterm-dash && cd iterm-dash
uv sync
uv run pytest        # Python tests (no iTerm2 needed)
npm test             # page module tests
uv run iterm-dash demo

iterm-dash demo serves the real UI fed by scripted sessions, which is how the still screenshots above were made. It's the quickest way to work on the page. The tests run against fake sessions, so neither needs iTerm2.

How the code fits together:

Read CONTRIBUTING.md before opening a pull request, and docs/architecture.md for the design and the iTerm2 behaviour it depends on. There's one hard rule: anything that changes a session gets tested only on a throwaway session, and debug output never prints screen text.

License

MIT. iterm-dash is an independent project, not affiliated with Anthropic or iTerm2. Claude and Claude Code are trademarks of Anthropic.