rigs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

rigs: your route into OpenRig

rigs：你的OpenRig接入通道

OpenRig runs a team of coding agents (Claude Code, Codex and others) side by side in tmux. A local daemon keeps their tasks, messages and state, so the team keeps working across restarts. This skill gets OpenRig installed, gets a team working on what the person wants, and shows how to work with that team from here.

The goal is a team doing the person's work, not just an install. Go through the steps in order and stop early only if the person asks you to. When they say what they want built, give it to OpenRig's operator (step 2) instead of building it yourself.

Tell the person what you're about to run and why before you run it. Don't install system packages or change their machine without a yes. Starting OpenRig and a team writes files: Codex hooks and settings in

~/.codex/config.toml

, a discovery skill in

~/.claude/skills

and

~/.agents/skills

, and, in the repository, managed guidance in

AGENTS.md

CLAUDE.md

plus the team's skills and plugins. Say so before you start OpenRig (the full list).

OpenRig在tmux中并行运行一组编码代理团队（包括Claude Code、Codex等）。本地守护进程会保存它们的任务、消息和状态，因此团队在重启后仍能继续工作。本技能用于安装OpenRig、启动团队处理用户需求，并说明如何从当前环境与该团队协作。

目标是让团队完成用户的工作，而非仅仅完成安装。 请按顺序执行步骤，仅在用户明确要求时提前终止。当用户说明想要构建的内容时，将需求交给OpenRig的operator（步骤2），不要自行构建。

在执行命令前，告知用户你即将运行的内容及其原因。未经用户同意，不得安装系统软件包或修改其设备。启动OpenRig和团队会写入以下文件：

~/.codex/config.toml

中的Codex钩子与配置、

~/.claude/skills

和

~/.agents/skills

中的发现技能，以及代码仓库中

AGENTS.md

或

CLAUDE.md

里的托管指南，还有团队的技能与插件。在启动OpenRig前请告知用户这一点（完整列表）。

1. Install OpenRig, if it isn't installed

1. 安装OpenRig（若未安装）

Check first:
```
rig --version
```
. If it prints a version, go to step 2.
What it needs: macOS or Linux, Node.js 22 or 24, tmux, and Claude Code or Codex signed in. Check only what's missing:
```
node --version
```
,
```
tmux -V
```
,
```
claude auth status
```
or
```
codex login status
```
.
Install:
```
npm install -g @openrig/cli
```
, then
```
rig preflight
```
(Node, tmux, the daemon port and state folders) and
```
rig doctor
```
.
Then go on to step 2: say it's installed and ask what they want worked on, and in which repository. A plain "install OpenRig" includes this. Stop here only if they say not to start a team.
If something fails:
```
rig context get help
```
is the help guide for the installed version. If
```
rig
```
itself won't run, use https://www.openrig.dev/help/agents. Getting started: https://openrig.dev/docs/getting-started

先检查： 运行
```
rig --version
```
。如果输出版本号，直接进入步骤2。
系统要求： macOS或Linux系统、Node.js 22或24版本、tmux，以及已登录的Claude Code或Codex。仅检查缺失的依赖：
```
node --version
```
、
```
tmux -V
```
、
```
claude auth status
```
或
```
codex login status
```
。
安装： 运行
```
npm install -g @openrig/cli
```
，然后执行
```
rig preflight
```
（检查Node、tmux、守护进程端口和状态文件夹）和
```
rig doctor
```
。
随后进入步骤2： 告知用户安装完成，询问其想要处理的内容以及对应的代码仓库。即使用户仅说“安装OpenRig”，也包含这一步。仅当用户明确表示不启动团队时，在此停止。
如果出现故障：
```
rig context get help
```
是已安装版本的帮助指南。如果
```
rig
```
命令本身无法运行，请访问https://www.openrig.dev/help/agents 。入门指南：https://openrig.dev/docs/getting-started

2. Open OpenRig and give its operator the goal

2. 打开OpenRig并向operator下达目标

