tmux-bridge

name: tmux-bridge description: Local terminal access via the tmux bridge. Use when the user asks about running shell commands, setting up the tmux bridge, or troubleshooting terminal connectivity. compatibility: Requires a local tmux bridge process running on the user's machine. metadata: tool-name: tmux docs: docs/tmux-bridge-contract.md

Tmux Bridge

The tmux bridge gives Pi access to a real local terminal on the user's machine. The tmux tool is always registered — it just needs the bridge process running locally to work.

What it does

When the bridge is running, the tmux tool can:

list_sessions — see active tmux sessions
create_session — start a new shell session (optionally in a specific directory)
send_keys — type commands into a session
capture_pane — read terminal output
send_and_capture — send a command and wait for output in one call
kill_session — close a session

Running `pi` (or other local CLIs) via tmux

The tmux pane is a normal local shell. If pi is installed, you can invoke it directly with send_keys/send_and_capture text like any other command.

Recommended flow:

list_sessions then create_session (or reuse an existing session)
Optional one-time check: command -v pi
Send the pi ... command
Monitor output with capture_pane

For long-running jobs, avoid rapid repeated captures. Prefer:

capture_pane with wait_ms (for example 15000-30000), or
send_and_capture with wait_for + timeout_ms when you know a completion pattern.

How to set it up

1. Start the bridge

The bridge is a local HTTPS server. Run it from a terminal:

npx pi-for-excel-tmux-bridge

This defaults to real tmux mode on https://localhost:3341.

Options:

--install-missing — auto-install tmux via Homebrew (macOS)
TMUX_BRIDGE_MODE=stub — safe simulated mode (no real shell execution)
TMUX_BRIDGE_TOKEN=your-secret — require auth token

2. Configure in Pi (usually not needed)

The default bridge URL (https://localhost:3341) works automatically — no configuration required. If you need a custom URL or auth token:

/experimental tmux-bridge-url <url>
/experimental tmux-bridge-token <token>
/experimental tmux-status

3. Accept the local HTTPS certificate

The bridge uses a self-signed cert. You may need to visit https://localhost:3341 in your browser once and accept it.

When the bridge is not running

The tmux tool stays registered but returns an error if the bridge is unreachable. Python tools (python_run, python_transform_range) still work via the in-browser Pyodide fallback — tmux is the only tool that strictly requires its bridge.

Security

Loopback-only (localhost)
Origin allowlist
Optional bearer token auth
Session names and key tokens are validated
No shell interpolation (argv-based tmux calls)

Troubleshooting

"bridge URL is unavailable" — the bridge process isn't running. Start it with npx pi-for-excel-tmux-bridge.
"timed out" — the bridge is running but the command took too long. Default timeout is 15s; use timeout_ms for longer operations.
CORS/cert errors — visit the bridge URL directly in your browser and accept the certificate.