pairmux

Agents drive.
Humans take over.

The same terminal, from either side.

pairmux is a small Agent-Computer Interface over tmux. Give an agent a real, persistent terminal. When a prompt needs credentials or a judgment call, a human can attach, take over, and hand it back.

Install pairmux Read the docs
  • Real PTYs for REPLs, TUIs, and interactive prompts.
  • Shell state that stays put between commands.
  • Shared observation and retained terminal history.

Not another exec API. Keep your built-in shell tool for quick, one-shot commands. Use pairmux when the terminal, its state, or a person is part of the work.

handoff Static CLI example

A program has reached an input prompt in a terminal named handoff.

Agent

Wait for a human, with a best-effort notification.

pairmux --json wait handoff --human --notify --timeout 5m

Human

From a second terminal, outside tmux, attach to the same live pane.

pairmux attach handoff

Answer the prompt, then detach with the configured tmux binding (default Ctrl-b d). Optionally, leave a note from your outer shell.

pairmux --json note handoff "demo input completed"

The agent’s wait can finish as soon as the prompt is answered. A note explains what you did; it is not required to resume.

One live terminal. The agent waits; the human steps in.
Try a safe, disposable-input demo

First, create a terminal and run this simulated password prompt. Use a new name if handoff is already active.

pairmux --json new --name handoff
pairmux --json run handoff "sh -c 'printf \"Password: \"; stty -echo; IFS= read -r secret; stty echo; printf \"\\ninput received\\n\"'"

Once run reports awaiting-input, follow the handoff commands above. Type demo-only, not a real secret. pairmux cannot guarantee how other programs echo, store, or log input.

When finished, stop the demo terminal. Its journal is retained.

pairmux --json kill handoff
Read the full handoff example

Install from PyPI.

The pairmux package comes from PyPI. The shell installer sets up uv if needed, then installs pairmux as an isolated tool.

macOS, Linux, or a WSL shell

curl -fsSL https://pairmux.treeleaves30760.com/install.sh | bash

Read install.sh before running itRead the Windows / WSL installer

The shell installer pins the pairmux package source to PyPI and ignores uv configuration and package-source overrides. uv bootstrap, and Python if needed, use official Astral sources, not PyPI.

Separate requirements: Python 3.9 or newer for the uv tool environment; tmux 3.2 or newer to run terminals. Install tmux with your OS package manager. On Windows, pairmux runs inside WSL, not natively.

Already have uv?

Quick run, without a persistent install

Run the latest pairmux once and print its version.

uvx --default-index https://pypi.org/simple pairmux@latest version

Install for everyday use

Install the pairmux command into uv’s tool-bin directory.

uv tool install --default-index https://pypi.org/simple pairmux

These manual commands set PyPI as the default index; they can still honor extra indexes and other source overrides in your environment or uv configuration. Use the shell installer for the pinned-source setup. If the persistent command is not found, add uv’s tool-bin directory to your PATH.

Setup, CLI reference, and agent integration