Start OpenRig:
```
rig daemon status
```
, and
```
rig daemon start
```
if it isn't running.
```
rig preflight
```
and
```
rig doctor
```
don't start it. Starting it also starts OpenRig's own team, the kernel, whose operator sets up the person's team. Keep it.
Show them OpenRig, the handoff: once OpenRig is running, open the OpenRig TUI and operator for the person. Say you're opening it, then run
```
rig terminal open saved:kernel --window
```
on the daemon's desktop. This is the next step after installing or starting OpenRig, and the way back whenever they want their agents or OpenRig again. Don't wait to be asked or for particular words. If they've said not now, give them that command for later. It opens a view itself, using herdr when installed or plain tmux otherwise:
- Inside Herdr (you run in a Herdr pane): it switches the person's Herdr to an
```
openrig kernel
```
  space, reusing a live one. No new window and no macOS prompt; their own spaces stay in the sidebar.
- In Terminal or Ghostty: a new tab or window the size of theirs.
- From Claude Desktop, iTerm or VS Code on a Mac: a new Ghostty window when supported, otherwise Terminal. Only here, tell the person before running it that Allow is fine if macOS asks to control that app.
```
echo $TERM_PROGRAM $__CFBundleIdentifier
```
  tells you where you run.
```
herdr
```
  ,
```
Apple_Terminal
```
  or
```
ghostty
```
  , or
```
tmux
```
  with
```
com.apple.Terminal
```
  or
```
com.mitchellh.ghostty
```
  , mean no macOS prompt, so don't mention one.
```
tmux
```
  with anything else (iTerm, VS Code) can prompt, so say Allow is fine first.
- Layout: under 120 columns the operator fills the first page; from 120, the dashboard and operator share it. The advisor has its own tab or tmux window.
Then tell the person in a sentence or two where it opened and that the operator is ready for what they want to build. Don't list agents or statuses (the TUI shows them), and don't suggest a command for them to type. Preserve the current terminal. If OpenRig's notes say it couldn't confirm the view, say so plainly. If it's already open, point them to it rather than opening another. Only if the window cannot open,
```
rig tui --shared
```
is the dashboard-only fallback; explain the failure and help with the chosen fallback. Herdr is visible only in a terminal the person can see; switching the shared TUI to
```
:terminals
```
does not open one. No and headless/SSH use are valid background outcomes. Provider-only
```
--provider herdr
```
or
```
--provider cmux
```
is for an existing provider workspace, not the first desktop window.
If the window can't open, or over headless SSH: say plainly that no visible terminal was opened, and ask the person to open a new terminal window or tab on the daemon's host. Over SSH, that's a new SSH session to it with the known account. If you only know an HTTP daemon address, ask for the SSH details rather than inventing them. Then give them one complete command:
- The command OpenRig printed: when
```
rig terminal open saved:kernel --window
```
  can't open a window, it says why and ends with
```
run:
```
  and a command (the
```
error
```
  field with
```
--json
```
  ). That command already names the installed herdr binary and the daemon's socket, or the conversation to attach. Relay it exactly rather than composing one. If a note asks you to place the view once Herdr starts, run that
```
rig terminal open
```
  yourself after they start it.
- If it printed no command: find
```
operator.agent
```
  in
```
rig ps --nodes --rig kernel --json
```
  , take its
```
canonicalSessionName
```
  (never a guessed name) and give
```
env -u TMUX tmux attach-session -t '=<canonicalSessionName>'
```
  for the operator's conversation.
