Oh-my-codex worker

Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based OMX teams

install

source · Clone the upstream repo

git clone https://github.com/Yeachan-Heo/oh-my-codex

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Yeachan-Heo/oh-my-codex "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/worker" ~/.claude/skills/yeachan-heo-oh-my-codex-worker && rm -rf "$T"

manifest: skills/worker/SKILL.md

source content

Worker Skill

This skill is for a Codex session that was started as an OMX Team worker (a tmux pane spawned by

$team

Identity

You MUST be running with

OMX_TEAM_WORKER

set. It looks like:

<team-name>/worker-<n>

Example:

alpha/worker-2

Load Worker Skill Path (Claude/Codex)

When a worker inbox tells you to load this skill, resolve the first existing path:

${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md

```
~/.codex/skills/worker/SKILL.md
```

<leader_cwd>/.codex/skills/worker/SKILL.md

```
<leader_cwd>/skills/worker/SKILL.md
```
(repo fallback)

Startup Protocol (ACK)

Parse

OMX_TEAM_WORKER

into:

```
teamName
```
(before the
```
/
```
)
```
workerName
```
(after the
```
/
```
, usually
```
worker-<n>
```
)

Send a startup ACK to the lead mailbox before task work:
- Recipient worker id:
```
leader-fixed
```
- Body: one short deterministic line (recommended:
```
ACK: <workerName> initialized
```
  ).
After ACK, proceed to your inbox instructions.

The lead will see your message in:

<team_state_root>/team/<teamName>/mailbox/leader-fixed.json

Use CLI interop:

omx team api send-message --input <json> --json

with

{team_name, from_worker, to_worker:"leader-fixed", body}

Copy/paste template:

omx team api send-message --input "{\"team_name\":\"<teamName>\",\"from_worker\":\"<workerName>\",\"to_worker\":\"leader-fixed\",\"body\":\"ACK: <workerName> initialized\"}" --json

Inbox + Tasks

Resolve canonical team state root in this order:
1. ```
OMX_TEAM_STATE_ROOT
```
  env
2. worker identity
```
team_state_root
```
3. team config/manifest
```
team_state_root
```
4. local cwd fallback (
```
.omx/state
```
  )

Read your inbox:

<team_state_root>/team/<teamName>/workers/<workerName>/inbox.md

Pick the first unblocked task assigned to you.

Read the task file:

<team_state_root>/team/<teamName>/tasks/task-<id>.json

(example:

task-1.json

)

Task id format:
- The MCP/state API uses the numeric id (
```
"1"
```
  ), not
```
"task-1"
```
  .
- Never use legacy
```
tasks/{id}.json
```
  wording.
Claim the task (do NOT start work without a claim) using claim-safe lifecycle CLI interop (
```
omx team api claim-task --json
```
).
Do the work.
Complete/fail the task via lifecycle transition CLI interop (
```
omx team api transition-task-status --json
```
) from
```
in_progress
```
to
```
completed
```
or
```
failed
```
.
- Do NOT directly write lifecycle fields (
```
status
```
  ,
```
owner
```
  ,
```
result
```
  ,
```
error
```
  ) in task files.
Use
```
omx team api release-task-claim --json
```
only for rollback/requeue to
```
pending
```
(not for completion).

Update your worker status:

<team_state_root>/team/<teamName>/workers/<workerName>/status.json

with

{"state":"idle", ...}

Mailbox

Check your mailbox for messages:

<team_state_root>/team/<teamName>/mailbox/<workerName>.json

When notified, read messages and follow any instructions. Use short ACK replies when appropriate.

Note: leader dispatch is state-first. The durable queue lives at:

<team_state_root>/team/<teamName>/dispatch/requests.json

Hooks/watchers may nudge you after mailbox/inbox state is already written.

Use CLI interop:

```
omx team api mailbox-list --json
```
to read

omx team api mailbox-mark-delivered --json

to acknowledge delivery

Copy/paste templates:

omx team api mailbox-list --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\"}" --json
omx team api mailbox-mark-delivered --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\",\"message_id\":\"<MESSAGE_ID>\"}" --json

Dispatch Discipline (state-first)

Worker sessions should treat team state + CLI interop as the source of truth.

Prefer inbox/mailbox/task state and
```
omx team api ... --json
```
operations.
Do not rely on ad-hoc tmux keystrokes as a primary delivery channel.
If a manual trigger arrives (for example
```
tmux send-keys
```
nudge), treat it only as a prompt to re-check state and continue through the normal claim-safe lifecycle.

Shutdown

If the lead sends a shutdown request, follow the shutdown inbox instructions exactly, write your shutdown ack file, then exit the Codex session.