Skip to main content

pairmux

Let AI agents drive interactive terminal programs — and hand off to a human when they can't.

Homepage · Documentation · CLI reference · Changelog · Source

pairmux is a small Agent-Computer Interface layer over a terminal multiplexer, with no service for you to install or supervise. It runs natively on macOS, Linux and Windows: it uses tmux when tmux is installed on macOS or Linux, and otherwise its own built-in multiplexer (a PTY on Unix, ConPTY on Windows). Agents get a real terminal with persistent shell state and actionable command outcomes; humans keep normal access to the same live terminal — watch, take over, hand back.

Why pairmux

  • A real PTY. Exec-style agent shell tools run commands without a terminal, so REPLs, psql, ssh password prompts, docker exec -it, git rebase -i, pagers, and TUIs are impossible there. pairmux makes them drivable.
  • Human handoff on credentials and judgment calls. A recognized secret prompt never suggests an answer; wait --human --notify, attach, and note turn a blocked credential prompt into a resumable checkpoint — and the wait ends as soon as the human answers, note or no note.
  • Persistent shell state. source venv/bin/activate, export, and nvm use happen once in a live shell instead of being re-composed into every command.
  • Actionable waits and captured history. run blocks until completion, a recognized prompt, or timeout (never killing the command); journals retain full output with exit codes, and --json emits a versioned pairmux.v1 envelope with ordered next steps.

Install

With uv installed, add a persistent pairmux command to PATH:

uv tool install pairmux
pairmux version
pairmux doctor

This ordinary install retains your environment and uv configuration, including index overrides, and may reuse cache. Check command -v pairmux for an older installation shadowing the new one.

Update (v0.6.0+)

From v0.6.0 onward, update the currently running, verified persistent uv tool installation (including one created by the installer):

pairmux update

v0.5.3 and older have no update command. First use uv tool install --upgrade pairmux with your normal configuration to obtain v0.6.0+ when available, then use the new command.

The updater needs uv installed. It clears all inherited UV_* settings, ignores uv configuration, and reinstalls from https://pypi.org/simple with no persistent cache or source builds, replacing old exact pins, constraints, indexes, and extras. It selects the latest compatible stable wheel, never below the running version's numeric core; recognized alpha/beta/rc builds can advance to that core's final or a later stable release, but dev/snapshot builds are refused.

A version change returns updated; a same-version reinstall returns refreshed, not a no-op. Failures return E_UPDATE with a recovery hint, without a guaranteed rollback. Recover with the original manager, or uv tool install --upgrade pairmux for uv installs (normal configuration applies). It does not update Homebrew, RPM, pipx/pip, manual/development installs, or temporary uvx runs, and does not touch tmux. There are no command-specific options, automatic updates, sudo, or uv bootstrap/update; global --json is supported.

Optional temporary run with uvx

uvx pairmux version
uvx pairmux doctor

uvx remains supported. It uses a temporary tool environment, which uv may cache, or reuses an existing uv-managed installation; it does not promise the latest version or a fresh download every time. Temporary runs cannot use pairmux update.

Alternative installer

The inspectable installer persistently installs pairmux with uv from the public PyPI index:

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

To review it before execution, download successfully first, inspect the file, then run it:

installer_dir=$(mktemp -d) &&
curl -fsSL https://pairmux.treeleaves30760.com/install.sh -o "$installer_dir/install.sh" &&
less "$installer_dir/install.sh" &&
bash "$installer_dir/install.sh"

The one-line pipe executes downloaded code; it is not a substitute for that review. The installer clears all inherited UV_* settings, ignores uv configuration, and uses https://pypi.org/simple with no persistent cache and wheels only. Normal uv commands use your regular configuration. See installation guidance for PATH setup and other supported methods (pipx install pairmux or python -m pip install pairmux in a dedicated environment).

On Windows, the PowerShell installer applies the same PyPI-only uv policy natively, without administrator rights:

