AGENT SKILL

driving-claude-code-sessions

Use when acting as a project manager that delegates tasks to other coding-agent sessions (Claude Code, Codex, or Pi) - launch workers, assign them work, monitor progress, review their tool calls, and collect results

License 许可
Apache-2.0
所属仓库
zak-keown/moe
最近更新
2026-09-05
Stars
★ 0
Forks
1

01 前言 Front Matter

name
driving-claude-code-sessions
description
Use when acting as a project manager that delegates tasks to other coding-agent sessions (Claude Code, Codex, or Pi) - launch workers, assign them work, monitor progress, review their tool calls, and collect results

02 资源文件 1

03 SKILL.md 正文

Driving Coding-Agent Sessions

Overview

You can launch coding-agent sessions — Claude Code, Codex, or Pi — as "workers" in tmux, send them prompts, wait for them to finish, read their output, and hand them off to a human. Workers run with permissions bypassed, so they execute tool calls without prompting. Each worker emits lifecycle events to a JSONL file so the controller can observe what it's doing — Claude and Codex through their hook systems, Pi through a native extension moe-crew loads into it.

All operations go through a single CLI: moe-crew. After launching a worker, the controller receives a shim path at /tmp/moe-crew-workers/bin/<tmux-name> that bakes in the worker handle. Every per-worker operation goes through that path — no positional state to thread between calls, no absolute skill path to prepend. A small set of environment variables tune behavior; see Environment variables at the bottom.

The shim path is deterministic: if you pick a memorable tmux name at launch, you can reconstruct /tmp/moe-crew-workers/bin/<tmux-name> whenever you need it. For agents driving via tool calls, that's the right model — shell state doesn't persist between calls, so a SHIM=...; $SHIM cmd pattern just adds noise. The examples below use the bare path.

Harnesses

Pick a harness with --harness at launch:

$SKILL/moe-crew launch --harness codex my-task /path/to/project
$SKILL/moe-crew launch --harness pi    my-task /path/to/project

Without --harness, MOE_CREW_DEFAULT_HARNESS wins; when it is unset, moe-crew selects the sole installed Claude Code, Codex, or Pi executable. It exits with usage code 2 and lists the installed choices when selection is ambiguous. Packs can declare defaultHarness, and each worker's harness still overrides every default.

The controller-facing command surface is identical across all three harnesses — launch, send, converse, wait-for-turn, read-turn, read-events, status, stop, and handoff behave the same regardless of harness. A few things differ:

  • Auth. Each harness authenticates from its own home — Claude ~/.claude, Codex ~/.codex, Pi ~/.pi/agent. moe-crew stages that login into the worker at launch, so to rotate credentials, relaunch.
  • adopt is Claude-only. Claude takes a caller-assigned session id, so a session can be resumed by id (claude --resume). Codex and Pi mint their own ids on the first prompt and offer no resume-by-id — relaunch them instead.
  • Codex isn't queryable until its first prompt. Codex mints its session id only when you send the first prompt, so between launch and the first send/converse a codex worker's status, session-id, and wait-for-turn return no worker known — it is running, it just hasn't registered yet. converse handles this internally, so the typical launch→converse path is fine; only the lower-level commands see the gap. (Claude takes its id at launch and Pi registers at launch, so both are queryable immediately.)

Prerequisites

  • tmux
  • a harness CLI — at least the one you launch: claude, codex, or pi

