pairmux

為終端機打造的代理與電腦介面（ACI）

讓你的 AI 代理操作終端機。 關鍵時刻，由你接手。

pairmux 為 AI 程式碼代理提供真正、持久的終端機——REPL、TUI、ssh、[y/N] 提示都難不倒它；一旦提示需要密碼或人為判斷，就把同一個即時終端機交到人類手上。

安裝 pairmux閱讀文件
程式碼代理

把這個版本部署到 staging。

我會開一個持久的終端機，然後 ssh 進去。

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

伺服器要求輸入密碼。我不會亂猜——交給你處理。

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

等待人類接手…

awaiting-input · secret

可由人類接手：pairmux attach deploy

$ ssh deploy@staging.internal
deploy@staging.internal's password:
以真實 pairmux 輸出編排而成的示意動畫。

01 — 問題所在

一般執行工具做不到的三件事。

多數代理的 shell 工具在沒有終端機的情況下執行指令。跑 ls 沒問題，其他的就不行了。

  • 沒有終端機。

    python、psql、ssh、git rebase -i、分頁器和 TUI 都需要 PTY。沒有它，這些程式不只是難用——而是根本無法使用。

    $ python
>>>

  • 沒有人可以問。

    遇到密碼提示時，代理只有兩個爛選項：亂猜，或放棄。pairmux 提供第三個：把即時終端機交給真人。

    Password:

  • 指令之間沒有記憶。

    source venv/bin/activate、export、nvm use 每次呼叫後就消失，只好在每個指令裡重組一次。真正的 shell 會記住它們。

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

02 — 運作方式

交接循環。

  1. pairmux --json new --name deploycreated

    一個持久的 shell，狀態在指令之間保留。

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

    run 會一直等到指令結束、出現可辨識的提示，或逾時為止。看起來像機密的提示會附上 do NOT guess or type secrets。

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

    代理停在可恢復的檢查點，人類會收到桌面通知（盡力送達）。

  4. pairmux attach deployattached

    人類進入同一個即時終端機，回應提示後離開。也可以選擇留言：pairmux --json note deploy "entered the staging password"

  5. wait 返回human-done

    提示一被回應，等待就結束。留言可以說明人類做了什麼，但恢復執行並不需要它。

每個終端機只有一個寫入者，讀取不需加鎖。每個位元組都有日誌，可用 log 取回。

03 — 適用情境

什麼時候該用，什麼時候不用。

用你原本的 shell 工具

  • 簡短的一次性指令：ls、git status、快速的 grep。
  • 在全新環境中執行、不需人類介入的長時間非互動工作——你的工具本身的背景執行就能做好。

用 pairmux

  • 互動式程式：REPL、TUI、分頁器、[y/N]、ssh、sudo。
  • 需要保留的 shell 狀態：venv、環境變數、nvm use。
  • 憑證提示、需要判斷的時刻、真人即時接手。
  • 開發伺服器或 tail -f，而且可能有人想一起看。

當終端機、它的狀態或真人本身就是工作的一部分，pairmux 就派得上用場。

04 — 相容工具

搭配你已經在用的代理。

  • Claude Code

    安裝一次內建的 Agent Skill，代理就會學會 new → run → wait 循環與安全規則。

    pairmux skill install --target all
    Agent Skills 指南

  • MCP 用戶端

    stdio MCP 伺服器把 new、run、peek、wait、send、log、ls、kill、note 和 doctor 提供為具型別的工具。

    pairmux mcp serve
    CLI 參考

  • 任何有 shell 工具的代理

    純 CLI。加上 --json 即可取得有版本的 pairmux.v1 封包，內含狀態、輸出、復原提示與依序的下一步。

    pairmux --json run deploy "ssh deploy@staging.internal"
    人機協作指南

05 — 安裝

一行指令完成安裝。

macOS / Linux

uv tool install pairmux

接著執行 pairmux doctor

工具環境需要 uv 與 Python 3.9 以上。tmux 為選用：若 PATH 中有 tmux（3.2 以上），pairmux 就會使用它；否則改用內建的多工器。

或讓安裝程式幫你設定 uv：

curl -fsSL https://pairmux.treeleaves30760.com/install.sh | bash
先看看 install.sh 的內容

安裝之後

pairmux doctor
回報目前使用的後端：PATH 中有 tmux 就用 tmux，否則使用內建多工器。Windows 一律使用內建多工器。
pairmux update
讓你的 uv 安裝保持最新（v0.6.0 以上；Windows 不適用，請改用 uv 重新安裝）。

Homebrew、pipx、發行版壓縮檔與更多細節，請見安裝指南。