pairmux

An Agent-Computer Interface for terminals

Your agent drives the terminal. You take over when it matters.

pairmux gives AI coding agents a real, persistent terminal — REPLs, TUIs, ssh, [y/N] prompts — and hands the same live terminal to a human the moment a prompt needs a password or a judgment call.

Install pairmuxRead the docs
Coding agent

Deploy the build to staging.

I'll open a persistent terminal and ssh in.

pairmux --json new --name deploy

  • status: created

pairmux --json run deploy "ssh deploy@staging.internal"

  • status: awaiting-input
  • next: do NOT guess or type secrets
  • next: pairmux wait deploy --human --notify

The server wants a password. I won't guess it — handing off to you.

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

Waiting for a human…

awaiting-input · secret

a human can take over: pairmux attach deploy

$ ssh deploy@staging.internal
deploy@staging.internal's password:
A scripted illustration built from real pairmux output.

01 — The problem

Three things an exec tool cannot do.

Most agent shell tools run a command without a terminal. That is fine for ls. It is not fine for the rest.

  • No terminal.

    python, psql, ssh, git rebase -i, pagers and TUIs need a PTY. Without one they are not awkward — they are impossible.

    $ python
>>>

  • No one to ask.

    A password prompt leaves an agent with two bad options: guess, or give up. pairmux adds a third: hand the live terminal to a person.

    Password:

  • No memory between commands.

    source venv/bin/activate, export, nvm use evaporate after every call, so they get re-composed into every command. A real shell keeps them.

    $ source .venv/bin/activate
(.venv) $

02 — How it works

The handoff loop.

  1. pairmux --json new --name deploycreated

    One persistent shell. Its state survives between commands.

  2. pairmux --json run deploy "ssh deploy@staging.internal"awaiting-input

    run blocks until the command finishes, a recognized prompt appears, or the timeout expires. A secret-shaped prompt comes back with do NOT guess or type secrets.

  3. pairmux --json wait deploy --human --notify --timeout 5mwaiting

    The agent parks on a resumable checkpoint and the human gets a best-effort desktop notification.

  4. pairmux attach deployattached

    The human steps into the same live terminal, answers the prompt, and detaches. Optionally: pairmux --json note deploy "entered the staging password".

  5. wait returnshuman-done

    The wait ends the moment the prompt is answered. A note explains what the human did; it is never required to resume.

Only one writer per terminal. Reads are lock-free. Every byte is journaled and retrievable with log.

03 — Fit

When to use it — and when not to.

Reach for your shell tool

  • Short one-shot commands: ls, git status, a quick grep.
  • A long non-interactive job in a fresh environment, with no human needed — your harness's background execution already does this well.

Reach for pairmux

  • Interactive programs: a REPL, a TUI, a pager, [y/N], ssh, sudo.
  • Shell state that must persist: a venv, exports, nvm use.
  • Credential prompts, judgment calls, live human takeover.
  • A dev server or tail -f that a person may also watch.

pairmux earns its place where a terminal, its state, or a human is part of the work.

04 — Works with

Works with the agent you already use.

  • Claude Code

    Install the embedded Agent Skill once; the agent learns the new → run → wait loop and the safety rules.

    pairmux skill install --target all
    Agent Skills guide

  • MCP clients

    A stdio MCP server exposes new, run, peek, wait, send, log, ls, kill, note and doctor as typed tools.

    pairmux mcp serve
    CLI reference

  • Any agent with a shell tool

    Plain CLI. Add --json for a versioned pairmux.v1 envelope with status, output, recovery hints and ordered next steps.

    pairmux --json run deploy "ssh deploy@staging.internal"
    Human collaboration guide

05 — Install

Install in one command.

macOS / Linux

uv tool install pairmux

then pairmux doctor

Needs uv and Python 3.9+ for the tool environment. tmux is optional: when it is on your PATH pairmux uses it (3.2 or newer); otherwise the built-in multiplexer takes over.

Or let the installer set up uv:

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

After installing

pairmux doctor
Reports the backend in use: tmux when it is on your PATH, otherwise the built-in multiplexer. Windows always uses the built-in one.
pairmux update
Keeps your uv install current (v0.6.0+; not on Windows, where you reinstall with uv instead).

Homebrew, pipx, release archives and details are in the install guide.