pi-farm
tmux session manager for pi agents — YAML config, reboot autostart, cron, todo panel, and sessions on other machines over ssh
Package details
Install pi-farm from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-farm- Package
pi-farm- Version
0.73.53- Published
- Nov 22, 2026
- Downloads
- 19.1K/mo · 19.1K/wk
- Author
- doouxiaoyu
- License
- MIT
- Types
- extension
- Size
- 875.9 KB
- Dependencies
- 0 dependencies · 0 peers
Pi manifest JSON
{
"extensions": [
"./extensions/pp-tmux.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pp · 用一个 YAML 管住一农场 pi agent
Declarative tmux farm for pi agents. One YAML file drives the tmux session, the pi session id/name and the remote-pi mesh name — and everything comes back after a reboot.
pi-plus.yml ──► tmux new-session -d -s backend -c ~/code/backend -- pi --name backend --session-id 1a2b3c4d
│ │ │ │
│ │ │ └─ 续接/新建 pi session
│ │ └─ pi 会话显示名 + remote-pi 名称
│ └─ 工作目录
└─ tmux session 名(默认三个名字共用一个)
特性
- 一份 YAML,三层名字:
tmux session/pi --name/remote-pi默认全部等于name,也可分别覆盖。 - 续接或新建 pi session:
pi_session填 session id 就续接(不存在则以该 id 新建),填.jsonl路径就--session。 - 真正在后台跑:
tmux new-session -d,关掉终端不掉线;pp attach随时接管。 - 开机自启:Linux systemd user unit / macOS launchd,
--watch还能定时巡检自动补活。 - 零依赖:单文件 Node CLI,自带 YAML 子集解析器,不装
js-yaml、不需要 Python。 - 可脚本化:
--json、--dry-run、--quiet,退出码可用(up有失败即 1)。 - 安全默认:不经过 shell 拼接命令;tmux 名做白名单校验;重建前先
check。 - 直接跟别的 agent 说话:
pp mesh ls/send直连 remote-pi 的本地 broker,按会话名或跨机地址发消息、拿 ACK、等回复。 - 定时任务:
pp cron add按「一次 / 每 N 分钟 / crontab 表达式」把 prompt 打进会话,或跑一条命令;装一个 crontab 行就管所有任务,重启后能补跑。 - 谁在等我:
pp todo列出「哪个会话卡在问题上」,pp todo attach 2直接进去;pi 弹提示或跑完停在问句时自动登记。 - 能查账:
pp audit是每次改动的流水(谁、什么时候、把哪个会话停了/起了/发了什么),--since 12h --action down就是"昨晚谁动的"。 - 多机器一张表:
pp node add登记一台 ssh 能到的机器,会话写node: prod-01就跑到那台机器上——远端不用装 pp,pp ls/tui/cron/todo一视同仁;机器的base_path/defaults让会话条目只剩两行。 - 机群体检:
pp doctor --nodes并行 ssh 一遍,每台一行给出连通性、负载、uptime、会话数、磁盘、内存。 - 会话可搬家:
pp mv <会话> --node <机器>停掉、改一行node:、在新机器起来;--local挪回来。 - 能收编:
pp adopt --all把机器上已在跑、但没人写进配置的 tmux 会话登记进来(带--node收编别的机器上的)。
安装
# 从 npm 安装(包名 pi-farm,装完命令就是 pp)
npm i -g pi-farm
# 或直接从 GitHub 安装
npm i -g github:HardyDou/pi-plus
# 或克隆后本地软链到 ~/.local/bin/pp
git clone https://github.com/HardyDou/pi-plus.git
cd pi-plus && ./install.sh
# 直接运行也可以:node bin/pp.js <command>
依赖:Node.js ≥ 18、tmux、pi(非 pi 的 agent 也可以,见 agent 字段)。
升级
pp update # 查最新版并升级(npm 全局装的就 npm i -g,git clone 的就 git pull)
pp update --check # 只看有没有新版;有则退出码 1,适合脚本/定时任务
pp update --dry-run # 只打印会跑的升级命令
内网镜像访问不到公共源时:
PP_NPM_REGISTRY=https://nexus.../npm-group pp update;若报notarget,是 npm 的 packument 缓存过期,npm cache clean --force后重试。
命令名被别的程序占了?(macOS 自带 /usr/bin/pp)
macOS 上 /usr/bin/pp 是一个 ASN.1 转换工具,pp ls 会打出它的用法说明。除了 pp,安装时还会一起装两个名字:
pifarm ls # 等价于 pp ls
pi-plus ls
pp alias add pif # 或者自己起个短名字(软链到同一个脚本,升级不会失效)
pp alias ls # 看有哪些别名、目录是否在 PATH 里
pp alias rm pif
pp doctor # 会提示 PATH 上的 pp 到底是不是我们
install.sh 也支持换名字:PP_BIN_NAME=pifarm ./install.sh(或 PP_BIN_NAME="pp pif")。
若你的
npm config get registry指向内网镜像(例如 Nexus),装不到这个包时显式指定公共源:npm i -g pi-farm --registry https://registry.npmjs.org/
Shell 补全(可选):
source completions/pp.bash # bash
fpath+=(~/path/to/pi-plus/completions); compinit # zsh
快速开始
pp init # 生成 ~/.pi/plus.yml(或 --local 生成 ./pi-plus.yml)
$EDITOR ~/.pi/plus.yml
pp check # 只校验配置,不碰 tmux
pp doctor # 环境体检:node / tmux / pi / 自启
pp up # 后台拉起所有 session
pp up --drift # 只补没起来的(可反复敲,适合放 cron)
pp send --all "…" # 一句话发给所有空闲会话(忙的跳过,不排队)
pp status # 看状态:序号、tmux 名、pid、pi session、remote-pi 名
pp attach backend # 进入某个 session(没启动会先启动)
pp attach 3 # 也可以直接给序号(pp ls 第一列的 #)
pp up --dry-run -v # 只打印将要执行的 tmux 命令
按名字操作,省略即全部(restart: no 的会话不参与,见下文策略):
pp up backend docs
pp restart backend
pp down backend # 只停一个
pp down # 全部停掉
pp rm backend # 删除:杀会话 + 删配置条目(会先问一次)
被单独
down掉的会话会不会被拉回来,取决于它的restart策略——unless-stopped/on-failure会记住这次手动停止,always会在下个巡检周期回来。
临时开一个(不写配置)
不想动配置文件时,直接在当前目录(或 -C 指定的目录)开一个:
pp new # 名字 = 目录名(tmux 安全字符,重名自动加 -2)
pp new api -C ~/code/api # 指定目录 + 名字
pp new scratch --agent bash --log -a # 别的 agent、留日志、进去(简写 n)
pp n api --save # 同时写进配置文件,重启后自动拉起
- 名字默认取目标目录名,会被规整成 tmux 安全字符(空格/中文/
.→-);目录名已被占用时自动-2、-3 - 默认 agent 是
pi,自动带--name <会话名>;remote-pi 名称同样取会话名,通过环境变量注入(remote_pi_mode: env),不会改写项目里的.pi/remote-pi/config.json - 常用选项:
-C/--dir、--agent、--log、--save、-a/--attach、--no-remote-pi、--force、--dry-run pp new不依赖任何配置文件;--save会在没有配置时新建~/.pi/plus.yml(或-c/$PI_PLUS_CONFIG指向的路径)并追加这一条
跟别的会话说话(mesh)
pp 直连 remote-pi 的本地 broker(~/.pi/remote/sessions/local/broker.sock),
不需要 pi 进程、不需要配对,本机和其它电脑上的 agent 都能发:
pp mesh ls # 谁在线(只读探测,不会让别人看到上下线)
pp mesh resolve backend # 配置里的会话 → mesh 地址 + 在线状态
pp mesh send backend "构建绿了,可以发版" # 会话名/序号都行
pp mesh send 1 macbook:/Users/me/code/api@api "ping" # 跨机直接写地址
pp mesh send all "5 分钟后重启机器" # 广播
pp mesh send backend "跑一下测试" --reply 60000 # 等它回话,收到就返回
- 单个目标 = 单播并等 broker 的 ACK:
delivered to …(收到)、busy(对方正在跑, 消息被丢弃,稍后重试)、denied、超时;多个目标或all= 组播,不等 ACK - 加
--reply <ms>会在 ACK 之后继续监听,把对方的回复打印出来(单播收到第一条就返回) - 跨机地址形如
macbook:/Users/me/code/api@api;本机注册名默认pp-mesh,用--as改 - 与
pp send的区别:pp send是往 tmux pane 里打字(对方当成"用户输入"),pp mesh send是走 agent 之间的消息通道(对方收到[agent-network] message from …信封) - broker 没起来时会明确报
no mesh broker at …;pp mesh ls/resolve可离线用来看地址
别的机器上的会话(pp node)
一台机器一个节点,登记在同一个配置文件里;会话加一行 node: 就搬过去。
远端只需要 sshd + tmux(跑 agent 才需要 pi),不用装 pp。
pp node add prod-01 --host 10.0.0.11 --user deploy --identity ~/.ssh/id_ed25519
pp node test prod-01 # tmux/pi/pp/负载/会话数,一次 ssh 往返
pp node exec prod-01 -- df -h / # 一条命令,不占会话
pp node ls # NODE TARGET PORT AUTH SESSIONS NOTE
nodes:
- name: prod-01
host: 10.0.0.11
user: deploy
identity: ~/.ssh/id_ed25519
tags: [prod, web] # pp up --tag prod / pp node exec --tag web -- …
guarded: true # pp down / pp rm 跳过它,除非 --force
drained: true # 维护中:pp up / 自启 / --heal 都跳过它
- name: textbook
host: textbook.example.com
password_env: TEXTBOOK_PASS # 密码不落盘;变量没设置会直接报错
sessions:
- name: prod-api
node: prod-01 # 这个会话在 prod-01 上
cwd: /srv/api
- name: textbook-web
node: textbook
cwd: /srv/web
之后 pp ls 的 NODE 列显示归属,pp attach prod-api、pp logs prod-api、
pp send prod-api "..."、pp tui 里的预览、pp cron 的投递全都自动走 ssh。
连不上的机器整台标成 unreachable,而不是假装里面的会话都停了。
密码走 sshpass -e(环境变量 SSHPASS),不进命令行,ps 看不到;
写在配置里的密码会让文件自动 chmod 600 并给你警告。详见 docs/nodes.md。
在 pi 里用 /pp-*(扩展)
pp 自带一个 pi 扩展:把 tmux 的 Ctrl-b s、Ctrl-b d 变成斜杠命令,不用离开对话。
pi install npm:pi-farm # 装进 ~/.pi/agent/settings.json,之后每个会话都有
pi -e npm:pi-farm # 只想这次带着它
| 命令 | tmux 等价 | 作用 |
|---|---|---|
/pp-ls |
Ctrl-b s |
列出所有会话,上下选择、回车切换 |
/pp-sw <会话> |
Ctrl-b s + 回车 |
直接切,支持唯一前缀与参数补全 |
/pp-quit |
Ctrl-b d |
断开当前终端,会话和 pi 继续跑 |
/pp-status |
— | 当前会话/窗口/pane/cwd/pi 会话 id/remote-pi 名字/pp 版本 |
/pp-peek [会话] [-n N] |
— | 看另一个会话最近 N 行输出,不切换 |
细节与排障见 docs/extension.md:
- 只操作"看着你"的那个 tmux client(
switch-client -c/detach-client -t),没有 client 附着时给提示而不是报错; /pp-status、/pp-peek用appendEntry渲染,不占模型上下文;pi -p下改为写 stdout;- 只在 tmux pane 里可用(靠
$TMUX定位服务器)。
定时任务(pp cron)
三件事:什么时候、送给谁、送什么。调度和存储都在 pp 自己手里
($XDG_STATE_HOME/pi-plus/cron.json),crontab -l 里永远只有一条 pp cron tick。
# 一次性:30 分钟后,往 backend 会话打一句 prompt
pp cron add --session backend --in 30m "看一下刚才那次 CI 的结果"
# 重复:每天早上 9 点(本地时间)
pp cron add --session docs --cron "0 9 * * *" "汇总昨天的提交,写到 docs/notes.md"
# 重复:每 5 分钟跑一条命令(不经过 pi)
pp cron add --every 5m --command "curl -fsS http://localhost:8080/health"
pp cron add --all --every 10m --idle-after 10m "忽略我的心跳检测,请继续你的任务" # 只在安静 10 分钟后才推
pp cron dryrun 636b62 # 只读:这一拍会推给谁,其余为什么被跳过
pp cron add --all --every 10m --window 23:00-08:00 "…" # 夜里不推(本地时间,可跨午夜)
pp cron add --heal --every 5m # 自愈:只补"该在没在的"会话
# 每周一、周二、周三 9 点
pp cron add --session risk-01 --cron "0 9 * * 1,2,3" "汇报昨天夜里跑的策略结果"
三种 schedule 选一个:
| 写法 | 含义 | 例子 |
|---|---|---|
--at <ISO> / --in <时长> |
只跑一次 | --at 2026-11-21T09:00、--in 90m |
--every <时长> |
每隔一段时间 | --every 30s、--every 2h |
--cron "<表达式>" |
crontab 语法,本地时间 | "*/15 * * * *"、"0 9 * * 1-5" |
--session 省略时用当前 tmux 会话(在 pi 里就是脚下这个);--command 与 prompt
二选一。作业管理:
pp cron ls # 表:ID / 目标 / 时间表 / 下次运行 / 跑过几次 / 上次结果
pp cron run 3c764f # 立刻跑一次(调试用,不动时间表)
pp cron rm 3c764f # 删掉
pp cron pause 3c764f # 静音,保留时间表与历史(resume 回来)
pp cron retarget 3c764f --session backend # 会话改名了:搬目标,不丢历史
pp cron logs -n 40 # 最近的投递记录
pp cron reset 3c764f # 把 lastRun 清掉,让它按时间表重排
pp cron status # crond 装没装、有没有到期作业、日志在哪
得有人每分钟叫它一次(pp cron tick,自带文件锁,重入会被跳过):
pp cron install # 往 crontab 写托管块:每分钟一次 + @reboot 一次补跑
pp cron install --print # 先看看会写什么
pp cron uninstall # 只删这个托管块,你自己的行一行不动
@reboot + 分钟级 tick 的组合负责重启后补跑:机器关机期间到期的作业会在开机后
第一次 tick 触发,前提是迟到时间没超过 --catch-up(默认 2 小时,--catch-up 0 表示
"迟到就别跑了")。超过窗口的会被标成 skipped: missed by 2h 30m,而不是几小时后突然
往你的会话里打一句话。
在 pi 里还多一个工具 schedule:直接说「明天早上九点提醒我」就行,模型会自己把它换算成
绝对时间再建作业(同一个 cron.json)——斜杠命令模型看不见,工具才看得见。
细节见 docs/cron.md。
谁在等我(pp todo)
会话卡在一个问题上,你却在别的窗口 —— 这类「等你决策」的事会被自动收进一张清单:
pp todo # 需要我决策的
# # STATE WAITED SESSION KIND WHAT
# 1 new 3m risk-01 settled 要我现在合并到 main 吗?
# 2 new 18m backend prompt waiting: 选一个分支 — Enter to switch
pp todo attach 1 # 进入那个会话(顺手标记 seen)
pp todo answer 1 "用方案 B" # 或者不回终端,就地答复并结掉这条
pp todo done 1 2 # 处理完了
pp todo ls --all --json # 连已完成的、机器可读
怎么判定「在等你」:
prompt—— pi 弹出了阻塞式提示(ui_prompt_start:select/confirm/input/editor),会话确实停在那儿;settled—— 一轮跑完,最后一段话以问号结尾或含「请确认 / 要不要 / 是否需要」;manual——pp todo add "…" --session <name>,或模型自己调用todo工具登记。
会话重新跑起来时,它自己的未完成待办会自动标记完成(你已经回答过了)。
噪音太大就 export PP_TODO_SETTLED=off(只记阻塞提示),想全都记就 always。
在 pi 里还有 /pp-todo:弹出清单,选中即切过去。
细节(数据文件、去重规则、边界)见 docs/todo.md。
一块屏看全部(pp tui)
会话多了以后,pp ls + pp todo + pp attach 来回敲就烦了。pp tui 把它们拼成一屏:
┌ sessions (7) ──────────────────────────┐ ┌ todo (2) ─────────────────────────────────────────────┐
│ 1 bh-system-01 running │ │ 1. risk-01 — 要我现在合并到 main 吗? (3m, settled) │
│ 2 bh-system-02 running │ │ 2. backend — waiting: 选一个分支 (18m, prompt) │
│ 3 mango-release-01 running │ └───────────────────────────────────────────────────────┘
│ 4 mano-dev-01 attached │ ┌ preview: bh-system-01 ────────────────────────────────┐
│ 5 ops-5 running │ │ ● Bash(git log --oneline -5) │
│ 6 risk-01 running │ │ a1b2c3d fix: ... │
│ 7 risk-02 running │ │ ⏳ Working... │
└────────────────────────────────────────┘ └───────────────────────────────────────────────────────┘
↑↓ move PgUp/PgDn scroll Tab panel Enter attach d done [ ] width -/+ rows f follow / find q quit
- 待办框的高度跟着内容走(空 3 行、每条 +1、最多 9 行),预览拿走剩下的行;
- 终端窄于 88 列时自动竖排(会话 / 待办 / 预览),空待办框直接隐藏;
- 会话行末的
3m/2h是这条会话最后一次有动静的时间(#{session_activity}),一眼看出谁在干活、谁已经晾了一下午; - 安静超过
PP_STALE_MINUTES(默认 30)分钟的会话标成琥珀色、行末带!—— "卡在 Working 一下午"那种最费时间的情况一眼就能看见(pp ls的IDLE列、--json的idleSeconds是同一份数据); - 从会话回到面板:
pp back或/pp-back(switch-client,不 detach,不留残留画面)。
按键:
| 键 | 作用 |
|---|---|
↑ ↓ / k j |
在聚焦的列表里移动 |
PgUp / PgDn |
整页翻动列表(光标跟着走,标题框不会跑丢) |
- / + |
待办框少一行 / 多一行,预览把行让出来或收回去 |
s |
切换排序:配置顺序 → 最久没动优先 → 按名字(footer 显示当前排序) |
/ |
输入子串过滤会话(名字/机器/状态),Enter 保留、Esc 清除 |
f |
暂停 / 恢复预览跟随(要读一段输出时按住它别动) |
Tab |
切换列表(会话 ↔ 待办) |
Enter |
进入(会话:在 tmux 里 switch-client,在 tmux 外 tmux attach);从待办进则进它所属的会话 |
d |
把选中的待办标记完成 |
D |
补齐 drift:启动"该在却没起"的会话(等于 pp up --drift,不用离开面板) |
[ / ] |
左列变窄 / 变宽(每按一次 4 列) |
r |
立即重绘 |
q / Esc / Ctrl-C |
退出 |
Enter 进去后 Ctrl-b d 回来,面板会自动重绘 —— 不退出 pp。
它不是终端模拟器:右侧下半部分是 capture-pane 的快照(每秒刷新),不是活终端。
真正接管终端的是 tmux,这也是它只有 ~400 行、不容易出玄学 bug 的原因。
渲染上还有一条硬规则:每一行都用绝对光标定位(ESC[{row};1H)重画、写完关掉自动折行。
这样即使某行宽度算错一个字符(中文、双宽 emoji 最常见),最多脏自己那一行,
不会让终端折行、多占一行、把整屏往上滚 —— 也就是不会出现"每刷新一次就多一帧"的样子。
pp tui # 交互
pp tui --left 24 # 左列固定 24 列(也能写 30%)
pp tui --once # 打印一帧就退出(管道/CI 里也能用)
pp back # 从任何会话切回这个面板(不 detach,不留残留画面)
pp tui -c ./pi-plus.yml --socket work
文档
| 文档 | 内容 |
|---|---|
| docs/configuration.md | 配置参考:全部字段、restart 策略矩阵、remote-pi 三种模式、完整示例、校验规则 |
| docs/cli.md | 命令行参考:全局选项、退出码、每个命令的用法/JSON/env |
| docs/autostart.md | 开机自启:systemd 单元为什么必须有 KillMode=none、linger、timer、launchd、WSL 两侧配置、冷启动验证 |
| docs/architecture.md | 内部实现:模块职责、up 数据流、名字解析、restart 状态机、tmux 目标规则 |
| docs/troubleshooting.md | 排障手册:按报错原文查(起不来、can't find pane、名字不对、自启没生效、attach 乱码…) |
| docs/development.md | 开发指南:跑测试、改代码的规矩、测试分层、发布流程(含 npm staged publishing 的坑) |
| docs/extension.md | pi 扩展 /pp-* 与 schedule 工具:在会话里切 tmux、看别人的屏幕、断开连接、让 agent 自己排定时任务 |
| docs/cron.md | 定时任务:三种时间表、crond 托管块、补跑与迟到语义、时区、调试 |
| docs/nodes.md | 多机器:nodes: 与 node: 字段、四种认证方式(密钥/agent/ssh config/密码)、pp node add/ls/show/rm/test/ssh、远端会话怎么跑、连不上怎么查 |
| docs/roles.md | 角色:role 是什么、怎么贴、一个标签能做什么(筛/排/批量/审计/追问)、命名经验与常见问题 |
| docs/todo.md | 待办:三种来源、去重、PP_TODO_SETTLED 噪音控制、数据文件、边界 |
配置参考
version: 1
# 可选:所有 session 跑在独立 tmux socket 上(等价于每条命令都加 --socket pi-plus)
# tmux:
# socket: pi-plus
defaults: # 所有 session 的默认值
agent: pi # 可写成 "pi --verbose",按空格分词、不经 shell
args: [] # 追加参数:["--approve"]
env: {} # 追加环境变量
sessions:
- name: backend # 必填;tmux / pi / remote-pi 的默认名
cwd: ~/code/backend # 必填;支持 ~ 与相对路径(相对配置文件所在目录)
# ---- 以下全部可选 ----
tmux_name: backend # tmux session 名(默认 name)
pi_session_name: backend # pi --name(默认 name)
remote_pi_name: backend # remote-pi 名(默认 name;false/null 表示不设置)
remote_pi_mode: config # config | env | off(默认 config)
pi_session: 1a2b3c4d # pi session id;或 ~/.pi/.../x.jsonl 路径
# pi_session_dir: ~/.pi/agent/sessions # 可选,传给 --session-dir
agent: pi # 覆盖 defaults.agent(bash / claude / "pi --verbose" 都行)
args: ["--approve"] # 追加参数
env: # 覆盖/追加环境变量
TZ: Asia/Shanghai
restart: unless-stopped # no | always | on-failure | unless-stopped
log: ~/.pi/plus/backend.log # 可选:pipe-pane 落盘
remain_on_exit: false # 可选:进程退出后保留 pane 便于看报错
字段速查:
| 字段 | 默认 | 说明 |
|---|---|---|
name |
必填 | 会话逻辑名,也是另外三个名字的默认值 |
cwd |
必填 | 工作目录,不存在则 up 直接报错 |
tmux_name |
name |
tmux session 名,白名单 [A-Za-z0-9][A-Za-z0-9_-]* |
pi_session_name |
name |
pi --name,会话列表里显示的名字 |
remote_pi_name |
name |
remote-pi mesh 名,自动 sanitize(空格/斜杠→-) |
remote_pi_mode |
config |
config 写 <cwd>/.pi/remote-pi/config.json;env 用 REMOTE_PI_DIRECT_CONFIG;off 不设置 |
pi_session |
新会话 | session id(--session-id)或 .jsonl 路径(--session) |
pi_session_dir |
pi 默认 | --session-dir |
agent |
pi |
启动命令,支持带参数;非 pi 时不追加 pi 专用flag |
args |
[] |
追加到命令末尾 |
env |
{} |
注入环境变量 |
restart |
always |
拉起策略,取值见下节(对齐 docker compose) |
log |
无 | pipe-pane 输出文件 |
remain_on_exit |
false |
保留 dead pane;restart: no 会自动开启 |
restart 策略(和 docker compose 一致)
| 值 | 裸 up / 开机自启 |
--watch 巡检 / 崩溃后 |
手动 down <name> 之后 |
|---|---|---|---|
always(默认) |
启动 | 补起 | 下次 up / 巡检仍会启动 |
no |
跳过 | 跳过 | —(只能 up <name> 手动启动) |
unless-stopped |
启动 | 补起 | 记住这次停止,自启/巡检都不碰;up <name> 解除 |
on-failure |
启动 | 只在 pane 进程异常退出(dead pane)时补起 | 同 unless-stopped |
判定规则:
- 不带名字的命令只处理
restart != no的会话;up <name>/restart <name>永远生效, 并会清除"手动停止"记录。 - 会话存在但 pane 已经死了(agent 进程退出)时,
up对restart != no的会话会重建;restart: no会保留 dead pane(自动打开remain-on-exit),status显示dead,pp logs <name>还能看到它最后吐出来的报错,up <name>才会重建。 - 这和 compose 里
docker compose ps还能看到Exited (1)的容器是一个意思。 - 手动停止记录存在
$XDG_STATE_HOME/pi-plus/state.json(默认~/.local/state/pi-plus/state.json), 按配置文件路径 + 会话名区分。 - 开机自启用的就是"巡检语义":
pp up --config <cfg> --reconcile --quiet, 所以unless-stopped/on-failure在你手动停掉后不会在重启时自己回来。
sessions:
- name: backend
cwd: ~/code/backend
restart: always # 常驻,挂了就补
- name: experiment
cwd: ~/code/exp
restart: no # 不参与自动拉起,只按需 pp up experiment
名字映射:一个名字,三处生效
| 想设置 | 字段 | 实际效果 |
|---|---|---|
| tmux session | tmux_name |
tmux new-session -s <name> |
| pi 会话名 | pi_session_name |
pi --name <name>(续接旧会话也会改名) |
| remote-pi mesh 名 | remote_pi_name |
写 agent_name 到 <cwd>/.pi/remote-pi/config.json |
三个都不写时全部等于 name,所以最简配置只有两行:
sessions:
- { name: backend, cwd: ~/code/backend }
remote-pi 的
agent_name是按目录存的。同一cwd下多个 session 配不同remote_pi_name(且用默认的remote_pi_mode: config)会互相覆盖,pi-plus会给出 warning;想让同目录多个 agent 各自有名字,用remote_pi_mode: env(每个进程独立 环境变量),这样pp check不再告警。
小提示:
remote_pi_mode: config会在项目里生成.pi/remote-pi/config.json, 建议加到全局 gitignore:echo '.pi/remote-pi/' >> ~/.config/git/ignore。
帮助
pp help # 总览:命令表、全局选项、restart 策略、配置示例
pp help up # 单命令:用法、说明、选项、示例、相关命令
pp up --help # 等价写法(-h 也可以)
pp help ls # 别名也能查,自动解析到 status
pp help instal # 拼错会给建议:did you mean 'pp help install'?
pi-plus不带参数 =pp help-h/--help出现在任何位置都生效,已经写了命令就给该命令的帮助- 帮助内容由
src/help.js的COMMANDS表生成,总览、单命令、补全词表共用一份数据, 加新命令时不会出现"文档忘了更新"
退出码:
| 码 | 含义 |
|---|---|
0 |
成功 |
1 |
运行时失败(会话启动失败、doctor 有检查项不通过) |
2 |
用法/配置错误(未知命令、未知选项、配置校验失败、找不到配置) |
命令参考
凡是接 <name> 的地方都可以写成 pp ls 的 # 序号(1 起,按配置顺序;
若真有会话叫这个名字,名字优先):pp attach 3、pp logs 3、pp down 2 5。
念不清的那些,按"我遇到什么"排:
| 我想 | 命令 |
|---|---|
pp new --from risk-01 --save |
照着一个跑对的会话克隆(同名族第 N 个不用重打) |
pp(不带参数) |
三行现状 + 六个常用命令 |
pp plan |
该先做哪一件、再做什么(带顺序与原因) |
pp handover |
换班那一页:过去 24h 变了什么、现在什么没起、还有什么要人决定 |
pp plan --node t114 |
只问那一台机器:要让它现在能接活,按顺序敲哪几条 |
pp backup / pp restore |
改配置前留一份,改坏了拿回来(普通目录拷贝,带 diff 预演) |
pp runbook |
事故处理手册:会话全没了 / 不投递 / 机器连不上 … 各自按序怎么查 |
pp snapshot |
把会话表、定时任务、机器、审计尾部打成一块,直接贴进工单 |
pp why risk-01 |
一句话解释它为什么是这个状态(drain/手工停/该在跑却没在跑) |
pp why --node t114 |
同一问题问整台机器(ssh/tmux/维护中/哪些没起) |
pp role risk-01 pm |
给会话贴角色标签(dev/pm/qa);--role 可筛选表,也能筛选批量动作(pp send --role pm "…") |
# 会话
pp new [name] [opts] 在当前目录/指定目录临时开一个(别名 n、create;--from 克隆、--node 远端、--role、--save)
pp up [name|#...] 后台创建/启动(别名 start;--drift 只补没起的、--wait 等到能接话、--node/--tag/--role 批量)
pp down [name|#...] 停止(--force 连 guarded/drained 一起、--yes 确认维护窗口内的操作)
pp rm <name|#>... 删除(杀掉会话 + 从配置里删掉这一条)
pp restart [name|#...] 重启(遵守 restart 策略)
pp adopt [name...] 把已在跑但配置里没有的会话登记进来(--all、--node)
pp mv <name|#> --node <机器> 把会话搬到别的机器(--local 搬回本机、--cwd 换目录)
# 看
pp status [name|#...] 状态表,第一列是 # 序号(--json、--watch、--started、--role、--sort、--node)
pp logs <name|#> [-n 200] 打印滚动输出(-f 跟随,--grep/--context、--stamp、--save)
pp why <会话|机器> 一句话解释它为什么是这个状态(--node 问整台机器、--role 问一个标签)
pp plan 该先做哪一件、再做什么(--node 只看一台机器)
pp handover [--since 24h] 换班那一页:变了什么 / 现在什么没起 / 还有什么要人决定(--send 交给某个会话)
pp snapshot 会话表 + 定时任务 + 机器 + 审计尾部打成一块,直接贴进工单
pp audit [target] 这台机器改过什么、谁改的(--action、--since、--role、--prune)
pp runbook [场景] 事故处理手册(--markdown 输出整本 docs/runbook.md)
pp tui 一块屏管所有会话和待办(Enter 进入、pp back 回来)
# 动
pp attach <name|#> 进入;不存在则先启动
pp send <name|#> "文本" 往 pane 里打字并回车(--no-enter 不回车;--all/--node/--tag/--role 撒网,忙的跳过;--until-idle 干完再打印屏幕)
pp todo [ls|attach|done] 谁在等我决策:列表 / 进去 / 完成(--all、--session)
pp role <会话> [角色|-] 给会话贴标签(--list 看所有标签与未贴的)
pp cron add|ls|rm|run|tick 定时把 prompt/命令送进会话(--in/--every/--cron,--all/--role,--heal/--sweep)
pp mesh ls|resolve|send 直连 remote-pi broker:看谁在线 / 查地址 / 发消息(--reply 等回复)
# 多机
pp node ls|show|add|rm 管别的机器:登记、看详情(--from-ssh-config 抄 ~/.ssh/config)
pp node test [name|--all] 体检:ssh / os / tmux / pi / 负载 / 磁盘 / 会话数(--json)
pp node exec <name> -- <cmd> 在机器上跑一条命令(--tag/--all、--parallel、--timeout)
pp node ssh <name> 用登记的认证方式开一个交互 shell
pp node drain|undrain <name> 维护窗口:期间 pp up / 自启 / --heal 都不动它的会话
# 本机与自身
pp check 校验配置(--remote 连远端会话、--brief 只报结论)
pp clean [--keep 2m] 把 pp 自己写大的日志原地收回(--dry-run)
pp doctor 环境诊断:配置/自启/扩展/漂移/日志/卡住/定时任务(--brief 给下一条命令)
pp init 写示例配置
pp install [--watch N] 安装开机自启(别名 autostart)
pp uninstall 卸载自启
pp alias [ls|add|rm] 换/加一个命令名(pp 被别的程序占用时用)
pp update [--check] 升级到最新发布版(npm / git 安装自动判断)
pp help [命令] 帮助(不带参数为总览)
pp version 打印版本
全局选项:-c/--config、--socket、--json、--dry-run、--force、--all、-q、-v、-h、-V。
--reconcile 是给自启/巡检用的:跳过被手动停止的 unless-stopped / on-failure 会话。
日常手动 up 不需要它。
配置文件查找顺序:
-c/--config <path>$PI_PLUS_CONFIG./pi-plus.yml、./pi-plus.yaml、./plus.yml、./plus.yaml~/.pi/plus.yml、~/.pi/plus.yaml$XDG_CONFIG_HOME/pi-plus/config.yml(默认~/.config/pi-plus/config.yml)
开机自启
完整说明(KillMode=none 的原因、linger、timer、launchd、WSL 两侧、冷启动验证)见 docs/autostart.md。
pp install # 开机/登录时按 restart 策略 up 一次
pp install --watch 300 # 另外每 5 分钟巡检,挂了自动补
pp install --print # 只打印 unit/plist,不落盘
pp uninstall
Linux(systemd user unit):写入 ~/.config/systemd/user/pi-plus.service,
systemctl --user enable。要开机即启动(不用先登录)需要一次 linger:
sudo loginctl enable-linger $USER
macOS(launchd):写入 ~/Library/LaunchAgents/com.pi-plus.plist,
RunAtLoad 登录即启动;--watch 用 StartInterval 定时巡检;日志在
~/Library/Logs/pi-plus.log。
WSL2:分两半,缺一不可。
WSL 内部(
pp install能做的部分):/etc/wsl.conf里[boot] systemd=true(较新 WSL 默认开启,可用cat /etc/wsl.conf确认)sudo loginctl enable-linger $USER:不登录也能启动 user 服务pp install:写~/.config/systemd/user/pi-plus.service并 enable
Windows 侧(WSL 内部再怎么配也做不到):Windows 重启后 WSL 发行版本身不会自己 启动,没有任何进程能替你触发它。必须由 Windows 上的一次动作把发行版拉起来,例如 登录时执行(PowerShell,无需管理员):
$p = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\pi-plus.vbs" Set-Content -Encoding ASCII $p 'Set s = CreateObject("WScript.Shell") : s.Run "wsl.exe -d <发行版名> -u <用户名> -e /bin/true", 0, False'把
<发行版名>换成wsl -l -v里的名字(例如Ubuntu-24.04)。也可以用任务计划 程序建一个“登录时”任务,动作同样是wsl.exe -d <发行版名> -u <用户名> -e /bin/true。原理:这条命令把发行版启动起来(systemd 成为 PID 1 并常驻),
--reconcile的pi-plus.service随即按各会话的restart策略拉起 agent;命令本身会立刻退出, VBScript 用隐藏窗口跑,不闪黑框。
只配 WSL 内部、不配 Windows 侧:
wsl --shutdown或重启后不会有任何会话,直到你手动 打开一次终端。pp doctor在 WSL 下会多打一行wsl提示这件事。
续接已有 pi 会话
# 1) 找到 session id:文件名就是 id
ls ~/.pi/agent/sessions/--<cwd编码>--/
# 编码规则:绝对路径里的 "/" 换成 "-",例如 /home/me/code → --home-me-code--
# 也可以在目录里跑 `pi --resume` 从列表里挑,再按提示查看 id
# 2) 写进配置
sessions:
- name: backend
cwd: ~/code/backend
pi_session: 1a2b3c4d # id 不存在时 pi 会以该 id 新建
同理,把之前手动 tmux new -s xxx 起的会话迁过来:先 pp down,
或者直接 tmux kill-session -t xxx 后 pp up。
排障
完整版见 docs/troubleshooting.md,这里是最常见的几行:
| 现象 | 处理 |
|---|---|
session "x" exited immediately |
-v 看实际命令;先用 check 确认 cwd/agent;临时加 remain_on_exit: true 看报错 |
tmux ... can't find pane |
老版本 bug,升级;pane 目标需要 =name: 形式 |
| remote-pi 名字不对 | 看 <cwd>/.pi/remote-pi/config.json 的 agent_name;同名冲突时 broker 可能显示 name#2 |
| 自启没生效 | systemctl --user status pi-plus;WSL 确认 systemd 开启;pp doctor |
| pi 找不到 | systemd 的 PATH 由 install 自动写入 node 所在目录;自定义路径用 agent: /abs/path/pi |
pp ls 打出一大段 ASN.1 用法 |
那是 macOS 自带的 /usr/bin/pp。用 pifarm ls,或 pp alias add pif 换个名字(见安装) |
开发
npm test # node --test,纯单元测试,不需要 tmux
./test/e2e.sh # 端到端冒烟测试(需 tmux/pi,约 3 分钟,会临时装一个 systemd unit 再删掉)
node bin/pp.js --help
代码结构:
bin/pp.js CLI 入口、参数解析
src/config.js YAML → 归一化配置、argv 构建
src/yaml.js 零依赖 YAML 子集解析器
src/tmux.js tmux 封装(含 dry-run 只读查询)
src/remote-pi.js remote-pi 配置读写
src/autostart.js systemd / launchd 模板与安装
src/commands.js 各子命令实现
English
pi-plus keeps a farm of pi coding
agents alive in tmux. Declare sessions in one YAML file; each session gets a
tmux session, a pi session (resumed by id or freshly created), a pi display
name, and a remote-pi mesh name — all defaulting to the same name.
npm i -g pi-farm
pp init && $EDITOR ~/.pi/plus.yml
pp check && pp up && pp status
pp attach backend
pp install --watch 300 # survive reboots, reconcile every 5 min
Minimal config:
version: 1
sort: name # same family sticks together: risk-01, risk-02, risk-pm
nodes: # sessions can run on other machines over ssh
- name: t114
host: 192.168.5.114
user: ops
identity: ~/.ssh/id_ed25519
base_path: /srv # a session's relative cwd lands here
tags: [test, baohan]
defaults: { agent: pi, restart: always }
sessions:
- name: backend
cwd: ~/code/backend
pi_session: 1a2b3c4d # optional: resume (or create) this pi session
role: dev # a label: filter, fan out, audit, schedule by it
- name: api
node: t114 # runs on that machine, in /srv/api
cwd: api
Name overrides: tmux_name, pi_session_name, remote_pi_name.
remote-pi mode: config (default, writes <cwd>/.pi/remote-pi/config.json),
env (REMOTE_PI_DIRECT_CONFIG), off.
What it can do
| I want | Command |
|---|---|
| see everything and jump in | pp tui (Enter attaches, pp back returns) |
| a table, or a live one | pp status, pp status --watch |
| what should I do next | pp plan — ordered steps with reasons |
| hand the shift over | pp handover [--send <session>] |
| why is this one like this | pp why <session>, pp why --node <machine> |
| work an incident | pp runbook — the runbook, one scenario at a time |
| one line into an agent | pp send <session> "…" (--all, --role, --tag, --node) |
| something on a schedule | pp cron add --all --every 10m "…" (--heal, --sweep) |
| sessions on other machines | pp node add/test/exec/ssh/drain |
| who changed what, and when | pp audit [--action up] [--role dev] |
| shrink what pp wrote | pp clean (in-place, keeps the last 2 MB) |
Tag any session with a role (pp role api dev) and every verb that takes
--role will fan out over it: pp up --role dev, pp logs --role dev -f,
pp send --role pm "standup", pp cron add --role qa --every 1h "…".
Inside pi, the bundled extension adds /pp-ls, /pp-sw <session>, /pp-quit,
/pp-status, /pp-peek [session] [-n N], /pp-todo and /pp-back
(install with pi install npm:pi-farm; upgrade with
npm install --prefix ~/.pi/agent/npm pi-farm@latest).
Zero runtime dependencies. Requires Node.js ≥ 18, tmux, and pi (any command
works via agent:). Every remote action is plain ssh … tmux … — the other
machine does not need pp installed.
License
MIT © 2026 HardyDou