team

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Team Skill

团队技能

$team
is the tmux-based parallel execution mode for OMX. It starts real worker Codex and/or Claude CLI sessions in split panes and coordinates them through
.omx/state/team/...
files plus CLI team interop (
omx team api ...
) and state files.
This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.
$team
是OMX基于tmux的并行执行模式。它会在拆分窗格中启动真实的工作器Codex和/或Claude CLI会话,并通过
.omx/state/team/...
文件、CLI团队互操作能力(
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
    omx team
    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.
  • 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
$team
, the agent must:
  1. Invoke OMX runtime directly with
    omx team ...
  2. Avoid replacing the flow with in-process
    spawn_agent
    fanout
  3. Verify startup and surface concrete state/pane evidence
  4. Keep team state alive until workers are terminal (unless explicit abort)
  5. Handle cleanup and stale-pane recovery when needed
If
omx team
is unavailable, stop with a hard error.
  • 默认输出简洁、证据充分的进度和完成报告,除非用户或风险等级要求提供更多细节。
  • 新的用户任务更新视为当前工作流分支的本地覆盖,同时保留之前无冲突的约束条件。
  • 如果正确性需要额外的检查、检索、执行或验证操作,请持续使用相关工具,直到团队工作流的上下文充分对齐。
  • 自动执行清晰、低风险、可回滚的下一步操作;仅当下一步存在重大分支、破坏性操作或依赖用户偏好时,才需要询问用户。
当用户触发
$team
时,Agent必须:
  1. 直接调用OMX运行时执行
    omx team ...
    命令
  2. 不要用进程内的
    spawn_agent
    分发逻辑替换该流程
  3. 验证启动状态,展示具体的状态/窗格证据
  4. 保持团队状态存活,直到所有工作器进入终止状态(除非收到显式终止指令)
  5. 按需处理清理和 stale 窗格恢复工作
如果
omx team
不可用,直接抛出硬错误终止流程。

Invocation 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 ...
is now the canonical launch path for coordinated execution. Team mode should carry its own parallel delivery + verification lanes without requiring a separate linked Ralph launch up front.
  • Canonical launch: use plain
    omx team ...
    /
    $team ...
    for coordinated workers.
  • Verification ownership: keep one lane focused on tests, regression coverage, and evidence before shutdown.
  • Escalation: start a separate
    omx ralph ...
    /
    $ralph ...
    only when a later manual follow-up still needs a persistent single-owner fix/verification loop.
  • Deprecation:
    omx team ralph ...
    has been removed. Use plain
    omx team ...
    for team execution or run
    omx ralph ...
    separately when you explicitly want a later Ralph loop.
omx team ...
现在是协同执行的标准启动路径。团队模式自带并行交付+验证通道,不需要预先单独启动关联的Ralph实例。
  • 标准启动: 直接使用
    omx team ...
    /
    $team ...
    启动协同工作器。
  • 验证权责: 在关闭前保留一个通道专注于测试、回归覆盖和证据收集。
  • 升级路径: 仅当后续需要手动跟进,需要持久的单责任人修复/验证循环时,才单独启动
    omx ralph ...
    /
    $ralph ...
  • 废弃说明:
    omx team ralph ...
    已被移除。团队执行请直接使用
    omx team ...
    ,如果明确需要后续Ralph循环,请单独运行
    omx ralph ...

Claude teammates (v0.6.0+)

Claude团队成员(v0.6.0+)

Important:
N:agent-type
(for example
2:executor
) selects the worker role prompt, not the worker CLI (
codex
vs
claude
).
To launch Claude teammates, use the team worker CLI env vars:
bash
undefined
重要提示:
N:agent-type
(例如
2:executor
)选择的是工作器角色提示词,而非工作器CLI(
codex
还是
claude
)。
要启动Claude团队成员,请使用团队工作器CLI环境变量:
bash
undefined

Force 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"
undefined
OMX_TEAM_WORKER_CLI=auto OMX_TEAM_WORKER_LAUNCH_ARGS="--model claude-..." omx team 2:executor "run mixed validation"
undefined

Preconditions

前置条件

Before running
$team
, confirm:
  1. tmux
    installed (
    tmux -V
    )
  2. Current leader session is inside tmux (
    $TMUX
    is set)
  3. omx
    command resolves to the intended install/build
  4. If running repo-local
    node bin/omx.js ...
    , run
    npm run build
    after
    src
    changes
  5. Check HUD pane count in the leader window and avoid duplicate
    hud --watch
    panes before split
Suggested preflight:
bash
tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || true
If duplicates exist, remove extras before
omx team
to prevent HUD ending up in worker stack.
运行
$team
前,请确认:
  1. 已安装
    tmux
    (执行
    tmux -V
    验证)
  2. 当前主会话运行在tmux内部(
    $TMUX
    环境变量已设置)
  3. omx
    命令指向预期的安装/构建版本
  4. 如果运行的是仓库本地的
    node bin/omx.js ...
    ,修改
    src
    后请先执行
    npm run build
  5. 检查主窗口的HUD窗格数量,拆分前避免重复的
    hud --watch
    窗格
建议的预检查命令:
bash
tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || true
如果存在重复窗格,请先删除多余实例再执行
omx team
,避免HUD出现在工作器栈中。

Pre-context Intake Gate

上下文预摄入关卡

Before launching
omx team
, require a grounded context snapshot:
  1. Derive a task slug from the request.
  2. Reuse the latest relevant snapshot in
    .omx/context/{slug}-*.md
    when available.
  3. If none exists, create
    .omx/context/{slug}-{timestamp}.md
    (UTC
    YYYYMMDDTHHMMSSZ
    ) with:
    • task statement
    • desired outcome
    • known facts/evidence
    • constraints
    • unknowns/open questions
    • likely codebase touchpoints
  4. If ambiguity remains high, run
    explore
    first for brownfield facts, then run
    $deep-interview --quick <task>
    before team launch.
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
USE_OMX_EXPLORE_CMD
is enabled, prefer
omx explore
with narrow, concrete prompts; otherwise use the richer normal explore path and fall back normally if
omx explore
is unavailable.
启动
omx team
前,需要获取对齐的上下文快照:
  1. 从请求中生成任务slug。
  2. 如果存在
    .omx/context/{slug}-*.md
    的最新相关快照,直接复用。
  3. 如果不存在,创建
    .omx/context/{slug}-{timestamp}.md
    (UTC时间格式
    YYYYMMDDTHHMMSSZ
    ),包含以下内容:
    • 任务描述
    • 预期结果
    • 已知事实/证据
    • 约束条件
    • 未知项/待解决问题
    • 可能涉及的代码库路径
  4. 如果歧义仍然很高,先运行
    explore
    获取存量项目信息,然后在团队启动前执行
    $deep-interview --quick <task>
在满足该关卡条件前不要启动工作器窗格;如果必须快速推进,请在启动报告中明确说明范围/风险限制。
对于预摄入过程中的简单只读存量项目查询,请遵循活跃会话指引:当启用
USE_OMX_EXPLORE_CMD
时,优先使用带窄范围、具体提示词的
omx explore
;否则使用更丰富的常规探索路径,如果
omx explore
不可用则正常降级。

Follow-up Staffing Contract

后续人员配置约定

When
$team
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:
  • 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>"
    /
    $team N "<task>"
    ) for the coordinated team run; mention a later separate Ralph follow-up only when genuinely needed
  • if the ideal role is unavailable, choose the closest role from the roster and say so