irm https://pairmux.treeleaves30760.com/install.ps1 | iex

Set $env:PAIRMUX_INSTALL_TARGET = 'wsl' first to install into a WSL distribution instead.

Requirements

The PyPI pairmux wheels contain a prebuilt native Go binary, so installation needs no Go toolchain or source build. Wheel installers require Python 3.9 or newer; the installed pairmux executable itself contains no Python code. If needed, the installer obtains uv from Astral's official installer, and uv may obtain managed Python from Astral's upstream Python distributions. Only the pairmux wheel comes from PyPI in that installer flow; uv/Python may come from Astral upstream.

PyPI package requirements and wheel targets:

  • macOS 12+, manylinux_2_17 (glibc 2.17+), or Windows 10 version 1809+ (ConPTY)
  • x86-64 or ARM64 (aarch64) on every operating system
  • tmux is optional. On macOS and Linux, pairmux uses tmux when it is installed (the tmux backend needs tmux 3.2 or newer, installed separately with your system package manager) and its built-in multiplexer otherwise. Windows always uses the built-in multiplexer. Set PAIRMUX_BACKEND=builtin or PAIRMUX_BACKEND=tmux to override the automatic choice. Neither the wheels nor the installers supply tmux or run sudo to install it.
  • WSL remains supported: inside WSL, pairmux installs and runs as on any other Linux system

From a source checkout, without PyPI

If you can clone the repository but cannot reach PyPI, install a development build from the clone with no build dependencies: python -m pip install . or uv tool install . builds the binary with a local Go 1.25+ toolchain, or packages a release binary you downloaded from GitHub Releases when you set PAIRMUX_PREBUILT_BINARY to its absolute path. Such builds get a development version and are not pairmux update targets. See the source install guide.

The quickstart below assumes the persistent pairmux command is on PATH. For temporary use, prefix each command with uvx.

60-second quickstart

Create one managed terminal, then run commands in it:

pairmux --json new --name demo
pairmux --json run demo "echo hello from pairmux"

# A timeout returns status=running; it does not kill the command.
pairmux --json run demo "sleep 2; echo finished" --timeout 1s

# When status is running, keep waiting without sleep-and-guess polling.
pairmux --json wait demo --idle 800
pairmux --json peek demo

wait --idle refreshes terminal state after output becomes quiet; silence alone is not treated as completion. peek and log are read-only, so other agents can inspect the same terminal without taking its writer lock.

Teach your agent

pairmux embeds its Agent Skill, including the new → run → wait/send/log loop and safe human handoff guidance:

pairmux skill install --target codex --dry-run
pairmux skill install --target codex
pairmux skill install -t all

-t is an alias for --target. Use -t all to update only the supported agent configuration directories that already exist, including Cline, Roo Code, Kilo Code, and Factory Droid. See the Agent Skills guide for all targets and install locations.

MCP clients can launch the built-in stdio server and use the core terminal operations as typed tools:

{
  "command": "pairmux",
  "args": ["mcp", "serve"]
}

Interactive work and human handoff

After 800 ms of output quiet, pairmux recognizes supported prompt patterns: confirmations, password/passphrase/passcode prompts, pager markers, press-key messages, and Python's >>>. It reports awaiting-input and never auto-answers. Replace the uppercase placeholders below before sending ordinary input:

pairmux send NAME --text VALUE --enter

For a secret-shaped prompt, the response recommends pairmux wait NAME --human --notify. A human can enter the same live pane with pairmux attach NAME, provide the input, and detach (on the tmux backend, with the configured tmux binding, default Ctrl-b d; see the CLI reference for the built-in backend). Running pairmux note NAME "ready" afterward records a message and releases an agent waiting with --human; it does not itself detach or enforce control ownership. This avoids routing the input through the agent-facing send command. Prompt recognition is heuristic, desktop notification is best-effort, and whether an application echoes or records input remains application-dependent.

How it works

