pairmux

What it is and what it does

pairmux is a thin Agent-Computer Interface layer over tmux that gives AI agents a real pseudo-terminal with persistent shell state, allowing them to drive interactive programs like REPLs, psql, ssh, docker exec, git rebase, pagers, and TUIs. Unlike exec-style agent tools that run commands without a terminal, pairmux maintains a live tmux session where agents can run commands, wait for completion or recognized prompts, and inspect output — all while a human retains normal access to the same terminal and can take over at any time.

The package handles credential and confirmation prompts by recognizing patterns (passwords, passphrases, pager markers, Python prompts) and refusing to auto-answer; instead it can notify a human or wait for manual input via a live tmux pane. Agents interact through a CLI with JSON output, a blocking `run` command that waits for completion or timeout, and read-only `peek` and `log` commands that let multiple agents inspect the same terminal without lock contention. It ships as a prebuilt native Go binary in platform-specific wheels, requires no separate service, and integrates with MCP clients via a stdio server.

Use it for:

• Let an LLM agent run interactive Python REPLs, SQL shells, or other stateful interpreters while maintaining session context across multiple commands
• Enable agents to drive credential-protected workflows (ssh, database login, git operations) by pausing and notifying a human when a secret prompt appears
• Orchestrate multi-step terminal tasks (build, test, deploy) where agents can watch live output and humans can intervene without restarting the session
• Provide MCP clients with typed terminal operations (new, run, wait, send, log) as first-class tools for agentic terminal automation
• Debug agent-driven terminal interactions by capturing full output with exit codes and timestamps in a queryable journal

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

pairmux lets AI agents control interactive terminal programs through a real PTY while allowing humans to watch, take over, or hand back control when needed.

Yes, if you need agents to drive interactive terminal programs with real PTY semantics and human handoff. The active maintenance, zero security issues, and permissive license are favorable. Install friction is moderate (platform and tmux version constraints) and the alpha status suggests early-stage stability — suitable for projects that can tolerate rapid iteration but not for production systems requiring long-term stability guarantees.

Install

pairmux on PyPI

pip install pairmux

uv add pairmux

poetry add pairmux

Installing pairmux

Before you install

Medium friction: prebuilt native binaries in wheels eliminate build dependencies, but platform support is limited to macOS 12+ and manylinux_2_17 (glibc 2.17+) on x86-64 or ARM64. Requires tmux 3.2 or newer. Active maintenance with recent releases.

License in practice

MIT license is permissive and imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

# Install
pip install pairmux

# Create and run a command in a managed terminal
pairmux --json new --name demo
pairmux --json run demo "echo hello from pairmux"

# Wait for output to quiet, then inspect
pairmux --json wait demo --idle 800
pairmux --json peek demo

Requires tmux 3.2 or newer, macOS 12+ or manylinux_2_17 (glibc 2.17+), and x86-64 or ARM64 architecture. Python 3.9+ is required to install the wheel, though the pairmux executable itself is a native Go binary.

Verify before relying

• Whether the prebuilt Go binary in the wheel is reproducible or auditable
• Performance characteristics under high-frequency command execution or large output volumes
• Stability guarantees given the alpha development status (3 - Alpha classifier)

Package facts

Evidence: pairmux-0.4.0-py3-none-macosx_12_0_arm64.whl; pairmux-0.4.0-py3-none-macosx_12_0_x86_64.whl; pairmux-0.4.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pairmux-0.4.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Keywords: ai agents, tmux, terminal, cli, mcp, developer tools

Tags

More Software Development packages

Further reading