pairmux
Blocking tmux terminal control for AI agents, with captured logs and live human handoff
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- 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.
- 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.
License · maintenance · safety
MIT (permissive) — MIT license is permissive and imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.
last release 2026-08-10 (4 days) · last repo commit 2026-08-10 · 7 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 654,478 downloads/mo, #5,524 on PyPI
Alternatives
Verify before relying
# 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- 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)
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 on it.
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
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.
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.
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 demoVerify 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
| License | MIT permissive |
| Python support | Supports the current Python release >=3.9 |
| Install friction | Medium. Platform-specific wheel |
| Runtime dependencies | None |
| Maintenance | Actively maintained 4 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 654,478 / month, #5,524 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 3 - AlphaEnvironment :: ConsoleIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseOperating System :: MacOSOperating System :: POSIX :: LinuxProgramming Language :: GoTopic :: Software DevelopmentTopic :: TerminalsTopic :: Utilities |
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
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “ai agent terminal control”
- pairmuxpairmux lets AI agents control interactive terminal programs through…
- openhandsOpenHands is a CLI tool that runs an AI agent in your terminal, IDE,…
- terminal-benchTerminal-Bench provides a benchmark suite and execution harness for…
Give your agent the search over MCP, or paste the wish link into any chat.
More Software Development packages
Provides backported and experimental type hints for Python 3.9+, allowing use of newer typing features on older Python versions and enabling early experimentation with type system PEPs before they enter the standard library.
NumPy provides an N-dimensional array object and a comprehensive suite of mathematical, linear algebra, Fourier transform, and random number functions for scientific computing in Python.
FastAPI is a Python web framework for building REST APIs using type hints, with automatic request validation, serialization, and interactive API documentation.
Provides a way to document function parameters, class attributes, return types, and variables inline using Python's `Annotated` type hint syntax instead of traditional docstrings.
Typer builds command-line applications from Python functions using type hints, automatically generating help text, argument parsing, and shell completion.
Install it if you are building CLIs in Python.
Distlib provides low-level packaging utilities for building, distributing, and managing Python software—including metadata handling, version specifiers, wheel support, script installation, and dependency resolution.
See also libtmux · tmuxp · echo-agent · iterm2 · langgraph-supervisor · ptyprocess · dockerpty · deepagents-code · omnigent · kimi-cli