$team
作为ralplan的后续模式使用时,需继承已审批计划的显式可用Agent类型名册,并在启动前转换为具体的人员配置指引:
  • 工作器角色选择需在已知名册范围内
  • 说明推荐的人员数量和角色配比
  • 如有可用信息,说明每个通道的推荐推理级别
  • 解释每个通道存在的原因(交付、验证、专家支持)
  • 包含明确的启动提示(
    omx team N "<task>"
    /
    $team N "<task>"
    )用于协同团队运行;仅当确实需要时才提及后续单独的Ralph跟进
  • 如果理想角色不可用,从名册中选择最接近的角色并明确说明

Current Runtime Behavior (As Implemented)

当前运行时行为(已实现)

omx team
currently performs:
  1. Parse args (
    N
    ,
    agent-type
    , task)
  2. Sanitize team name from task text
  3. Initialize team state:
    • .omx/state/team/<team>/config.json
    • .omx/state/team/<team>/manifest.v2.json
    • .omx/state/team/<team>/tasks/task-<id>.json
  4. Compose team-scoped worker instructions file at:
    • .omx/state/team/<team>/worker-agents.md
    • Uses project
      AGENTS.md
      content (if present) + worker overlay, without mutating project
      AGENTS.md
  5. Resolve canonical shared state root from leader cwd (
    <leader-cwd>/.omx/state
    )
  6. Split current tmux window into worker panes
  7. Launch workers with:
    • OMX_TEAM_WORKER=<team>/worker-<n>
    • OMX_TEAM_STATE_ROOT=<leader-cwd>/.omx/state
    • OMX_TEAM_LEADER_CWD=<leader-cwd>
    • worker CLI selected by
      OMX_TEAM_WORKER_CLI
      /
      OMX_TEAM_WORKER_CLI_MAP
      (
      codex
      or
      claude
      )
    • optional worktree metadata envs when
      --worktree
      is used
  8. Wait for worker readiness (
    capture-pane
    polling)
  9. Write per-worker
    inbox.md
    and trigger via
    tmux send-keys
  10. Return control to leader; follow-up uses
    status
    /
    resume
    /
    shutdown
