Download
Shellbell + iTerm2

Your iTerm2 tabs.
On your phone.

Shellbell’s macOS service reads iTerm2 tabs and panes through iTerm2’s own Python API, so the tabs you already work in appear on your phone. iTerm2 ships with that API turned off.

Two switches, once.

Turn on iTerm2’s Python API, then connect Shellbell to iTerm2. After that, follow live output, scroll history, type into any tab and open new tabs from the phone. Nothing else changes about how you use iTerm2.

Set up iTerm2.

Keep iTerm2 and the Shellbell computer service running on an awake, online Mac.

  1. Turn on iTerm2’s Python API.

    In iTerm2, open Settings → General → Magic and select Enable Python API. iTerm2 leaves this off by default, and Shellbell cannot see any tab until it is on. No Python install is needed: Shellbell talks to the same local socket the setting opens.

  2. Connect Shellbell to iTerm2.

    Start the Shellbell computer service. In the Mac app, open Settings → Terminals and choose Connect iTerm2; on a headless Mac, run shellbell connect iterm2. macOS then asks whether Shellbell may control iTerm2, and iTerm2 may ask too; allow both. This is the only step that makes macOS ask. Shellbell uses that permission to ask iTerm2 for a private API key.

    If you declined, the Terminals settings and shellbell doctor show where to change it, in System Settings → Privacy & Security → Automation.

  3. Check Shellbell’s access.

    The Mac app’s Terminals section shows whether iTerm2 is ready and what to do if not. On a headless Mac, run the diagnostics; they report the same reasons and fixes.

    shellbell doctor

  4. Optional: install shell integration.

    For reliable “command finished” alerts, install iTerm2’s shell integration from iTerm2 → Install Shell Integration. It reports each prompt and exit code to iTerm2, which Shellbell uses for notifications. Screens, history and typing work without it.

  5. Pair your phone and choose a tab.

    Use the ordinary Shellbell pairing flow. Your iTerm2 tabs and split panes appear as sessions, and New iTerm2 tab opens a fresh tab on the Mac.

    Pairing walkthrough

This integration is supplied by the macOS computer service. On Linux, or with Ghostty, Warp, Terminal.app, Alacritty, Kitty or WezTerm, run your session inside tmux instead.

Integration references.

Read the backend contract or iTerm2’s own documentation for its API.

Shellbell’s iTerm2 adapter

API connection, authorization, tab discovery, and backend behavior.

Computer installation guide

Terminal access for iTerm2, tmux and Herdr.

iTerm2 Python API

How iTerm2 authorizes API clients.