For any other failure, the table under "What can interrupt installation and the OpenRig view" in
```
rig context get reference/getting-started.md#open-the-kernel-conversations
```
says why and what to do next.
Give the operator the goal: ask what they want worked on, in which repository and on which branch, unless they've said. Find the
```
operator.agent
```
row in
```
rig ps --nodes --rig kernel --json
```
, take its
```
canonicalSessionName
```
(never the logical ID or a guessed name) and send:
```
rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>. Branch: <branch>.'
```
Or the person types the goal and folder in the operator's pane. If they give you a goal later, forward it the same way. The operator helps them pick a team that fits their logins, starts it on their yes and gives the goal to the team's lead. Show them where the operator answers, and don't build the project yourself.
Relay the operator's questions: the operator asks in its own pane, and the person may not be looking there. After each step you hand it, read its screen with
```
rig capture <canonicalSessionName>
```
. When it asks the person something (start this team? which folder? which option?), ask them here in the operator's words and send their answer back with
```
rig send
```
, or tell them to answer in the operator's pane. Unlike a prompt or a menu, a question doesn't show up as a stopped seat, so don't leave it to a background wait.
Installation is finished when the operator is ready and the person is talking to it; a healthy daemon alone isn't that. If they'd rather talk later, keep that choice, leave them the exact connection step and say the handoff to the operator is still pending.
See what's running:
```
rig ps
```
, then
```
rig ps --nodes --rig <rig>
```
for a team's agents. If a team is already running in that repository, tell the operator.
Check it's ready before you say so:
```
rig ps --nodes --rig <rig>
```
. If an agent is stopped at a prompt or a menu, read it with
```
rig capture <seat>@<rig>
```
and answer with the key that screen shows (
```
rig send --help
```
says how to send a digit, a letter or Escape), or ask the person. Capture it again before sending anything more.
Join this session to the team, if that helps:
```
rig attach --self --rig <rigId> --pod <pod> --member <name> --runtime <claude-code|codex> --print-env
```
adds this session as a new member of a pod.
```
--node <logicalId>
```
binds it to an existing seat instead. Attach once, and keep the variables it prints (
```
OPENRIG_NODE_ID
```
and
```
OPENRIG_SESSION_NAME
```
). Each command may run in a fresh shell, so put them in front of every later
```
rig
```
command. Check with
```
rig whoami --json
```
.
Replies: other agents can't type into this session. Read work sent to you with
```
rig queue list --destination <your address>
```
and
```
rig queue show <id> --full
```
, and read an agent's screen with
```
rig capture <seat>@<rig>
```
.

启动OpenRig： 运行
```
rig daemon status
```
，如果未运行则执行
```
rig daemon start
```
。
```
rig preflight
```
和
```
rig doctor
```
不会启动守护进程。启动守护进程的同时会启动OpenRig自身的团队kernel，其operator负责搭建用户的团队。请保持守护进程运行。
向用户展示OpenRig（交接环节）： OpenRig运行后，为用户打开OpenRig TUI和operator。先告知用户你即将打开它，然后在守护进程的桌面环境中运行
```
rig terminal open saved:kernel --window
```
。这是安装或启动OpenRig后的下一步，也是用户后续想要访问代理或OpenRig时的返回方式。无需等待用户询问或特定指令。如果用户表示暂时不需要，将该命令提供给用户供后续使用。该命令会自行打开视图，若已安装herdr则使用herdr，否则使用原生tmux：
- Herdr内部（你在Herdr窗格中运行）：会将用户的Herdr切换到
```
openrig kernel
```
  空间，复用已有的运行中空间。不会打开新窗口，也不会触发macOS权限提示；用户自己的空间仍保留在侧边栏中。
- 在Terminal或Ghostty中： 打开一个与当前窗口大小一致的新标签页或窗口。
- 在Mac上的Claude Desktop、iTerm或VS Code中： 支持时会打开新的Ghostty窗口，否则打开Terminal。仅在这种情况下，运行前需告知用户：如果macOS请求控制该应用，点击“允许”即可。可通过
```
echo $TERM_PROGRAM $__CFBundleIdentifier
```
  查看当前运行环境。如果输出为
```
herdr
```
  、
```
Apple_Terminal
```
  或
```
ghostty
```
  ，或是
```
tmux
```
  搭配
```
com.apple.Terminal
```
  或
```
com.mitchellh.ghostty
```
  ，则不会触发macOS提示，无需提及。如果是
```
tmux
```
  搭配其他终端（iTerm、VS Code），则可能触发提示，需提前说明点击允许即可。
- 布局： 列数低于120时，operator占满首页；列数达到120及以上时，仪表盘和operator共享页面。advisor有独立的标签页或tmux窗口。

然后用一两句话告知用户窗口已打开的位置，以及operator已准备好接收其构建需求。不要列出代理或状态（TUI会显示），也不要建议用户输入命令。保留当前终端。如果OpenRig的提示显示无法确认视图打开状态，直接如实告知。如果已经打开，引导用户查看现有窗口，不要重复打开。仅当窗口无法打开时，

rig tui --shared

是仅仪表盘的降级方案；解释失败原因并协助使用所选的降级方案。Herdr仅在用户可见的终端中显示；将共享TUI切换到

:terminals

不会打开新终端。无界面/SSH场景下的后台运行是合理的结果。仅指定provider的

--provider herdr

或

--provider cmux

用于已有的provider工作区，而非首个桌面窗口。