Important:
  • Leader remains in existing pane
  • Worker panes are independent full Codex/Claude CLI sessions
  • Workers may run in separate git worktrees (
    omx team --worktree[=<name>]
    ) while sharing one team state root
  • 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:
    1. explicit worker CLI provided by runtime state (persisted on worker identity/config),
    2. OMX_TEAM_WORKER_CLI_MAP
      entry for that worker index,
    3. fallback
      OMX_TEAM_WORKER_CLI
      / auto detection.
  • Mixed CLI-map teams are supported for both startup and trigger submit behavior.
  • Trigger submit differs by CLI:
    • Codex may use queue-first
      Tab
      on busy panes (strategy-dependent).
    • Claude always uses direct Enter-only (
      C-m
      ) rounds (never queue-first
      Tab
      ).
omx team
当前执行以下流程:
  1. 解析参数(
    N
    agent-type
    、任务)
  2. 从任务文本中生成合规的团队名称
  3. 初始化团队状态:
    • .omx/state/team/<team>/config.json
    • .omx/state/team/<team>/manifest.v2.json
    • .omx/state/team/<team>/tasks/task-<id>.json
  4. 生成团队范围的工作器说明文件,路径为:
    • .omx/state/team/<team>/worker-agents.md
    • 使用项目的
      AGENTS.md
      内容(如果存在)+ 工作器覆盖配置,不会修改项目的
      AGENTS.md
      文件
  5. 从主进程当前工作目录解析标准共享状态根路径(
    <leader-cwd>/.omx/state
  6. 将当前tmux窗口拆分为多个工作器窗格
  7. 启动工作器,传入以下参数:
    • OMX_TEAM_WORKER=<team>/worker-<n>
    • OMX_TEAM_STATE_ROOT=<leader-cwd>/.omx/state
    • OMX_TEAM_LEADER_CWD=<leader-cwd>
    • OMX_TEAM_WORKER_CLI
      /
      OMX_TEAM_WORKER_CLI_MAP
      选择的工作器CLI(
      codex
      claude
    • 使用
      --worktree
      时传入可选的工作树元数据环境变量
  8. 等待工作器就绪(轮询
    capture-pane
  9. 写入每个工作器的
    inbox.md
    并通过
    tmux send-keys
    触发执行
  10. 归还控制权给主进程;后续操作使用
    status
    /
    resume
    /
    shutdown
    命令
重要说明:
  • 主进程保留在现有窗格中
  • 工作器窗格是独立的完整Codex/Claude CLI会话
  • 工作器可以在独立的git工作树中运行(
    omx team --worktree[=<name>]
    ),同时共享同一个团队状态根路径
  • 工作器确认消息写入
    mailbox/leader-fixed.json
  • 通知钩子会更新工作器心跳,并在活跃团队模式下提醒主进程
  • 提交路由对每个工作器触发遵循以下CLI解析优先级:
    1. 运行时状态提供的显式工作器CLI(持久化在工作器身份/配置中),
    2. 对应工作器索引的
      OMX_TEAM_WORKER_CLI_MAP
      条目,
    3. 降级使用
      OMX_TEAM_WORKER_CLI
      / 自动检测。
  • 混合CLI映射的团队同时支持启动和触发提交行为。
  • 不同CLI的触发提交逻辑不同:
    • Codex可能对繁忙窗格使用队列优先的
      Tab
      键(取决于策略)。
    • Claude始终使用直接的仅回车(
      C-m
      )循环(从不使用队列优先的
      Tab
      键)。

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):
  1. Explicit worker model in
    OMX_TEAM_WORKER_LAUNCH_ARGS
  2. Inherited leader
    --model
    flag
  3. Low-complexity default from
    OMX_DEFAULT_SPARK_MODEL
    (legacy alias:
    OMX_SPARK_MODEL
    ) when 1+2 are absent and team
    agentType
    is low-complexity
Default-model rule:
  • Do not assume a frontier or spark model from recency or model-family heuristics.
  • Use
    OMX_DEFAULT_FRONTIER_MODEL
    for frontier-default guidance.
  • Use
    OMX_DEFAULT_SPARK_MODEL
    for spark/low-complexity worker-default guidance.
Thinking-level rule (critical):
  • No model-name heuristic mapping.
  • Team runtime must not infer
    model_reasoning_effort
    from model-name substrings (e.g.,
    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
    OMX_TEAM_WORKER_LAUNCH_ARGS
    already includes
    -c model_reasoning_effort=...
    , that explicit value overrides dynamic allocation for every worker.
Normalization requirements:
  • Parse both
    --model <value>
    and
    --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
    -c model_reasoning_effort="<level>"
    ; otherwise inject the worker role's default reasoning level
团队模式从一套共享的启动参数集解析工作器模型标志(不支持单工作器模型选择)。
模型优先级(从高到低):
  1. OMX_TEAM_WORKER_LAUNCH_ARGS
    中显式指定的工作器模型
  2. 继承自主进程的
    --model
    标志
  3. 当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
:
  1. Start team and verify startup evidence (team line, tmux target, panes, ACK mailbox)
  2. Monitor task and worker progress with runtime/state tools first (
    omx team status <team>
    ,
    omx team resume <team>
    , mailbox/state files)
  3. Wait for terminal task state before shutdown:
    • pending=0
    • in_progress=0
    • failed=0
      (or explicitly acknowledged failure path)
  4. Only then run
    omx team shutdown <team>
  5. Verify shutdown evidence and state cleanup
Do not run
shutdown
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.
运行
$team
时请严格遵循以下生命周期:
  1. 启动团队并验证启动证据(团队行、tmux目标、窗格、ACK邮箱)
  2. 优先使用运行时/状态工具监控任务和工作器进度(
    omx team status <team>
    omx team resume <team>
    、邮箱/状态文件)
  3. 关闭前等待任务进入终止状态:
    • pending=0
    • in_progress=0
    • failed=0
      (或显式确认的失败路径)
  4. 只有满足以上条件后才执行
    omx team shutdown <team>
  5. 验证关闭证据和状态清理结果
除非用户显式请求中止/取消,否则不要在工作器正在写入更新时运行
shutdown
。 当存在运行时/状态证据时,不要将临时的窗格输入视为主要控制流。

Active 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
omx team await <team-name> --timeout-ms 30000 --json
when event-driven waiting is a better fit.
If the leader gets a stale/team-stalled nudge, immediately run
omx team status <team-name>
before taking any manual intervention.
当团队处于运行中状态时,主进程不能失去监控。请持续检查团队实时状态,直到任务最终完成。
最低可接受的循环:
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:
  1. Use
    omx team ...
    runtime lifecycle commands for orchestration.
  2. Use
    omx team api ... --json
    for mailbox/task mutations.
  3. Verify delivery via mailbox/state evidence (
    mailbox/*.json
    , task status,
    omx team status
    ).
Strict rules:
  • MUST NOT use direct
    tmux send-keys
    as the primary mechanism to deliver instructions/messages.
  • MUST NOT spam Enter/trigger keys without first checking runtime/state evidence.
  • MUST prefer durable state writes + runtime dispatch (
    dispatch/requests.json
    , mailbox, inbox).
  • Direct tmux interaction is fallback-only and only after failure checks (for example
    worker_notify_failed:<worker>
    ) or explicit user request (for example “press enter”).
为避免不稳定行为,消息/任务交付不能依赖临时的tmux输入
要求的默认路径:
  1. 使用
    omx team ...
    运行时生命周期命令进行编排。
  2. 使用
    omx team api ... --json
    进行邮箱/任务变更。
  3. 通过邮箱/状态证据验证交付结果(
    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:
  • status
    : reads team snapshot (task counts, dead/non-reporting workers)
  • resume
    : reconnects to live team session if present
  • shutdown
    : graceful shutdown request, then cleanup (deletes
    .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 (
    OMX_TEAM_WORKER
    per worker)
  • leader notifications via
    tmux display-message
  • tmux窗格/进程(每个工作器对应
    OMX_TEAM_WORKER
    变量)
  • 主进程通过
    tmux display-message
    发送通知

Data Plane

数据平面

  • .omx/state/team/<team>/...
    files
  • Team mailbox files:
  • .omx/state/team/<team>/mailbox/leader-fixed.json
  • .omx/state/team/<team>/mailbox/worker-<n>.json
  • .omx/state/team/<team>/dispatch/requests.json
    (durable dispatch queue; hook-preferred, fallback-aware)
  • .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
omx team api
for machine-readable mutation/reads instead of legacy
team_*
MCP tools.
bash
omx team api <operation> --input '{"team_name":"my-team",...}' --json
Examples:
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
--json
responses include stable metadata for automation:
  • schema_version
  • timestamp
  • command
  • ok
  • operation
  • data
    or
    error
使用
omx team api
进行机器可读的变更/读取操作,替代旧的
team_*
MCP工具。
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
--json
响应包含用于自动化的稳定元数据:
  • schema_version
  • timestamp
  • command
  • ok
  • operation
  • data
    error

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
    leader-fixed
    mailbox via
    omx 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
    task-<id>.json
    (example
    task-1.json
    )
  • MCP API
    task_id
    uses bare id (example
    "1"
    , not
    "task-1"
    )
  • Never instruct workers to read
    tasks/{id}.json
主进程到工作器:
  • 将完整任务写入工作器的
    inbox.md
  • 通过
    tmux send-keys
    发送短触发指令(<200字符)
工作器到主进程:
  • 通过
    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的
    task_id
    使用纯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
      2
      + Enter)
  • OMX_TEAM_WORKER_LAUNCH_ARGS
    • Extra args passed to worker launch command
  • OMX_TEAM_WORKER_CLI
    • Worker CLI selector:
      auto|codex|claude
      (default:
      auto
      )
    • auto
      chooses
      claude
      when worker
      --model
      contains
      claude
      , otherwise
      codex
    • In
      claude
      mode, workers launch with exactly one
      --dangerously-skip-permissions
      and ignore explicit model/config/effort launch overrides (uses default
      settings.json
      )
  • OMX_TEAM_WORKER_CLI_MAP
    • Per-worker CLI selector (comma-separated
      auto|codex|claude
      )
    • Length must be
      1
      (broadcast) or exactly the team worker count
    • Example:
      OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude
    • When present, overrides
      OMX_TEAM_WORKER_CLI
  • OMX_TEAM_AUTO_INTERRUPT_RETRY
    • Trigger submit fallback (default: enabled)
    • 0
      disables adaptive queue->resend escalation
  • 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
      + 回车)
  • OMX_TEAM_WORKER_LAUNCH_ARGS
    • 传递给工作器启动命令的额外参数
  • OMX_TEAM_WORKER_CLI
    • 工作器CLI选择器:
      auto|codex|claude
      (默认:
      auto
    • auto
      模式下,当工作器
      --model
      包含
      claude
      时选择
      claude
      ,否则选择
      codex
    • claude
      模式下,工作器启动时会携带唯一的
      --dangerously-skip-permissions
      参数,忽略显式的模型/配置/推理开销启动覆盖(使用默认的
      settings.json
  • OMX_TEAM_WORKER_CLI_MAP
    • 单工作器CLI选择器(逗号分隔的
      auto|codex|claude
      列表)
    • 长度必须为
      1
      (广播)或与团队工作器数量完全一致
    • 示例:
      OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude
    • 存在时会覆盖
      OMX_TEAM_WORKER_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 (
    tmux send-keys ... C-m
    ) can appear to "do nothing" when a worker is actively processing; Enter may be queued by the pane/task flow.
  • 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
omx team status <team>
and mailbox/state evidence:
  1. 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
      omx sparkshell --tmux-pane %<worker-pane> --tail-lines 400
      before improvising extra tmux commands.
  2. If the pane is stuck in an interactive state, safely return to idle prompt first:
    • optional interrupt
      C-c
      or escape flow (CLI-specific) once, then re-check pane capture
  3. Send one concise trigger (single line) and wait for evidence:
    • tmux send-keys -t %<worker-pane> "ack + continue current task; report status" C-m
  4. Re-check:
    • pane output via
      capture-pane
    • mailbox updates (
      mailbox/leader-fixed.json
      or worker mailbox)
    • omx team status <team>
仅在检查
omx team status <team>
和邮箱/状态证据后使用:
  1. 捕获窗格尾部内容确认当前工作器状态:
    • tmux capture-pane -t %<worker-pane> -p -S -120
    • 如果需要读取更多尾部内容或有限摘要,在编写额外tmux命令前,优先通过
      omx sparkshell --tmux-pane %<worker-pane> --tail-lines 400
      进行显式选择检查。
  2. 如果窗格卡在交互状态,先安全返回空闲提示符:
    • 可选执行一次中断
      C-c
      或退出流程(依CLI而定),然后重新检查窗格捕获内容
  3. 发送一条简洁的触发指令(单行)并等待证据:
    • tmux send-keys -t %<worker-pane> "ack + continue current task; report status" C-m
  4. 重新检查:
    • 通过
      capture-pane
      查看窗格输出
    • 邮箱更新(
      mailbox/leader-fixed.json
      或工作器邮箱)
    • omx team status <team>

worker_notify_failed:<worker>

worker_notify_failed:<worker>

Meaning:
  • Leader wrote inbox but trigger submit path failed
Checks:
  1. tmux list-panes -F '#{pane_id}\t#{pane_start_command}'
  2. tmux capture-pane -t %<worker-pane> -p -S -120
  3. Verify worker process alive and not stuck on trust prompt
  4. Rebuild if running repo-local (
    npm run build
    )
含义:
  • 主进程已写入收件箱,但触发提交路径失败
检查项:
  1. tmux list-panes -F '#{pane_id}\t#{pane_start_command}'
  2. tmux capture-pane -t %<worker-pane> -p -S -120
  3. 验证工作器进程存活,未卡在信任提示界面
  4. 如果是本地仓库运行请重新构建(
    npm run build

Team starts but leader gets no ACK

团队已启动但主进程未收到ACK

Checks:
  1. Worker pane capture shows inbox processing
  2. .omx/state/team/<team>/mailbox/leader-fixed.json
    exists
  3. Worker skill loaded and
    omx team api send-message --json
    called
  4. Task-id mismatch not blocking worker flow
检查项:
  1. 工作器窗格捕获内容显示正在处理收件箱
  2. .omx/state/team/<team>/mailbox/leader-fixed.json
    存在
  3. 工作器技能已加载,且已调用
    omx team api send-message --json
  4. 任务ID不匹配未阻塞工作器流程

Worker logs
omx team api ... ENOENT
(or legacy
team_send_message ENOENT
/
team_update_task ENOENT
)

工作器日志输出
omx team api ... ENOENT
(或旧的
team_send_message ENOENT
/
team_update_task ENOENT

Meaning:
  • Team state path no longer exists while worker is still running.
  • Typical cause: leader/manual flow ran
    omx team shutdown <team>
    (or removed
    .omx/state/team/<team>
    ) before worker finished.
Checks:
  1. omx team status <team>
    and confirm whether tasks were still
    in_progress
    when shutdown occurred
  2. Verify whether
    .omx/state/team/<team>/
    exists
  3. Inspect worker pane tail for post-shutdown writes
  4. Confirm no external cleanup (
    rm -rf .omx/state/team/<team>
    ) happened during execution
Prevention:
  1. Enforce completion gate (no in-progress tasks) before shutdown
  2. Use
    shutdown
    only for terminal completion or explicit abort
  3. If aborting, expect late worker writes to fail and treat ENOENT as expected teardown artifact
含义:
  • 工作器仍在运行时团队状态路径已不存在。
  • 典型原因:主进程/手动流程在工作器完成前执行了
    omx team shutdown <team>
    (或删除了
    .omx/state/team/<team>
    )。
检查项:
  1. omx team status <team>
    ,确认关闭时是否仍有
    in_progress
    状态的任务
  2. 验证
    .omx/state/team/<team>/
    是否存在
  3. 检查工作器窗格尾部内容是否有关闭后的写入操作
  4. 确认执行过程中没有外部清理操作(
    rm -rf .omx/state/team/<team>
预防措施:
  1. 关闭前强制执行完成关卡(无进行中的任务)
  2. 仅在任务最终完成或显式中止时使用
    shutdown
  3. 如果执行中止,预期会有工作器写入失败,将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
undefined

1) 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 HUD
omx team 1:executor "fresh retry"

指引:

- 不要杀死主进程窗格
- 不要杀死HUD窗格(`omx hud --watch`),除非你有意重启HUD

Required Reporting During Execution

执行期间的报告要求

When operating this skill, provide concrete progress evidence:
  1. Team started line (
    Team started: <name>
    )
  2. tmux target and worker pane presence
  3. leader mailbox ACK path/content check
  4. status/shutdown outcomes
Do not claim success without file/pane evidence. Do not claim clean completion if shutdown occurred with
in_progress>0
. Use
omx sparkshell --tmux-pane ...
as an explicit opt-in operator aid for pane inspection and summaries; keep raw
tmux capture-pane
evidence available for manual intervention and proof.
操作该技能时,请提供具体的进度证据:
  1. 团队启动行(
    Team started: <name>
  2. tmux目标和工作器窗格存在性
  3. 主进程邮箱ACK路径/内容检查结果
  4. 状态/关闭结果
没有文件/窗格证据不要声称成功。 如果关闭时
in_progress>0
不要声称完全完成。 使用
omx sparkshell --tmux-pane ...
作为显式选择的运维辅助工具进行窗格检查和摘要;保留原始
tmux capture-pane
证据用于人工干预和证明。

MCP 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
:
ToolDescription
omx_run_team_start
Spawn tmux CLI workers in the background; returns a
jobId
immediately
omx_run_team_status
Non-blocking status check for a running job
omx_run_team_wait
Block until the job completes, with automatic idle-pane nudging
omx_run_team_cleanup
Kill worker tmux panes for a job (early stop only)
对于程序化或Agent驱动的团队启动(与交互式CLI使用相对),OMX通过
team-server
暴露四个MCP工具:
工具描述
omx_run_team_start
在后台启动tmux CLI工作器;立即返回
jobId
omx_run_team_status
对运行中的任务进行非阻塞状态检查
omx_run_team_wait
阻塞直到任务完成,自动提醒空闲窗格
omx_run_team_cleanup
杀死任务的tmux工作器窗格(仅用于提前停止)

CLI vs MCP Tools

CLI vs MCP工具

  • omx team ...
    CLI
    — Primary method for interactive team orchestration. Use this when you are operating inside a live tmux session and want direct pane visibility.
  • omx_run_team_*
    MCP tools
    — For programmatic or agent-driven team spawning (analogous to OMC's
    omc_run_team_*
    tools). Use these when an agent needs to launch workers, poll status, and collect results without manual intervention.
  • omx team ...
    CLI
    — 交互式团队编排的主要方法。当你在活跃的tmux会话中操作,需要直接的窗格可见性时使用。
  • omx_run_team_*
    MCP工具
    — 用于程序化或Agent驱动的团队启动(类似于OMC的
    omc_run_team_*
    工具)。当Agent需要启动工作器、轮询状态、收集结果而无需人工干预时使用。

Naming Distinction

命名区分

Two cleanup tools exist and must not be confused:
  • team_cleanup
    (state-server): Deletes team state files on disk (
    .omx/state/team/<team>/
    ). Use after a team run is fully complete.
  • omx_run_team_cleanup
    (team-server): Kills tmux worker panes for a job. Use only when stopping workers early; otherwise
    omx_run_team_wait
    handles natural termination.
存在两个清理工具,请勿混淆:
  • team_cleanup
    状态服务器):删除磁盘上的团队状态文件
    .omx/state/team/<team>/
    )。在团队运行完全完成后使用。
  • omx_run_team_cleanup
    团队服务器):杀死任务的tmux工作器窗格。仅在提前停止工作器时使用;否则
    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 early
omx_run_team_status
can be called between steps 1 and 2 for a non-blocking poll if you need to interleave other work while workers run.
1. 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_status
进行非阻塞轮询。

Limitations

限制

  • 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
continue
after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
Good: The user changes only the output shape or downstream delivery step (for example
make a PR
). Preserve earlier non-conflicting workflow constraints and apply the update locally.
Bad: The user says
continue
, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
正确: 工作流已经有明确的下一步时用户说
continue
。继续当前分支的工作,而不是重启或重复询问相同问题。
正确: 用户仅修改输出格式或下游交付步骤(例如
make a PR
)。保留之前无冲突的工作流约束,本地应用更新。
错误: 用户说
continue
,工作流却重启发现流程,或者在收集缺失的验证/证据前停止。