pi-iterm2
Native iTerm2 integration for Pi

Your agent,
at a glance.

Stop checking every tab. Know when Pi is working, needs your input, or is ready for what’s next. Right where you already look.

Add to your terminal View source ↗
iTerm2 3.5+Pi extensionMIT licensed
π — a little more signal, a little less switchingiTerm2
π api-refactorworking
π review-testswaiting
π docs-updateidle
Pi Coding Agent
❯ Clean up the API and run the tests.
read  src/index.ts
edit  src/api.ts
bash  npm test
Running the test suite…
Try a state. See the signal change.
Interactive preview · real terminal, native indicatorsNo extra dashboard. No context switching.
01 / The signal

Three states. Zero guesswork.

One session or a whole row of tabs. The important part is always visible.

Working

An orange dot and a live tool detail tell you what’s happening, from reading a file to running a command.

bash: git status #ff9500

Waiting

A blue dot signals that it’s your turn. See when Pi needs an answer, an approval, or a little direction.

Your input needed #5f87ff

Idle

A green dot means ready. The label dims to gray and the tool detail clears, keeping finished sessions quiet.

idle · ready for you #00d75f
Not a custom UI.Actual iTerm2 tab status,
captured in the wild.
Actual iTerm2 window showing an orange working status badge beside a Pi session tab.
02 / Under the hood

Terminal-native.
Thoughtfully connected.

Small signals, built on iTerm2’s own capabilities. Not another window to keep open.

Two paths. One precise status.

Direct OSC 21337 sequences pair with asynchronous it2 session set-status updates to iTerm2’s session database. The native CLI targets the exact session ID.

Progress beyond the active tab.

Indeterminate tab and Dock progress via OSC 9;4 while Pi works. An attention state when input is needed. Automatically cleared when the turn completes.

Step away. Stay in the loop.

Native iTerm2 desktop notifications via OSC 9 when a task takes more than four seconds to finish, or when Pi needs your attention.

Fits the way you work.

Automatic tmux and screen passthrough for terminal control sequences. Inspect, preview, or clear the integration with simple slash commands, without leaving Pi.

Pi session
OSC 21337 · directit2 CLI · asynchronous
iTerm2
03 / Get started

One command.
A calmer tab bar.

Install as a Pi package, reload your session, and let your terminal do the talking.

Before you begin
iTerm2 3.5 or later with the Python API enabled.Settings → General → Magic
→ Enable Python API
Terminal
$ pi install git:github.com/mprokopov/pi-iterm2

Then run /reload in Pi, or restart your session.

/iterm2Inspect integration status
/iterm2 testPreview the status indicators
/iterm2 clearClear custom tab statuses

Less tab checking. More getting things done.

Explore on GitHub ↗