如果窗口无法打开，或在无界面SSH环境中： 直接告知用户未打开可见终端，请用户在守护进程所在主机上打开新的终端窗口或标签页。在SSH场景下，就是使用已知账号新建一个SSH会话。如果你只知道HTTP守护进程地址，询问用户SSH详情，不要自行编造。然后向用户提供一条完整命令：
- OpenRig输出的命令： 当
```
rig terminal open saved:kernel --window
```
  无法打开窗口时，会说明原因，并在末尾给出
```
run:
```
  和一条命令（使用
```
--json
```
  时对应
```
error
```
  字段）。该命令已经包含了已安装的herdr二进制文件路径和守护进程的套接字，或是要附加的会话。直接原封不动转发该命令，不要自行拼接。如果提示要求在Herdr启动后放置视图，在用户启动Herdr后，你自行运行对应的
```
rig terminal open
```
  命令。
- 如果没有输出命令： 在
```
rig ps --nodes --rig kernel --json
```
  的输出中找到
```
operator.agent
```
  ，获取其
```
canonicalSessionName
```
  （绝对不要猜测名称），然后提供命令
```
env -u TMUX tmux attach-session -t '=<canonicalSessionName>'
```
  来接入operator的会话。

对于其他故障，可查看

rig context get reference/getting-started.md#open-the-kernel-conversations

中“哪些情况会中断安装和OpenRig视图打开”下方的表格，了解原因和后续处理方式。

向operator下达目标： 除非用户已经说明，否则询问用户想要处理的内容、对应的代码仓库和分支。在
```
rig ps --nodes --rig kernel --json
```
的输出中找到
```
operator.agent
```
行，获取其
```
canonicalSessionName
```
（绝对不要使用逻辑ID或猜测名称），然后发送：
```
rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>. Branch: <branch>.'
```
或者让用户在operator的窗格中输入目标和文件夹。如果用户之后才提供目标，用同样的方式转发。operator会帮助用户选择符合其登录状态的团队，经用户同意后启动团队，并将目标交给团队负责人。告知用户operator的回复位置，不要自行构建项目。
转发operator的问题： operator在自己的窗格中提问，用户可能没有查看。在你交接的每一步之后，用
```
rig capture <canonicalSessionName>
```
读取其屏幕内容。当operator向用户提问时（比如是否启动该团队？哪个文件夹？选哪个选项？），用operator的原话向用户提问，然后用
```
rig send
```
将用户的回复发回，或者告知用户直接在operator的窗格中回复。与提示或菜单不同，问题不会显示为已停止的席位，因此不要留待后台等待。
安装完成的标志是operator已就绪且用户正在与其对话；仅守护进程正常运行并不算完成。如果用户希望之后再沟通，尊重其选择，提供准确的连接步骤，并说明与operator的交接仍待完成。
查看运行状态： 运行
```
rig ps
```
，然后用
```
rig ps --nodes --rig <rig>
```
查看某个团队的代理。如果该仓库中已有团队在运行，告知operator。
在告知就绪前先检查： 运行
```
rig ps --nodes --rig <rig>
```
。如果某个代理停在提示或菜单处，用
```
rig capture <seat>@<rig>
```
读取内容，然后根据屏幕显示的按键回复（
```
rig send --help
```
说明了如何发送数字、字母或Escape键），或者询问用户。在发送更多内容前，再次捕获屏幕确认。
如有需要，将当前会话加入团队：
```
rig attach --self --rig <rigId> --pod <pod> --member <name> --runtime <claude-code|codex> --print-env
```
会将当前会话作为新成员加入pod。如果使用
```
--node <logicalId>
```
则会绑定到已有的席位。只需执行一次附加操作，保存输出的环境变量（
```
OPENRIG_NODE_ID
```
和
```
OPENRIG_SESSION_NAME
```
）。由于每个命令可能在新的shell中运行，因此后续所有
```
rig
```
命令前都要加上这些变量。可通过
```
rig whoami --json
```
检查状态。
回复处理： 其他代理无法在当前会话中输入。通过
```
rig queue list --destination <your address>
```
和
```
rig queue show <id> --full
```
读取发送给你的任务，用
```
rig capture <seat>@<rig>
```
读取代理的屏幕内容。

3. Follow the work to its result

3. 跟进工作直到产出结果