(No jq and no bash hooks: moe-crew is a TypeScript/node tool and its hooks are node programs. node is required, but it's already present wherever Claude Code runs.)

Setup

The CLI lives at <skill>/scripts/moe-crew. Top-level subcommands need the skill path:

  • moe-crew launch [--harness <claude|codex|pi>] <tmux-name> <cwd> [-- harness-args...] — bootstrap a worker (default resolution is described under Harnesses)
  • moe-crew adopt <tmux-name> <cwd> <session-id> [-- claude-args...] — re-adopt an existing Claude session as a worker (claude-only; see Recovering workers)
  • moe-crew list [--all] — enumerate workers
  • moe-crew grant-consent — one-time consent for running workers with permissions bypassed

Once a worker is launched, run subsequent commands against /tmp/moe-crew-workers/bin/<tmux-name>:

SKILL=/abs/path/to/skill/scripts
$SKILL/moe-crew grant-consent                          # one-time per machine
$SKILL/moe-crew launch my-task /path/to/project        # stdout: /tmp/moe-crew-workers/bin/my-task
/tmp/moe-crew-workers/bin/my-task status               # use the shim directly

Pick a memorable tmux name at launch; the shim path is then deterministic. (You can capture it into a shell variable in an interactive shell, but for agent-driven workflows the bare path is simpler — there's no shell state to lose between calls.)

Workflow

In examples below, $SKILL is the absolute path to skills/driving-claude-code-sessions/scripts. WORKER is the bare shim path (e.g. /tmp/moe-crew-workers/bin/my-task) — substitute the deterministic path for your worker.

1. Launch

$SKILL/moe-crew launch my-task /path/to/project
# stdout: /tmp/moe-crew-workers/bin/my-task
# stderr: Worker launched. tmux/session_id/cwd/events/reproduce

moe-crew launch:

  • Writes a 3-line shim at /tmp/moe-crew-workers/bin/my-task
  • Starts tmux and the harness in it
  • Blocks until the worker is ready — Claude (which takes a caller-assigned session id) waits for its session_start event; Codex and Pi mint their own ids on the first prompt, so launch settles their TUI and the worker's meta self-registers when it fires its first event
  • Prints the shim path on stdout (one line)
  • Prints a "Worker launched" panel on stderr — the reproduce: line is the exact command to relaunch with the same args

Pass harness CLI args after a -- separator, or pick an explicit harness with --harness:

$SKILL/moe-crew launch my-task /path/to/project -- --model sonnet
$SKILL/moe-crew launch --harness codex my-task /path/to/project

2. Converse (the typical case)

/tmp/moe-crew-workers/bin/my-task converse "Refactor the auth module" 300

converse sends the prompt, waits for the worker to finish, and prints the final assistant text on stdout. For tool-heavy turns where the bare text strips the interesting part, use --with-turn to get the full markdown:

/tmp/moe-crew-workers/bin/my-task converse --with-turn "Run the failing tests" 600

Multi-turn just works — the wait tracks turn boundaries automatically:

/tmp/moe-crew-workers/bin/my-task converse "Write tests for the auth module" 300
/tmp/moe-crew-workers/bin/my-task converse "Add edge cases for expired tokens" 300

3. Lower-level control

If you need to drive the worker more directly:

/tmp/moe-crew-workers/bin/my-task send "Refactor the auth module"     # send without waiting
/tmp/moe-crew-workers/bin/my-task wait-for-turn 300                   # block until stop or session_end
/tmp/moe-crew-workers/bin/my-task status                              # idle | working | terminated | gone | unknown
/tmp/moe-crew-workers/bin/my-task read-turn                           # last turn as markdown (tool results truncated to 5 lines)
/tmp/moe-crew-workers/bin/my-task read-turn --full                    # last turn with complete tool results

4. Watching what the worker does

Every tool call emits a pre_tool_use event with the tool name and input. Tail the event stream to watch in real time:

/tmp/moe-crew-workers/bin/my-task read-events --follow &
MONITOR_PID=$!
# ... do other work ...
kill $MONITOR_PID

Or pull events after the fact:

/tmp/moe-crew-workers/bin/my-task read-events                       # all events
/tmp/moe-crew-workers/bin/my-task read-events --last 5
/tmp/moe-crew-workers/bin/my-task read-events --type pre_tool_use

--type accepts one of: session_start, user_prompt_submit, pre_tool_use, post_tool_use, stop, session_end. Unknown event names fail fast. (Claude workers emit pre_tool_use but not post_tool_use; Codex and Pi emit both.)

If you see something you don't want, stop the worker:

/tmp/moe-crew-workers/bin/my-task stop

5. Stop and clean up

/tmp/moe-crew-workers/bin/my-task stop

Sends /exit, waits up to 10s for session_end, kills the tmux session if still running, and removes the meta, events, and shim files.

stop is destructive: the worker is gone and the shim path stops working. If you wanted the worker around for follow-up turns or a parallel workflow, don't call stop until you're done with it. To resume work under the same name, relaunch — moe-crew launch my-task /path/to/project again — and you'll get a fresh worker at the same shim path.

After stop, the shim no longer exists, so invoking it again surfaces a shell error along the lines of no such file or directory: /tmp/moe-crew-workers/bin/my-task (the exact wording depends on your shell). That's expected; the worker is gone.

6. Hand off to a human

/tmp/moe-crew-workers/bin/my-task handoff

Prints attach instructions for a human to take over the tmux session.

Finding workers

$SKILL/moe-crew list                      # live workers (idle/working/terminated)
$SKILL/moe-crew list --all                # include 'gone' workers (tmux already exited)
$SKILL/moe-crew list api                  # substring filter on tmux name
$SKILL/moe-crew prune                     # remove dead workers + orphaned sidecars/shims

Reference

moe-crew launch [--harness <claude|codex|pi>] <tmux-name> <cwd> [-- harness-args...]
moe-crew adopt <tmux-name> <cwd> <session-id> [-- claude-args...]   # claude-only
moe-crew list [--all] [<pattern>]
moe-crew prune                          # remove dead/orphaned worker state
moe-crew grant-consent

<shim> converse [--with-turn] <prompt> [timeout=120]
<shim> send <prompt>
<shim> wait-for-turn [timeout=60] [--after-line N]
<shim> status
<shim> read-events [--last N] [--type T] [--follow]   # --last caps the --follow backlog
<shim> read-turn [--full]
<shim> stop
<shim> handoff
<shim> session-id
<shim> events-file

<shim> is /tmp/moe-crew-workers/bin/<tmux-name>. Run moe-crew help for the same surface.

Common Patterns

Fan-Out: Multiple Workers in Parallel

Each worker gets its OWN linked git worktree — never a shared checkout. Two workers writing into the same tree collide on the axis the parallel- implementation worktree gate is built to prevent (see the moe plugin's dispatch-agents, "Safe Parallel Implementation: The Worktree Gate", and its two-rung fallback ladder). Create all worktrees first, branched from one recorded base SHA. Before launching anything, validate every cwd has one of the wave's pairwise-unique linked Git directories:

# One recorded base for the whole wave — every worker branches from it.
BASE=$(git -C ~/proj rev-parse HEAD)

git -C ~/proj worktree add ~/proj-worktrees/worker-api -b feat/api "$BASE"
git -C ~/proj worktree add ~/proj-worktrees/worker-ui  -b feat/ui  "$BASE"

# For each cwd, --git-dir and --git-common-dir must differ. The two --git-dir
# results must also differ from each other.
git -C ~/proj-worktrees/worker-api rev-parse --path-format=absolute --git-dir
git -C ~/proj-worktrees/worker-api rev-parse --path-format=absolute --git-common-dir
git -C ~/proj-worktrees/worker-ui rev-parse --path-format=absolute --git-dir
git -C ~/proj-worktrees/worker-ui rev-parse --path-format=absolute --git-common-dir

$SKILL/moe-crew launch worker-api ~/proj-worktrees/worker-api
$SKILL/moe-crew launch worker-ui  ~/proj-worktrees/worker-ui

/tmp/moe-crew-workers/bin/worker-api send "Add pagination to /users"
/tmp/moe-crew-workers/bin/worker-ui  send "Add a loading spinner to the user list"

/tmp/moe-crew-workers/bin/worker-api wait-for-turn 600
/tmp/moe-crew-workers/bin/worker-ui  wait-for-turn 600

/tmp/moe-crew-workers/bin/worker-api stop
/tmp/moe-crew-workers/bin/worker-ui  stop

# Integrate the wave: merge each branch into BASE, run the suite, THEN start
# the next wave from the merged head.

moe-crew launch accepts an arbitrary per-worker cwd; it does not create the worktree for you and does not know about worktrees at all. That step is git, done before dispatch. If two workers' declared work touches the same file, a task is missing Files:, Interfaces:, Consumes:, or Produces:, or any worktree creation/validation command fails, do not fan them out. Missing task metadata fails validation. A file collision or worktree failure selects the second and only fallback rung: run the whole wave sequentially from the controller's validated tree. There is no unisolated-parallel rung and no partial parallel launch.

Pipeline: Worker A produces, Worker B consumes

$SKILL/moe-crew launch spec ~/proj
/tmp/moe-crew-workers/bin/spec converse "Write an OpenAPI spec for /users to /tmp/api.yaml" 300
/tmp/moe-crew-workers/bin/spec stop

$SKILL/moe-crew launch impl ~/proj
/tmp/moe-crew-workers/bin/impl converse "Implement the endpoint defined in /tmp/api.yaml" 600
/tmp/moe-crew-workers/bin/impl stop

Don't trust worker B's summary of what it did — check the produced file. A worker can report success while having written the wrong thing (see Important Notes).

Edge Cases

Worker crashes mid-turn

wait-for-turn matches stop OR session_end, so it returns when the worker dies. Call status afterward: if it's gone, the worker crashed.

After a converse timeout, check status before wait-for-turn

A bare wait-for-turn baselines at the current end of the events file and waits for the next turn-end. If a converse timed out, the worker often finishes during the gap — the stop has already landed, so a follow-up wait-for-turn blocks the entire timeout waiting for a turn that will never start. After a timeout, call status first: idle means the turn already ended (read-turn to read it); working means it's still going.

Recovering workers after a reboot

Worker runtime state (the meta/events/shim files under /tmp/moe-crew-workers) lives in /tmp, which macOS clears on reboot — and the tmux panes die with it. But the conversations survive: Claude Code persists each session transcript at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. moe-crew adopt brings one back as a live, driveable worker (this is claude-only — Codex and Pi mint their own session ids and offer no resume-by-id, so relaunch those instead):

$SKILL/moe-crew adopt my-task /path/to/project <session-id>
# stdout: /tmp/moe-crew-workers/bin/my-task   (same shim contract as launch)

This is claude-only — codex/pi conversations do NOT survive stop. Codex and Pi run under a staged per-worker home at /tmp/moe-crew-workers/homes/<name>/ (config, auth, and the rollout/session transcript), not your real ~/.codex / ~/.pi. stop removes that home, so the transcript is gone and there is no recovery path — relaunch starts a fresh session. Only claude persists its transcript outside the worker dir (in ~/.claude/projects), which is why only claude is adoptable.

adopt pre-writes the meta keyed by <session-id>, starts claude --resume <session-id> (which preserves the id, so the worker emits events normally), and writes the shim — so the resumed conversation is fully driveable (converse/status/read-turn/…), with all prior context intact. If a tmux session of that name already exists (e.g. restored by tmux-resurrect / tmux-continuum), adopt respawns its pane in place, preserving the restored layout; otherwise it opens a new one.

Find a worker's <session-id> from its working directory: the newest *.jsonl in ~/.claude/projects/<cwd with every / . _ replaced by ->. For bulk recovery (e.g. pairing with tmux-continuum's @continuum-boot), examples/recover-workers.sh reads a tmux-resurrect snapshot, derives each id, and calls adopt per worker — run it with --dry-run first. Note: workers are restored as resumed sessions, not their original tool/MCP state; re-pass any launch args (e.g. -- --model …) you depended on.

Lost the shim path

If you know the tmux name, the path is /tmp/moe-crew-workers/bin/<tmux-name>. If you don't, moe-crew list enumerates everything; moe-crew list <pattern> filters by tmux-name substring.

Long prompts

send uses bracketed-paste, which handles multi-line and special characters. For prompts in the tens-of-KB range, write to a file and tell the worker to read it:

echo "Long instructions..." > /tmp/instructions.txt
/tmp/moe-crew-workers/bin/my-task send "Read /tmp/instructions.txt and follow it"

Important Notes

  • One controller per worker. Two controllers driving the same tmux session will collide.
  • Workers don't share state with the controller except via files on disk and the event stream.
  • Shim paths bake in absolute skill paths. A plugin reinstall at a new location breaks live workers; relaunch them.
  • moe-crew is a transparent relay, not a validator. converse/read-turn return whatever the worker says — verbatim, including when the worker is confidently wrong. For correctness-critical handoffs, verify the produced artifact on disk, not the worker's prose self-report.

Environment variables

The moe-crew CLI honors a small set of env vars. All are optional.

Variable Purpose
MOE_CREW_DEFAULT_HARNESS Default harness after worker and command/pack selections. Must be claude, codex, or pi.
MOE_CREW_PLUGIN_ROOT Installed moe-crew plugin root. The launcher otherwise derives it from the running bundle.
MOE_CREW_CLAUDE_BIN / MOE_CREW_CODEX_BIN / MOE_CREW_PI_BIN Path to each harness binary. Default to claude / codex / pi (resolved via PATH). Set when a binary is not on PATH or you want to pin a specific version.
MOE_CREW_CODEX_MODEL / MOE_CREW_PI_MODEL Optional model override for codex / pi workers. Unset = the harness default (codex: gpt-5.5; pi: its configured default).
MOE_CREW_CONVERSE_DIAG_FILE When set, moe-crew converse writes a post-mortem diagnostic on timeout — ps tree, tmux capture-pane, last 30 lines of the worker's session JSONL, last 20 lines of the moe-crew events JSONL — to this path, then emits a moe-crew-diagnostic: <path> pointer to stderr. The file is overwritten on each timeout. Unset = no diagnostic file. Useful when wrapping moe-crew in a harness that can ship the file off-box before the worker is reaped.
MOE_CREW_WORKER_DIR Override the worker dir (default $XDG_RUNTIME_DIR/moe-crew-workers, or ~/.local/state/moe-crew/workers).
MOE_CREW_SUBMIT_TIMEOUT / MOE_CREW_SUBMIT_RETRY_INTERVAL send: seconds to wait for the worker to confirm a pasted prompt (default 10) and seconds between retry-Enter resends (default 2). Raise the timeout if a slow tmux session drops the paste.
MOE_CREW_REGISTER_TIMEOUT Seconds the FIRST send/converse to a derive worker (codex/pi) waits for it to self-register its session id (default 15).
XDG_STATE_HOME Durable Moe state root for one-time consent ($XDG_STATE_HOME/moe/crew/consent; fallback ~/.local/state/moe/crew/consent).
HOME Harness-owned state root; Claude transcripts live under ~/.claude/projects/.

moe-crew help shows the same surface.

04 同仓库更多 Skills