Claude Code Orchestrator (tmux-first)

# Claude Code Orchestrator (tmux-first)

Use tmux-based orchestration for long coding tasks to avoid silent hangs and make progress observable.

Standard workflow

1. Create prompt file (avoid long shell quote issues).
2. Start a dedicated tmux session.
3. Launch `claude --dangerously-skip-permissions` in interactive mode.
4. Paste prompt into Claude.
5. Require callback command in prompt (via wrapper):
6. `bash {baseDir}/scripts/wake.sh "..." now`
7. Share socket/session attach command with user.
8. On completion, review diff + lint/build + risk summary.

Start command

```bash bash {baseDir}/scripts/start-tmux-task.sh \ --label "gallery-detail-polish" \ --workdir "/Users/yaxuan/.openclaw/workspace/work/active/02-gallery-ops" \ --prompt-file "/Users/yaxuan/Downloads/gallery-website-design-system.md" \ --task "参考这个修改我当前的画廊官网，注意优先打磨细节和质感，对整体结构展示先不用大改。" ```

Monitor commands

```bash # attach bash {baseDir}/scripts/monitor-tmux-task.sh --attach --session <session>

# capture last 200 lines bash {baseDir}/scripts/monitor-tmux-task.sh --session <session> --lines 200 ```

Task overview

List all running `cc-*` tasks at a glance — useful for "butler-style" summaries.

```bash # Human-readable one-liner per task bash {baseDir}/scripts/list-tasks.sh

# Structured JSON array (pipe to jq, feed to OpenClaw, etc.) bash {baseDir}/scripts/list-tasks.sh --json | jq . ```

• Options:
• `--lines <n>` — number of trailing pane lines to capture per task (default 20).
• `--socket <path>` — tmux socket path (default `$TMPDIR/clawdbot-tmux-sockets/clawdbot.sock`).
• `--json` — emit JSON array instead of human table.
• `--target ssh --ssh-host <alias>` — list sessions on a remote host.

Each entry contains: label, session, status, sessionAlive, reportExists, reportJsonPath, lastLines, updatedAt.

Combine with OpenClaw to generate a periodic butler summary: ``` # In an OpenClaw prompt / cron: bash {baseDir}/scripts/list-tasks.sh --json | \ openclaw gateway call summarize-tasks --stdin ```

Rules

• Prefer interactive Claude in tmux for visibility (not long `claude -p` one-shot for large tasks).
• Always include callback via wrapper `bash {baseDir}/scripts/wake.sh "..." now` in prompt.
• Startup script now uses robust submit (ready-check + multi-Enter retry + execution-state detection) to avoid "prompt pasted but not submitted".
• If no pane output for >2-3 min, inspect and restart session.
• Kill stale Claude processes before restart.
• Always return: session name + attach command + current status.

Status check (zero-token)

If wake not received within expected time, check task status before consuming tokens:

```bash bash {baseDir}/scripts/status-tmux-task.sh --label <label> ```

Output: `STATUS=running|likely_done|stuck|idle|dead|done_session_ended`

• `likely_done` / `done_session_ended` → proceed to completion loop
• `running` → wait
• `stuck` → inspect (attach or capture-pane)
• `dead` → session lost, run complete-tmux-task.sh fallback
• `idle` → Claude may be waiting for input, inspect

Completion loop (mandatory)

When wake event "Claude Code done (...)" arrives, complete this loop immediately:

1. Acknowledge user within 60s: "已收到完成信号，正在评估改动".
2. Preferred path: read completion report generated by Claude Code task:
3. - `/tmp/cc-<label>-completion-report.json`
4. If report missing, run local fallback immediately:
5. - `bash {baseDir}/scripts/complete-tmux-task.sh --label <label> --workdir <workdir>`
6. Mandatory deep-read: read full JSON/MD report before replying.
7. Read context before replying:
8. - Read completion report file(s) (`/tmp/cc-<label>-completion-report.json/.md`)
9. - Read recent tmux transcript (monitor script) to capture what Claude actually did/failed/tried
10. - Incorporate the latest user constraints from current chat
11. Then provide assistant analysis (not a fixed template):
12. - what was actually completed
13. - what is reliable vs uncertain
14. - key risks/tradeoffs in the user's context
15. - concrete next-step options
16. Ask explicit decision from user if scope drift exists.

Do not stop at wake-only notification. Wake is trigger, not final delivery.

Anti-pattern to avoid - Forbidden: one-line fixed reply after wake without reading transcript + report. - Forbidden: only relaying "done + report path" without analysis in user context. - Forbidden: rigid templated output that ignores current conversation context.

Hard guardrails added

• Prompt now enforces “no wake without report”:
• - task must write `/tmp/cc-<label>-completion-report.json` + `.md`
• - final wake must include `report=<json_path>`
• Recovery command exists for deterministic fallback:
• - `scripts/complete-tmux-task.sh` reproduces evidence and emits structured report
• Delivery SLA remains mandatory:
• - wake received -> ack <= 60s -> report