claude-code

在可观察的 tmux 会话中触发 Claude 代码开发任务，具有稳定的启动、进度可见性以及对 OpenClaw 的完成回调。当用户要求通过 Claude Code 运行编码工作并希望通过 SSH 登录、监控进度并在完成后自动收到审核通知时使用。

# 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):
   `bash {baseDir}/scripts/wake.sh "..." now`
6. Share socket/session attach command with user.
7. 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:
   - `/tmp/cc-<label>-completion-report.json`
3. If report missing, run local fallback immediately:
   - `bash {baseDir}/scripts/complete-tmux-task.sh --label <label> --workdir <workdir>`
4. **Mandatory deep-read**: read full JSON/MD report before replying.
5. Read context before replying:
   - Read completion report file(s) (`/tmp/cc-<label>-completion-report.json/.md`)
   - Read recent tmux transcript (monitor script) to capture what Claude actually did/failed/tried
   - Incorporate the latest user constraints from current chat
6. Then provide assistant analysis (not a fixed template):
   - what was actually completed
   - what is reliable vs uncertain
   - key risks/tradeoffs in the user's context
   - concrete next-step options
7. 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

---

## 中文说明

# Claude Code 编排器（tmux 优先）

对于长时间运行的编码任务，使用基于 tmux 的编排，以避免无声卡死并使进度可观察。

## 标准工作流

1. 创建提示词文件（避免长 shell 引号问题）。
2. 启动一个专用的 tmux 会话。
3. 在交互模式下启动 `claude --dangerously-skip-permissions`。
4. 将提示词粘贴到 Claude 中。
5. 在提示词中要求回调命令（通过 wrapper）：
   `bash {baseDir}/scripts/wake.sh "..." now`
6. 将 socket/会话 attach 命令分享给用户。
7. 完成时，审查 diff + lint/build + 风险摘要。

## 启动命令

```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 "参考这个修改我当前的画廊官网，注意优先打磨细节和质感，对整体结构展示先不用大改。"
```

## 监控命令

```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
```

## 任务概览

一目了然地列出所有正在运行的 `cc-*` 任务 —— 适用于“管家式”摘要。

```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 .
```

选项：
- `--lines <n>` —— 每个任务捕获的尾部窗格行数（默认 20）。
- `--socket <path>` —— tmux socket 路径（默认 `$TMPDIR/clawdbot-tmux-sockets/clawdbot.sock`）。
- `--json` —— 输出 JSON 数组而非人类可读表格。
- `--target ssh --ssh-host <alias>` —— 列出远程主机上的会话。

每个条目包含：**label**、**session**、**status**、**sessionAlive**、**reportExists**、**reportJsonPath**、**lastLines**、**updatedAt**。

与 OpenClaw 结合以生成周期性的管家摘要：
```
# In an OpenClaw prompt / cron:
bash {baseDir}/scripts/list-tasks.sh --json | \
  openclaw gateway call summarize-tasks --stdin
```

## 规则

- 为提高可见性，优先在 tmux 中使用交互式 Claude（对于大型任务不要使用长时间的 `claude -p` 一次性命令）。
- 始终通过 wrapper `bash {baseDir}/scripts/wake.sh "..." now` 在提示词中加入回调。
- 启动脚本现在使用稳健的提交方式（就绪检查 + 多次 Enter 重试 + 执行状态检测），以避免“提示词已粘贴但未提交”。
- 如果超过 2-3 分钟没有窗格输出，检查并重启会话。
- 重启前杀掉过期的 Claude 进程。
- 始终返回：会话名 + attach 命令 + 当前状态。

## 状态检查（零 token）

如果在预期时间内未收到 wake，在消耗 token 之前先检查任务状态：

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

输出：`STATUS=running|likely_done|stuck|idle|dead|done_session_ended`

- `likely_done` / `done_session_ended` → 进入完成循环
- `running` → 等待
- `stuck` → 检查（attach 或 capture-pane）
- `dead` → 会话丢失，运行 complete-tmux-task.sh 回退
- `idle` → Claude 可能在等待输入，进行检查

## 完成循环（强制）

当 wake 事件 "Claude Code done (...)" 到达时，立即完成此循环：

1. 在 60 秒内向用户确认："已收到完成信号，正在评估改动"。
2. 首选路径：读取 Claude Code 任务生成的完成报告：
   - `/tmp/cc-<label>-completion-report.json`
3. 如果报告缺失，立即运行本地回退：
   - `bash {baseDir}/scripts/complete-tmux-task.sh --label <label> --workdir <workdir>`
4. **强制深度阅读**：回复前阅读完整的 JSON/MD 报告。
5. 回复前阅读上下文：
   - 阅读完成报告文件（`/tmp/cc-<label>-completion-report.json/.md`）
   - 阅读最近的 tmux 记录（monitor 脚本），以捕获 Claude 实际做了/失败了/尝试了什么
   - 纳入当前聊天中最新的用户约束
6. 然后提供助手分析（而非固定模板）：
   - 实际完成了什么
   - 哪些是可靠的、哪些是不确定的
   - 在用户上下文中的关键风险/权衡
   - 具体的下一步选项
7. 如果存在范围漂移，请用户做出明确决策。

不要止步于仅 wake 通知。wake 是触发器，而非最终交付。

### 应避免的反模式
- 禁止：wake 后未阅读记录 + 报告就给出一行固定回复。
- 禁止：仅转达"完成 + 报告路径"而在用户上下文中没有分析。
- 禁止：忽略当前对话上下文的僵硬模板化输出。

## 新增的硬性护栏

- 提示词现在强制执行“无报告不 wake”：
  - 任务必须写入 `/tmp/cc-<label>-completion-report.json` + `.md`
  - 最终 wake 必须包