Find the team's task: the operator gives the goal to the team's lead as a queue task:
```
dev-build@starter
```
, or
```
orch-lead
```
in
```
workshop
```
and
```
factory
```
(for starter and factory,
```
rig specs preview <name> --kind rig
```
says what each seat does; for a running team,
```
rig ps --nodes --rig <rig>
```
). Find it with
```
rig queue list --destination <seat>@<rig> -a
```
.
Follow it to the result: a task that changed hands isn't finished.
```
rig queue show <id> --full
```
names the seat it went to, and that seat's next task is the one whose
```
handedOffFrom
```
is that ID (
```
rig queue list --destination <seat>@<rig> -a -o json
```
). Follow each handoff until an agent reports the result, and use
```
rig capture <seat>@<rig>
```
to see what it's doing. Then read what it produced and tell the person what the team actually did (the branch, commit, review or PR text), not just that you sent it.
Give the team more work: write the goal to a file: what to change, in which repository and branch, what done looks like, and that the result comes back to you (the branch or commit, the review, any PR text). Then
```
rig queue create --source <your name> --destination <seat>@<rig> --body-file <file>
```
, and tell that agent with
```
rig send <seat>@<rig> "task <id> is yours"
```
. A message informs, and a queue task is the work someone owns.
```
--source
```
names you when this session hasn't joined the team.
Then ask what's next. If no team can take the work, fix that or ask the person. Don't quietly do it yourself.
Other ways to work with the team:
```
rig send <seat>@<rig> "..."
```
types into an agent's terminal,
```
rig capture <seat>@<rig>
```
reads its screen, and
```
rig ps --nodes --rig <rig>
```
shows who's on it.

找到团队的任务： operator会将目标作为队列任务交给团队负责人：starter模式下是
```
dev-build@starter
```
，workshop和factory模式下是
```
orch-lead
```
（对于starter和factory模式，
```
rig specs preview <name> --kind rig
```
会说明每个席位的职责；对于运行中的团队，用
```
rig ps --nodes --rig <rig>
```
查看）。通过
```
rig queue list --destination <seat>@<rig> -a
```
查找任务。
跟进直到结果产出： 被转交的任务不算完成。
```
rig queue show <id> --full
```
会显示任务被转交到的席位，而该席位的下一个任务就是
```
handedOffFrom
```
字段为该ID的任务（通过
```
rig queue list --destination <seat>@<rig> -a -o json
```
查看）。跟进每一次转交，直到某个代理汇报结果，并用
```
rig capture <seat>@<rig>
```
查看其当前工作内容。然后读取产出内容，告知用户团队实际完成的工作（比如分支、提交、评审或PR文本），而不仅仅是说你已经发送了任务。
给团队分配更多工作： 将目标写入文件：包括要修改的内容、对应的代码仓库和分支、完成标准，以及结果需返回给你（包括分支或提交、评审、所有PR文本）。然后运行
```
rig queue create --source <your name> --destination <seat>@<rig> --body-file <file>
```
，并用
```
rig send <seat>@<rig> "task <id> is yours"
```
通知对应代理。消息仅作告知，队列任务才是某人负责的工作。如果当前会话未加入团队，用
```
--source
```
指定你的名称。
然后询问下一步需求。 如果没有团队能承接该工作，解决该问题或询问用户。不要悄悄自己完成。
与团队协作的其他方式：
```
rig send <seat>@<rig> "..."
```
向代理的终端输入内容，
```
rig capture <seat>@<rig>
```
读取其屏幕，
```
rig ps --nodes --rig <rig>
```
查看团队成员。

4. Find out more

4. 了解更多

How OpenRig works:

rig context profile world-public --situation fresh

What you can do:
```
rig context get onboarding-width
```
(the capability map).
Everything in the library:
```
rig context list
```
.
Exact syntax:
```
rig <command> --help
```
is always current for the installed version.

Written for OpenRig 0.6.7. When something here and

--help

disagree,

--help

wins.

OpenRig的工作原理： 运行

rig context profile world-public --situation fresh

。

你可以做什么： 运行
```
rig context get onboarding-width
```
（能力地图）。
库中的所有内容： 运行
```
rig context list
```
。
准确语法：
```
rig <command> --help
```
始终是已安装版本的最新参考。

本文档针对OpenRig 0.6.7编写。若此处内容与

--help

输出不一致，以

--help

为准。