team
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTeam Skill
团队技能
$team.omx/state/team/...omx team api ...This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.
$team.omx/state/team/...omx team api ...这个技能属于操作敏感类能力,请将其视为运维工作流,而非通用的提示词模式。
Team vs Native Subagents
团队模式 vs 原生子Agent
- Use Codex native subagents for bounded, in-session parallelism where one leader thread can fan out a few independent subtasks and wait for them directly.
- Use when you need durable tmux workers, shared task state, mailbox/dispatch coordination, worktrees, explicit lifecycle control, or long-running parallel execution that must survive beyond one local reasoning burst.
omx team - Native subagents can complement team/ralph execution, but they do not replace the tmux team runtime's stateful coordination contract.
- 如果你需要的是有边界的会话内并行能力,由单个主线程分发少量独立子任务并直接等待结果,使用Codex原生子Agent。
- 如果你需要持久化的tmux工作器、共享任务状态、邮箱/调度协调、工作树、显式生命周期控制,或是需要超出单次本地推理周期的长时间并行执行,使用****。
omx team - 原生子Agent可以和团队/ralph执行模式互补,但它们无法替代tmux团队运行时的有状态协调约定。
What This Skill Must Do
该技能必须实现的能力
GPT-5.4 Guidance Alignment
GPT-5.4 规范对齐
- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail.
- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the team workflow is grounded.
- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent.
When user triggers , the agent must:
$team- Invoke OMX runtime directly with
omx team ... - Avoid replacing the flow with in-process fanout
spawn_agent - Verify startup and surface concrete state/pane evidence
- Keep team state alive until workers are terminal (unless explicit abort)
- Handle cleanup and stale-pane recovery when needed
If is unavailable, stop with a hard error.
omx team- 默认输出简洁、证据充分的进度和完成报告,除非用户或风险等级要求提供更多细节。
- 新的用户任务更新视为当前工作流分支的本地覆盖,同时保留之前无冲突的约束条件。
- 如果正确性需要额外的检查、检索、执行或验证操作,请持续使用相关工具,直到团队工作流的上下文充分对齐。
- 自动执行清晰、低风险、可回滚的下一步操作;仅当下一步存在重大分支、破坏性操作或依赖用户偏好时,才需要询问用户。
当用户触发时,Agent必须:
$team- 直接调用OMX运行时执行命令
omx team ... - 不要用进程内的分发逻辑替换该流程
spawn_agent - 验证启动状态,展示具体的状态/窗格证据
- 保持团队状态存活,直到所有工作器进入终止状态(除非收到显式终止指令)
- 按需处理清理和 stale 窗格恢复工作
如果不可用,直接抛出硬错误终止流程。
omx teamInvocation Contract
调用约定
bash
omx team [N:agent-type] "<task description>"Examples:
bash
omx team 3:executor "analyze feature X and report flaws"
omx team "debug flaky integration tests"
omx team "ship end-to-end fix with verification"bash
omx team [N:agent-type] "<task description>"示例:
bash
omx team 3:executor "analyze feature X and report flaws"
omx team "debug flaky integration tests"
omx team "ship end-to-end fix with verification"Team-first launch contract
团队优先启动约定
omx team ...- Canonical launch: use plain /
omx team ...for coordinated workers.$team ... - Verification ownership: keep one lane focused on tests, regression coverage, and evidence before shutdown.
- Escalation: start a separate /
omx ralph ...only when a later manual follow-up still needs a persistent single-owner fix/verification loop.$ralph ... - Deprecation: has been removed. Use plain
omx team ralph ...for team execution or runomx team ...separately when you explicitly want a later Ralph loop.omx ralph ...
omx team ...- 标准启动: 直接使用/
omx team ...启动协同工作器。$team ... - 验证权责: 在关闭前保留一个通道专注于测试、回归覆盖和证据收集。
- 升级路径: 仅当后续需要手动跟进,需要持久的单责任人修复/验证循环时,才单独启动/
omx ralph ...。$ralph ... - 废弃说明: 已被移除。团队执行请直接使用
omx team ralph ...,如果明确需要后续Ralph循环,请单独运行omx team ...。omx ralph ...
Claude teammates (v0.6.0+)
Claude团队成员(v0.6.0+)
Important: (for example ) selects the worker role prompt, not the worker CLI ( vs ).
N:agent-type2:executorcodexclaudeTo launch Claude teammates, use the team worker CLI env vars:
bash
undefined重要提示:(例如)选择的是工作器角色提示词,而非工作器CLI(还是)。
N:agent-type2:executorcodexclaude要启动Claude团队成员,请使用团队工作器CLI环境变量:
bash
undefinedForce all teammates to Claude CLI
强制所有团队成员使用Claude CLI
OMX_TEAM_WORKER_CLI=claude omx team 2:executor "update docs and report"
OMX_TEAM_WORKER_CLI=claude omx team 2:executor "update docs and report"
Mixed team (worker 1 = Codex, worker 2 = Claude)
混合团队(工作器1 = Codex,工作器2 = Claude)
OMX_TEAM_WORKER_CLI_MAP=codex,claude omx team 2:executor "split doc/code tasks"
OMX_TEAM_WORKER_CLI_MAP=codex,claude omx team 2:executor "split doc/code tasks"
Auto mode: Claude is selected when worker launch args/model contains 'claude'
自动模式:当工作器启动参数/模型包含'claude'时自动选择Claude
OMX_TEAM_WORKER_CLI=auto OMX_TEAM_WORKER_LAUNCH_ARGS="--model claude-..." omx team 2:executor "run mixed validation"
undefinedOMX_TEAM_WORKER_CLI=auto OMX_TEAM_WORKER_LAUNCH_ARGS="--model claude-..." omx team 2:executor "run mixed validation"
undefinedPreconditions
前置条件
Before running , confirm:
$team- installed (
tmux)tmux -V - Current leader session is inside tmux (is set)
$TMUX - command resolves to the intended install/build
omx - If running repo-local , run
node bin/omx.js ...afternpm run buildchangessrc - Check HUD pane count in the leader window and avoid duplicate panes before split
hud --watch
Suggested preflight:
bash
tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || trueIf duplicates exist, remove extras before to prevent HUD ending up in worker stack.
omx team运行前,请确认:
$team- 已安装(执行
tmux验证)tmux -V - 当前主会话运行在tmux内部(环境变量已设置)
$TMUX - 命令指向预期的安装/构建版本
omx - 如果运行的是仓库本地的,修改
node bin/omx.js ...后请先执行srcnpm run build - 检查主窗口的HUD窗格数量,拆分前避免重复的窗格
hud --watch
建议的预检查命令:
bash
tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || true如果存在重复窗格,请先删除多余实例再执行,避免HUD出现在工作器栈中。
omx teamPre-context Intake Gate
上下文预摄入关卡
Before launching , require a grounded context snapshot:
omx team- Derive a task slug from the request.
- Reuse the latest relevant snapshot in when available.
.omx/context/{slug}-*.md - If none exists, create (UTC
.omx/context/{slug}-{timestamp}.md) with:YYYYMMDDTHHMMSSZ- task statement
- desired outcome
- known facts/evidence
- constraints
- unknowns/open questions
- likely codebase touchpoints
- If ambiguity remains high, run first for brownfield facts, then run
explorebefore team launch.$deep-interview --quick <task>
Do not start worker panes until this gate is satisfied; if forced to proceed quickly, state explicit scope/risk limitations in the launch report.
For simple read-only brownfield lookups during intake, follow active session guidance: when is enabled, prefer with narrow, concrete prompts; otherwise use the richer normal explore path and fall back normally if is unavailable.
USE_OMX_EXPLORE_CMDomx exploreomx explore启动前,需要获取对齐的上下文快照:
omx team- 从请求中生成任务slug。
- 如果存在的最新相关快照,直接复用。
.omx/context/{slug}-*.md - 如果不存在,创建(UTC时间格式
.omx/context/{slug}-{timestamp}.md),包含以下内容:YYYYMMDDTHHMMSSZ- 任务描述
- 预期结果
- 已知事实/证据
- 约束条件
- 未知项/待解决问题
- 可能涉及的代码库路径
- 如果歧义仍然很高,先运行获取存量项目信息,然后在团队启动前执行
explore。$deep-interview --quick <task>
在满足该关卡条件前不要启动工作器窗格;如果必须快速推进,请在启动报告中明确说明范围/风险限制。
对于预摄入过程中的简单只读存量项目查询,请遵循活跃会话指引:当启用时,优先使用带窄范围、具体提示词的;否则使用更丰富的常规探索路径,如果不可用则正常降级。
USE_OMX_EXPLORE_CMDomx exploreomx exploreFollow-up Staffing Contract
后续人员配置约定
When is used as a follow-up mode from ralplan, carry forward the approved plan's explicit available-agent-types roster and convert it into concrete staffing guidance before launch:
$team- keep worker-role choices inside the known roster
- state the recommended headcount and role counts
- state the suggested reasoning level for each lane when available
- explain why each lane exists (delivery, verification, specialist support)
- include an explicit launch hint (/
omx team N "<task>") for the coordinated team run; mention a later separate Ralph follow-up only when genuinely needed$team N "<task>" - if the ideal role is unavailable, choose the closest role from the roster and say so
当作为ralplan的后续模式使用时,需继承已审批计划的显式可用Agent类型名册,并在启动前转换为具体的人员配置指引:
$team- 工作器角色选择需在已知名册范围内
- 说明推荐的人员数量和角色配比
- 如有可用信息,说明每个通道的推荐推理级别
- 解释每个通道存在的原因(交付、验证、专家支持)
- 包含明确的启动提示(/
omx team N "<task>")用于协同团队运行;仅当确实需要时才提及后续单独的Ralph跟进$team N "<task>" - 如果理想角色不可用,从名册中选择最接近的角色并明确说明
Current Runtime Behavior (As Implemented)
当前运行时行为(已实现)
omx team- Parse args (,
N, task)agent-type - Sanitize team name from task text
- Initialize team state:
.omx/state/team/<team>/config.json.omx/state/team/<team>/manifest.v2.json.omx/state/team/<team>/tasks/task-<id>.json
- Compose team-scoped worker instructions file at:
.omx/state/team/<team>/worker-agents.md- Uses project content (if present) + worker overlay, without mutating project
AGENTS.mdAGENTS.md
- Resolve canonical shared state root from leader cwd ()
<leader-cwd>/.omx/state - Split current tmux window into worker panes
- Launch workers with:
OMX_TEAM_WORKER=<team>/worker-<n>OMX_TEAM_STATE_ROOT=<leader-cwd>/.omx/stateOMX_TEAM_LEADER_CWD=<leader-cwd>- worker CLI selected by /
OMX_TEAM_WORKER_CLI(OMX_TEAM_WORKER_CLI_MAPorcodex)claude - optional worktree metadata envs when is used
--worktree
- Wait for worker readiness (polling)
capture-pane - Write per-worker and trigger via
inbox.mdtmux send-keys - Return control to leader; follow-up uses /
status/resumeshutdown
Important:
- Leader remains in existing pane
- Worker panes are independent full Codex/Claude CLI sessions
- Workers may run in separate git worktrees () while sharing one team state root
omx team --worktree[=<name>] - Worker ACKs go to
mailbox/leader-fixed.json - Notify hook updates worker heartbeat and nudges leader during active team mode
- Submit routing uses this CLI resolution order per worker trigger:
- explicit worker CLI provided by runtime state (persisted on worker identity/config),
- entry for that worker index,
OMX_TEAM_WORKER_CLI_MAP - fallback / auto detection.
OMX_TEAM_WORKER_CLI
- Mixed CLI-map teams are supported for both startup and trigger submit behavior.
- Trigger submit differs by CLI:
- Codex may use queue-first on busy panes (strategy-dependent).
Tab - Claude always uses direct Enter-only () rounds (never queue-first
C-m).Tab
- Codex may use queue-first
omx team- 解析参数(、
N、任务)agent-type - 从任务文本中生成合规的团队名称
- 初始化团队状态:
.omx/state/team/<team>/config.json.omx/state/team/<team>/manifest.v2.json.omx/state/team/<team>/tasks/task-<id>.json
- 生成团队范围的工作器说明文件,路径为:
.omx/state/team/<team>/worker-agents.md- 使用项目的内容(如果存在)+ 工作器覆盖配置,不会修改项目的
AGENTS.md文件AGENTS.md
- 从主进程当前工作目录解析标准共享状态根路径()
<leader-cwd>/.omx/state - 将当前tmux窗口拆分为多个工作器窗格
- 启动工作器,传入以下参数:
OMX_TEAM_WORKER=<team>/worker-<n>OMX_TEAM_STATE_ROOT=<leader-cwd>/.omx/stateOMX_TEAM_LEADER_CWD=<leader-cwd>- 由/
OMX_TEAM_WORKER_CLI选择的工作器CLI(OMX_TEAM_WORKER_CLI_MAP或codex)claude - 使用时传入可选的工作树元数据环境变量
--worktree
- 等待工作器就绪(轮询)
capture-pane - 写入每个工作器的并通过
inbox.md触发执行tmux send-keys - 归还控制权给主进程;后续操作使用/
status/resume命令shutdown
重要说明:
- 主进程保留在现有窗格中
- 工作器窗格是独立的完整Codex/Claude CLI会话
- 工作器可以在独立的git工作树中运行(),同时共享同一个团队状态根路径
omx team --worktree[=<name>] - 工作器确认消息写入
mailbox/leader-fixed.json - 通知钩子会更新工作器心跳,并在活跃团队模式下提醒主进程
- 提交路由对每个工作器触发遵循以下CLI解析优先级:
- 运行时状态提供的显式工作器CLI(持久化在工作器身份/配置中),
- 对应工作器索引的条目,
OMX_TEAM_WORKER_CLI_MAP - 降级使用/ 自动检测。
OMX_TEAM_WORKER_CLI
- 混合CLI映射的团队同时支持启动和触发提交行为。
- 不同CLI的触发提交逻辑不同:
- Codex可能对繁忙窗格使用队列优先的键(取决于策略)。
Tab - Claude始终使用直接的仅回车()循环(从不使用队列优先的
C-m键)。Tab
- Codex可能对繁忙窗格使用队列优先的
Team worker model + thinking resolution (current contract)
团队工作器模型 + 推理级别解析(当前约定)
Team mode resolves worker model flags from one shared launch-arg set (not per-worker model selection).
Model precedence (highest to lowest):
- Explicit worker model in
OMX_TEAM_WORKER_LAUNCH_ARGS - Inherited leader flag
--model - Low-complexity default from (legacy alias:
OMX_DEFAULT_SPARK_MODEL) when 1+2 are absent and teamOMX_SPARK_MODELis low-complexityagentType
Default-model rule:
- Do not assume a frontier or spark model from recency or model-family heuristics.
- Use for frontier-default guidance.
OMX_DEFAULT_FRONTIER_MODEL - Use for spark/low-complexity worker-default guidance.
OMX_DEFAULT_SPARK_MODEL
Thinking-level rule (critical):
- No model-name heuristic mapping.
- Team runtime must not infer from model-name substrings (e.g.,
model_reasoning_effort,spark,high-capability).mini - When the leader assigns teammate roles/tasks, OMX allocates per-worker reasoning effort dynamically from the resolved worker role (,
low,medium).high - Explicit launch args still win: if already includes
OMX_TEAM_WORKER_LAUNCH_ARGS, that explicit value overrides dynamic allocation for every worker.-c model_reasoning_effort=...
Normalization requirements:
- Parse both and
--model <value>--model=<value> - Remove duplicate/conflicting model flags
- Emit exactly one final canonical flag:
--model <value> - Preserve unrelated args in worker launch config
- If explicit reasoning exists, preserve canonical ; otherwise inject the worker role's default reasoning level
-c model_reasoning_effort="<level>"
团队模式从一套共享的启动参数集解析工作器模型标志(不支持单工作器模型选择)。
模型优先级(从高到低):
- 中显式指定的工作器模型
OMX_TEAM_WORKER_LAUNCH_ARGS - 继承自主进程的标志
--model - 当1和2都不存在且团队为低复杂度时,使用
agentType(旧别名:OMX_DEFAULT_SPARK_MODEL)的低复杂度默认值OMX_SPARK_MODEL
默认模型规则:
- 不要根据使用时间或模型系列启发式假设使用前沿或spark模型。
- 前沿模型默认指引使用。
OMX_DEFAULT_FRONTIER_MODEL - spark/低复杂度工作器默认指引使用。
OMX_DEFAULT_SPARK_MODEL
推理级别规则(关键):
- 不做模型名称启发式映射。
- 团队运行时不能从模型名称子串(例如、
spark、high-capability)推断mini。model_reasoning_effort - 当主进程分配团队角色/任务时,OMX根据解析到的工作器角色(、
low、medium)动态分配每个工作器的推理开销。high - 显式启动参数优先级最高:如果已经包含
OMX_TEAM_WORKER_LAUNCH_ARGS,该显式值会覆盖所有工作器的动态分配值。-c model_reasoning_effort=...
标准化要求:
- 同时解析和
--model <value>两种格式--model=<value> - 删除重复/冲突的模型标志
- 输出唯一的最终标准标志:
--model <value> - 保留工作器启动配置中不相关的参数
- 如果存在显式推理级别配置,保留标准格式的;否则注入工作器角色的默认推理级别
-c model_reasoning_effort="<level>"
Required Lifecycle (Operator Contract)
要求的生命周期(运维约定)
Follow this exact lifecycle when running :
$team- Start team and verify startup evidence (team line, tmux target, panes, ACK mailbox)
- Monitor task and worker progress with runtime/state tools first (,
omx team status <team>, mailbox/state files)omx team resume <team> - Wait for terminal task state before shutdown:
pending=0in_progress=0- (or explicitly acknowledged failure path)
failed=0
- Only then run
omx team shutdown <team> - Verify shutdown evidence and state cleanup
Do not run while workers are actively writing updates unless user explicitly requested abort/cancel.
Do not treat ad-hoc pane typing as primary control flow when runtime/state evidence is available.
shutdown运行时请严格遵循以下生命周期:
$team- 启动团队并验证启动证据(团队行、tmux目标、窗格、ACK邮箱)
- 优先使用运行时/状态工具监控任务和工作器进度(、
omx team status <team>、邮箱/状态文件)omx team resume <team> - 关闭前等待任务进入终止状态:
pending=0in_progress=0- (或显式确认的失败路径)
failed=0
- 只有满足以上条件后才执行
omx team shutdown <team> - 验证关闭证据和状态清理结果
除非用户显式请求中止/取消,否则不要在工作器正在写入更新时运行。
当存在运行时/状态证据时,不要将临时的窗格输入视为主要控制流。
shutdownActive leader monitoring rule
活跃主进程监控规则
While a team is ON/running, the leader must not go blind. Keep checking live team state until terminal completion.
Minimum acceptable loop:
bash
sleep 30 && omx team status <team-name>Repeat that check while the team stays active, or use when event-driven waiting is a better fit.
omx team await <team-name> --timeout-ms 30000 --jsonIf the leader gets a stale/team-stalled nudge, immediately run before taking any manual intervention.
omx team status <team-name>当团队处于运行中状态时,主进程不能失去监控。请持续检查团队实时状态,直到任务最终完成。
最低可接受的循环:
bash
sleep 30 && omx team status <team-name>在团队保持活跃期间重复该检查,或者当事件驱动等待更合适时使用。
omx team await <team-name> --timeout-ms 30000 --json如果主进程收到stale/团队停滞提醒,请在进行任何人工干预前立即执行。
omx team status <team-name>Message Dispatch Policy (CLI-first, state-first)
消息分发策略(CLI优先、状态优先)
To avoid brittle behavior, message/task delivery must not be driven by ad-hoc tmux typing.
Required default path:
- Use runtime lifecycle commands for orchestration.
omx team ... - Use for mailbox/task mutations.
omx team api ... --json - Verify delivery via mailbox/state evidence (, task status,
mailbox/*.json).omx team status
Strict rules:
- MUST NOT use direct as the primary mechanism to deliver instructions/messages.
tmux send-keys - MUST NOT spam Enter/trigger keys without first checking runtime/state evidence.
- MUST prefer durable state writes + runtime dispatch (, mailbox, inbox).
dispatch/requests.json - Direct tmux interaction is fallback-only and only after failure checks (for example ) or explicit user request (for example “press enter”).
worker_notify_failed:<worker>
为避免不稳定行为,消息/任务交付不能依赖临时的tmux输入。
要求的默认路径:
- 使用运行时生命周期命令进行编排。
omx team ... - 使用进行邮箱/任务变更。
omx team api ... --json - 通过邮箱/状态证据验证交付结果(、任务状态、
mailbox/*.json)。omx team status
严格规则:
- 禁止使用直接的作为交付指令/消息的主要机制。
tmux send-keys - 禁止在未检查运行时/状态证据的情况下重复发送回车/触发键。
- 必须优先使用持久化状态写入 + 运行时分发(、邮箱、收件箱)。
dispatch/requests.json - 直接tmux交互仅作为降级方案,且仅在故障检查(例如)或用户显式请求(例如“按回车”)后使用。
worker_notify_failed:<worker>
Operational Commands
操作命令
bash
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>Semantics:
- : reads team snapshot (task counts, dead/non-reporting workers)
status - : reconnects to live team session if present
resume - : graceful shutdown request, then cleanup (deletes
shutdown).omx/state/team/<team>
bash
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>语义说明:
- :读取团队快照(任务计数、无响应/未上报的工作器)
status - :如果存在活跃的团队会话则重新连接
resume - :发送优雅关闭请求,然后清理资源(删除
shutdown).omx/state/team/<team>
Data Plane and Control Plane
数据平面和控制平面
Control Plane
控制平面
- tmux panes/processes (per worker)
OMX_TEAM_WORKER - leader notifications via
tmux display-message
- tmux窗格/进程(每个工作器对应变量)
OMX_TEAM_WORKER - 主进程通过发送通知
tmux display-message
Data Plane
数据平面
- files
.omx/state/team/<team>/... - Team mailbox files:
.omx/state/team/<team>/mailbox/leader-fixed.json.omx/state/team/<team>/mailbox/worker-<n>.json- (durable dispatch queue; hook-preferred, fallback-aware)
.omx/state/team/<team>/dispatch/requests.json
- 文件
.omx/state/team/<team>/... - 团队邮箱文件:
.omx/state/team/<team>/mailbox/leader-fixed.json.omx/state/team/<team>/mailbox/worker-<n>.json- (持久化分发队列;优先使用钩子,支持降级)
.omx/state/team/<team>/dispatch/requests.json
Key Files
关键文件
.omx/state/team/<team>/config.json.omx/state/team/<team>/manifest.v2.json.omx/state/team/<team>/tasks/task-<id>.json.omx/state/team/<team>/workers/worker-<n>/identity.json.omx/state/team/<team>/workers/worker-<n>/inbox.md.omx/state/team/<team>/workers/worker-<n>/heartbeat.json.omx/state/team/<team>/workers/worker-<n>/status.json.omx/state/team-leader-nudge.json
.omx/state/team/<team>/config.json.omx/state/team/<team>/manifest.v2.json.omx/state/team/<team>/tasks/task-<id>.json.omx/state/team/<team>/workers/worker-<n>/identity.json.omx/state/team/<team>/workers/worker-<n>/inbox.md.omx/state/team/<team>/workers/worker-<n>/heartbeat.json.omx/state/team/<team>/workers/worker-<n>/status.json.omx/state/team-leader-nudge.json
Team Mutation Interop (CLI-first)
团队变更互操作(CLI优先)
Use for machine-readable mutation/reads instead of legacy MCP tools.
omx team apiteam_*bash
omx team api <operation> --input '{"team_name":"my-team",...}' --jsonExamples:
bash
omx team api send-message --input '{"team_name":"my-team","from_worker":"worker-1","to_worker":"leader-fixed","body":"ACK"}' --json
omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json
omx team api transition-task-status --input '{"team_name":"my-team","task_id":"1","from":"in_progress","to":"completed","claim_token":"<token>"}' --json--jsonschema_versiontimestampcommandokoperation- or
dataerror
使用进行机器可读的变更/读取操作,替代旧的 MCP工具。
omx team apiteam_*bash
omx team api <operation> --input '{"team_name":"my-team",...}' --json示例:
bash
omx team api send-message --input '{"team_name":"my-team","from_worker":"worker-1","to_worker":"leader-fixed","body":"ACK"}' --json
omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json
omx team api transition-task-status --input '{"team_name":"my-team","task_id":"1","from":"in_progress","to":"completed","claim_token":"<token>"}' --json--jsonschema_versiontimestampcommandokoperation- 或
dataerror
Team + Worker Protocol Notes
团队 + 工作器协议说明
Leader-to-worker:
- Write full assignment to worker
inbox.md - Send short trigger (<200 chars) with
tmux send-keys
Worker-to-leader:
- Send ACK to mailbox via
leader-fixedomx team api send-message --json - Claim/transition/release task lifecycle via
omx team api <operation> --json
Worker commit protocol (critical for incremental integration):
- After completing task work and before reporting completion, workers MUST commit:
git add -A && git commit -m "task: <task-subject>" - This ensures changes are available for incremental integration into the leader branch
- If a worker forgets to commit, the runtime auto-commits as a fallback, but explicit commits are preferred
Task ID rule (critical):
- File path uses (example
task-<id>.json)task-1.json - MCP API uses bare id (example
task_id, not"1")"task-1" - Never instruct workers to read
tasks/{id}.json
主进程到工作器:
- 将完整任务写入工作器的
inbox.md - 通过发送短触发指令(<200字符)
tmux send-keys
工作器到主进程:
- 通过向
omx team api send-message --json邮箱发送确认消息leader-fixed - 通过认领/变更/释放任务生命周期
omx team api <operation> --json
工作器提交协议(增量集成的关键):
- 完成任务工作后、上报完成前,工作器必须提交变更:
git add -A && git commit -m "task: <task-subject>" - 这确保变更可用于增量集成到主分支
- 如果工作器忘记提交,运行时会作为降级方案自动提交,但优先使用显式提交
任务ID规则(关键):
- 文件路径使用(例如
task-<id>.json)task-1.json - MCP API的使用纯ID(例如
task_id,而非"1")"task-1" - 不要指示工作器读取
tasks/{id}.json
Environment Knobs
环境配置项
Useful runtime env vars:
OMX_TEAM_READY_TIMEOUT_MS- Worker readiness timeout (default 45000)
OMX_TEAM_SKIP_READY_WAIT=1- Skip readiness wait (debug only)
OMX_TEAM_AUTO_TRUST=0- Disable auto-advance for trust prompt (default behavior auto-advances)
OMX_TEAM_AUTO_ACCEPT_BYPASS=0- Disable Claude bypass-permissions prompt auto-accept (default behavior auto-accepts + Enter)
2
- Disable Claude bypass-permissions prompt auto-accept (default behavior auto-accepts
OMX_TEAM_WORKER_LAUNCH_ARGS- Extra args passed to worker launch command
OMX_TEAM_WORKER_CLI- Worker CLI selector: (default:
auto|codex|claude)auto - chooses
autowhen workerclaudecontains--model, otherwiseclaudecodex - In mode, workers launch with exactly one
claudeand ignore explicit model/config/effort launch overrides (uses default--dangerously-skip-permissions)settings.json
- Worker CLI selector:
OMX_TEAM_WORKER_CLI_MAP- Per-worker CLI selector (comma-separated )
auto|codex|claude - Length must be (broadcast) or exactly the team worker count
1 - Example:
OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude - When present, overrides
OMX_TEAM_WORKER_CLI
- Per-worker CLI selector (comma-separated
OMX_TEAM_AUTO_INTERRUPT_RETRY- Trigger submit fallback (default: enabled)
- disables adaptive queue->resend escalation
0
OMX_TEAM_LEADER_NUDGE_MS- Leader nudge interval in ms (default 120000)
OMX_TEAM_STRICT_SUBMIT=1- Force strict send-keys submit failure behavior
实用的运行时环境变量:
OMX_TEAM_READY_TIMEOUT_MS- 工作器就绪超时时间(默认45000)
OMX_TEAM_SKIP_READY_WAIT=1- 跳过就绪等待(仅用于调试)
OMX_TEAM_AUTO_TRUST=0- 禁用信任提示的自动前进(默认行为为自动前进)
OMX_TEAM_AUTO_ACCEPT_BYPASS=0- 禁用Claude绕过权限提示的自动接受(默认行为为自动接受+ 回车)
2
- 禁用Claude绕过权限提示的自动接受(默认行为为自动接受
OMX_TEAM_WORKER_LAUNCH_ARGS- 传递给工作器启动命令的额外参数
OMX_TEAM_WORKER_CLI- 工作器CLI选择器:(默认:
auto|codex|claude)auto - 模式下,当工作器
auto包含--model时选择claude,否则选择claudecodex - 在模式下,工作器启动时会携带唯一的
claude参数,忽略显式的模型/配置/推理开销启动覆盖(使用默认的--dangerously-skip-permissions)settings.json
- 工作器CLI选择器:
OMX_TEAM_WORKER_CLI_MAP- 单工作器CLI选择器(逗号分隔的列表)
auto|codex|claude - 长度必须为(广播)或与团队工作器数量完全一致
1 - 示例:
OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude - 存在时会覆盖配置
OMX_TEAM_WORKER_CLI
- 单工作器CLI选择器(逗号分隔的
OMX_TEAM_AUTO_INTERRUPT_RETRY- 触发提交降级方案(默认:启用)
- 会禁用自适应队列->重发升级逻辑
0
OMX_TEAM_LEADER_NUDGE_MS- 主进程提醒间隔(单位毫秒,默认120000)
OMX_TEAM_STRICT_SUBMIT=1- 强制严格的send-keys提交失败行为
Failure Modes and Diagnosis
故障模式和诊断
Operator note (important for Claude panes):
- Manual Enter injection () can appear to "do nothing" when a worker is actively processing; Enter may be queued by the pane/task flow.
tmux send-keys ... C-m - This is not necessarily a runtime bug. Confirm worker/team state before diagnosing dispatch failure.
- Avoid repeated blind Enter spam; it can create noisy duplicate submits once the pane becomes idle.
运维注意事项(Claude窗格的重要说明):
- 当工作器正在处理时,手动注入回车()可能看起来“无响应”;回车可能被窗格/任务流排队。
tmux send-keys ... C-m - 这不一定是运行时bug。在诊断分发故障前请先确认工作器/团队状态。
- 避免重复盲目发送回车;一旦窗格进入空闲状态,这可能会产生大量重复提交。
Safe Manual Intervention (last resort)
安全人工干预(最后手段)
Use only after checking and mailbox/state evidence:
omx team status <team>- Capture pane tail to confirm current worker state:
tmux capture-pane -t %<worker-pane> -p -S -120- If a larger-tail read or bounded summary would help, prefer explicit opt-in inspection via before improvising extra tmux commands.
omx sparkshell --tmux-pane %<worker-pane> --tail-lines 400
- If the pane is stuck in an interactive state, safely return to idle prompt first:
- optional interrupt or escape flow (CLI-specific) once, then re-check pane capture
C-c
- optional interrupt
- Send one concise trigger (single line) and wait for evidence:
tmux send-keys -t %<worker-pane> "ack + continue current task; report status" C-m
- Re-check:
- pane output via
capture-pane - mailbox updates (or worker mailbox)
mailbox/leader-fixed.json omx team status <team>
- pane output via
仅在检查和邮箱/状态证据后使用:
omx team status <team>- 捕获窗格尾部内容确认当前工作器状态:
tmux capture-pane -t %<worker-pane> -p -S -120- 如果需要读取更多尾部内容或有限摘要,在编写额外tmux命令前,优先通过进行显式选择检查。
omx sparkshell --tmux-pane %<worker-pane> --tail-lines 400
- 如果窗格卡在交互状态,先安全返回空闲提示符:
- 可选执行一次中断或退出流程(依CLI而定),然后重新检查窗格捕获内容
C-c
- 可选执行一次中断
- 发送一条简洁的触发指令(单行)并等待证据:
tmux send-keys -t %<worker-pane> "ack + continue current task; report status" C-m
- 重新检查:
- 通过查看窗格输出
capture-pane - 邮箱更新(或工作器邮箱)
mailbox/leader-fixed.json omx team status <team>
- 通过
worker_notify_failed:<worker>
worker_notify_failed:<worker>worker_notify_failed:<worker>
worker_notify_failed:<worker>Meaning:
- Leader wrote inbox but trigger submit path failed
Checks:
tmux list-panes -F '#{pane_id}\t#{pane_start_command}'tmux capture-pane -t %<worker-pane> -p -S -120- Verify worker process alive and not stuck on trust prompt
- Rebuild if running repo-local ()
npm run build
含义:
- 主进程已写入收件箱,但触发提交路径失败
检查项:
tmux list-panes -F '#{pane_id}\t#{pane_start_command}'tmux capture-pane -t %<worker-pane> -p -S -120- 验证工作器进程存活,未卡在信任提示界面
- 如果是本地仓库运行请重新构建()
npm run build
Team starts but leader gets no ACK
团队已启动但主进程未收到ACK
Checks:
- Worker pane capture shows inbox processing
- exists
.omx/state/team/<team>/mailbox/leader-fixed.json - Worker skill loaded and called
omx team api send-message --json - Task-id mismatch not blocking worker flow
检查项:
- 工作器窗格捕获内容显示正在处理收件箱
- 存在
.omx/state/team/<team>/mailbox/leader-fixed.json - 工作器技能已加载,且已调用
omx team api send-message --json - 任务ID不匹配未阻塞工作器流程
Worker logs omx team api ... ENOENT
(or legacy team_send_message ENOENT
/ team_update_task ENOENT
)
omx team api ... ENOENTteam_send_message ENOENTteam_update_task ENOENT工作器日志输出omx team api ... ENOENT
(或旧的team_send_message ENOENT
/ team_update_task ENOENT
)
omx team api ... ENOENTteam_send_message ENOENTteam_update_task ENOENTMeaning:
- Team state path no longer exists while worker is still running.
- Typical cause: leader/manual flow ran (or removed
omx team shutdown <team>) before worker finished..omx/state/team/<team>
Checks:
- and confirm whether tasks were still
omx team status <team>when shutdown occurredin_progress - Verify whether exists
.omx/state/team/<team>/ - Inspect worker pane tail for post-shutdown writes
- Confirm no external cleanup () happened during execution
rm -rf .omx/state/team/<team>
Prevention:
- Enforce completion gate (no in-progress tasks) before shutdown
- Use only for terminal completion or explicit abort
shutdown - If aborting, expect late worker writes to fail and treat ENOENT as expected teardown artifact
含义:
- 工作器仍在运行时团队状态路径已不存在。
- 典型原因:主进程/手动流程在工作器完成前执行了(或删除了
omx team shutdown <team>)。.omx/state/team/<team>
检查项:
- ,确认关闭时是否仍有
omx team status <team>状态的任务in_progress - 验证是否存在
.omx/state/team/<team>/ - 检查工作器窗格尾部内容是否有关闭后的写入操作
- 确认执行过程中没有外部清理操作()
rm -rf .omx/state/team/<team>
预防措施:
- 关闭前强制执行完成关卡(无进行中的任务)
- 仅在任务最终完成或显式中止时使用
shutdown - 如果执行中止,预期会有工作器写入失败,将ENOENT视为预期的销毁 artifacts
Shutdown reports success but stale worker panes remain
关闭报告成功但仍有残留的工作器窗格
Cause:
- stale pane outside config tracking or previous failed run
Fix:
- manual pane cleanup (see clean-slate commands)
原因:
- 配置跟踪外的残留窗格或之前的运行失败
修复方案:
- 手动清理窗格(参见从零恢复命令)
Clean-Slate Recovery
从零恢复
Run from leader pane:
bash
undefined在主进程窗格中执行:
bash
undefined1) Inspect panes
1) 检查窗格
tmux list-panes -F '#{pane_id}\t#{pane_current_command}\t#{pane_start_command}'
tmux list-panes -F '#{pane_id}\t#{pane_current_command}\t#{pane_start_command}'
2) Kill stale worker panes only (examples)
2) 仅杀死残留的工作器窗格(示例)
tmux kill-pane -t %450
tmux kill-pane -t %451
tmux kill-pane -t %450
tmux kill-pane -t %451
3) Remove stale team state (example)
3) 删除残留的团队状态(示例)
rm -rf .omx/state/team/<team-name>
rm -rf .omx/state/team/<team-name>
4) Retry
4) 重试
omx team 1:executor "fresh retry"
Guidelines:
- Do not kill leader pane
- Do not kill HUD pane (`omx hud --watch`) unless intentionally restarting HUDomx team 1:executor "fresh retry"
指引:
- 不要杀死主进程窗格
- 不要杀死HUD窗格(`omx hud --watch`),除非你有意重启HUDRequired Reporting During Execution
执行期间的报告要求
When operating this skill, provide concrete progress evidence:
- Team started line ()
Team started: <name> - tmux target and worker pane presence
- leader mailbox ACK path/content check
- status/shutdown outcomes
Do not claim success without file/pane evidence.
Do not claim clean completion if shutdown occurred with .
Use as an explicit opt-in operator aid for pane inspection and summaries; keep raw evidence available for manual intervention and proof.
in_progress>0omx sparkshell --tmux-pane ...tmux capture-pane操作该技能时,请提供具体的进度证据:
- 团队启动行()
Team started: <name> - tmux目标和工作器窗格存在性
- 主进程邮箱ACK路径/内容检查结果
- 状态/关闭结果
没有文件/窗格证据不要声称成功。
如果关闭时不要声称完全完成。
使用作为显式选择的运维辅助工具进行窗格检查和摘要;保留原始证据用于人工干预和证明。
in_progress>0omx sparkshell --tmux-pane ...tmux capture-paneMCP Job Lifecycle Tools
MCP任务生命周期工具
For programmatic or agent-driven team spawning (as opposed to interactive CLI use), OMX exposes four MCP tools via the :
team-server| Tool | Description |
|---|---|
| Spawn tmux CLI workers in the background; returns a |
| Non-blocking status check for a running job |
| Block until the job completes, with automatic idle-pane nudging |
| Kill worker tmux panes for a job (early stop only) |
对于程序化或Agent驱动的团队启动(与交互式CLI使用相对),OMX通过暴露四个MCP工具:
team-server| 工具 | 描述 |
|---|---|
| 在后台启动tmux CLI工作器;立即返回 |
| 对运行中的任务进行非阻塞状态检查 |
| 阻塞直到任务完成,自动提醒空闲窗格 |
| 杀死任务的tmux工作器窗格(仅用于提前停止) |
CLI vs MCP Tools
CLI vs MCP工具
- CLI — Primary method for interactive team orchestration. Use this when you are operating inside a live tmux session and want direct pane visibility.
omx team ... - MCP tools — For programmatic or agent-driven team spawning (analogous to OMC's
omx_run_team_*tools). Use these when an agent needs to launch workers, poll status, and collect results without manual intervention.omc_run_team_*
- CLI — 交互式团队编排的主要方法。当你在活跃的tmux会话中操作,需要直接的窗格可见性时使用。
omx team ... - MCP工具 — 用于程序化或Agent驱动的团队启动(类似于OMC的
omx_run_team_*工具)。当Agent需要启动工作器、轮询状态、收集结果而无需人工干预时使用。omc_run_team_*
Naming Distinction
命名区分
Two cleanup tools exist and must not be confused:
- (state-server): Deletes team state files on disk (
team_cleanup). Use after a team run is fully complete..omx/state/team/<team>/ - (team-server): Kills tmux worker panes for a job. Use only when stopping workers early; otherwise
omx_run_team_cleanuphandles natural termination.omx_run_team_wait
存在两个清理工具,请勿混淆:
- (状态服务器):删除磁盘上的团队状态文件(
team_cleanup)。在团队运行完全完成后使用。.omx/state/team/<team>/ - (团队服务器):杀死任务的tmux工作器窗格。仅在提前停止工作器时使用;否则
omx_run_team_cleanup会处理自然终止。omx_run_team_wait
Basic Usage Example
基础使用示例
1. omx_run_team_start({
teamName: "fix-bugs",
agentTypes: ["codex"],
tasks: [{ subject: "Fix bug", description: "..." }],
cwd: "/path/to/project"
})
→ Returns { jobId: "omx-abc123" }
2. omx_run_team_wait({ job_id: "omx-abc123", timeout_ms: 300000 })
→ Blocks until done, auto-nudges idle panes
3. omx_run_team_cleanup({ job_id: "omx-abc123" })
→ Only needed if stopping workers earlyomx_run_team_status1. omx_run_team_start({
teamName: "fix-bugs",
agentTypes: ["codex"],
tasks: [{ subject: "Fix bug", description: "..." }],
cwd: "/path/to/project"
})
→ 返回 { jobId: "omx-abc123" }
2. omx_run_team_wait({ job_id: "omx-abc123", timeout_ms: 300000 })
→ 阻塞直到完成,自动提醒空闲窗格
3. omx_run_team_cleanup({ job_id: "omx-abc123" })
→ 仅在提前停止工作器时需要如果需要在工作器运行时并行处理其他工作,可以在步骤1和2之间调用进行非阻塞轮询。
omx_run_team_statusLimitations
限制
- Worktree provisioning requires a git repository and can fail on branch/path collisions
- send-keys interactions can be timing-sensitive under load
- stale panes from prior runs can interfere until manually cleaned
- 工作树配置需要git仓库,分支/路径冲突时可能失败
- 高负载下send-keys交互可能存在时序敏感问题
- 之前运行残留的窗格可能会造成干扰,需要手动清理
Scenario Examples
场景示例
Good: The user says after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
continueGood: The user changes only the output shape or downstream delivery step (for example ). Preserve earlier non-conflicting workflow constraints and apply the update locally.
make a PRBad: The user says , and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
continue正确: 工作流已经有明确的下一步时用户说。继续当前分支的工作,而不是重启或重复询问相同问题。
continue正确: 用户仅修改输出格式或下游交付步骤(例如)。保留之前无冲突的工作流约束,本地应用更新。
make a PR错误: 用户说,工作流却重启发现流程,或者在收集缺失的验证/证据前停止。
continue