A terminal multiplexer remains the terminal-state engine: tmux when it is installed on macOS or Linux, otherwise pairmux's own built-in server, which drives a PTY on Unix and ConPTY on native Windows. Short-lived pairmux commands add completion detection, captured output, model-friendly shaping, and coordination around the live pane. pairmux attach connects a human to the same managed terminal whenever a human needs to observe or take over.

pairmux is open source under the MIT License.

Metadata

Release files for pairmux 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for pairmux 1.5.0
File Actions
pairmux-1.5.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for pairmux-1.5.0-py3-none-win_arm64.whl
pairmux-1.5.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for pairmux-1.5.0-py3-none-win_amd64.whl
pairmux-1.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for pairmux-1.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
pairmux-1.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for pairmux-1.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pairmux-1.5.0-py3-none-macosx_12_0_x86_64.whl Python 3 none macOS 12.0+ x86-64 Details for pairmux-1.5.0-py3-none-macosx_12_0_x86_64.whl
pairmux-1.5.0-py3-none-macosx_12_0_arm64.whl Python 3 none macOS 12.0+ ARM64 Details for pairmux-1.5.0-py3-none-macosx_12_0_arm64.whl

Total release size: 11.4 MB

Release files / pairmux-1.5.0-py3-none-win_arm64.whl

Download URL pairmux-1.5.0-py3-none-win_arm64.whl
Size 1.8 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
d445f512a6ea38059c1c4ee3a9bebad325781e7b1fb57e454182c6e6ca147443
BLAKE2b-256 checksum
How to use checksums
f218f8d99c51437939cb75e22b6fbd2a43923838cdc2dd9d885c4374b590c3d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pairmux-1.5.0-py3-none-win_amd64.whl

Download URL pairmux-1.5.0-py3-none-win_amd64.whl
Size 2.0 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
291dd793cdfb3e2bc57734a7dfcfcdaa0973ea4a198e2194299c35204c3580a1
BLAKE2b-256 checksum
How to use checksums
9968afeb1af5d8228519e62a9b2118b1c7b723efa37ff40a460624f30a6add88
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pairmux-1.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL pairmux-1.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 2.0 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
13360899d66d69ff7af70ff2a1e3dfc94aa9bfcc5b83f8e7e5c3e830fbdb63df
BLAKE2b-256 checksum
How to use checksums
934389be19de34b8dd88f55d721e5911c41f3290e389497826edcedc950904de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pairmux-1.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL pairmux-1.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 1.8 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b5a597d549ba9c39acd9b4fa41d14f626e169092ff909cde925b0eb5414c2663
BLAKE2b-256 checksum
How to use checksums
c1525fd60790e1827aef3a2b88b1c867b209ac93892757a1325a9b803f34cd97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pairmux-1.5.0-py3-none-macosx_12_0_x86_64.whl

Download URL pairmux-1.5.0-py3-none-macosx_12_0_x86_64.whl
Size 2.0 MB
Tags Python 3 macOS 12.0+ x86-64
SHA-256 checksum
How to use checksums
0d6139ec7caa08cc21b287bf672c039769bd08ca2b16a6dea4693e2f8628029b
BLAKE2b-256 checksum
How to use checksums
7657041a49b31c21cf3ae758f911b587cf66738f39d39a23a9b62b0f5bfcfdb0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pairmux-1.5.0-py3-none-macosx_12_0_arm64.whl

Download URL pairmux-1.5.0-py3-none-macosx_12_0_arm64.whl
Size 1.8 MB
Tags Python 3 macOS 12.0+ ARM64
SHA-256 checksum
How to use checksums
5130fb6dadf99e4c36ae1dfbccb7f190d26320bfea5c1f643a92f6b3a68e99d3
BLAKE2b-256 checksum
How to use checksums
5cd7a589c539134512f8f526711c2b9b67f5006b6ac655e986bdce1f2b826fb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pairmux 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page