Claude Code Orchestrator (tmux-first)

Trigger Claude Code development tasks in observable tmux sessions with stable startup, progress visibility, and completion callback to OpenClaw. Use when use...

Security Scan

The skill largely does what its name says (orchestrates Claude runs inside tmux) but contains several practical mismatches and risky instructions (missing declared dependencies, use of a '--dangerously-skip-permissions' flag, local proxy envs, scp/ssh copy paths and automatic wake callbacks) that warrant caution before installing or running.

Purpose & Capability

The name/description match the scripts: this is a tmux-based orchestrator for running Claude Code tasks and collecting reports. However, the skill omits a few obvious runtime dependencies from its metadata (the scripts require 'jq', 'ssh'/'scp' for remote flows, and the OpenClaw CLI for wake calls) and the SKILL.md/registry metadata don't declare that the OpenClaw CLI or SSH keys will be used. That omission is a transparency gap (not necessarily malicious) but important for users to know.

Instruction Scope

The runtime instructions and scripts instruct the agent/operator to: launch 'claude' with the flag '--dangerously-skip-permissions', paste large prompts into an interactive Claude session, run git diff/lint/build in the target workdir, read project files, generate JSON/MD reports in /tmp, and send a wake callback to OpenClaw. All of these actions are within the stated purpose, but the use of the 'dangerously' flag, automatic reading of the project's workdir (and running npm scripts), and mandated automatic wake/callbacks increase the risk surface and deserve explicit user consent and review.

Install Mechanism

There is no install spec (instruction-only), and the skill ships shell scripts that are intended to be run directly. No remote downloads or archive extraction are present in the manifest. The lack of an install step lowers automatic risk, but the provided scripts will execute on the user's system when run.

Credentials

The skill declares no required environment variables/credentials, yet the scripts: export proxy environment variables (https_proxy/http_proxy/all_proxy) when launching Claude, call 'openclaw gateway call wake' (which requires the OpenClaw CLI/auth), and use ssh/scp for remote flows (which will use the user's SSH keys). The skill also runs project-local npm scripts by default (lint/build), which can execute arbitrary code in the user's repo. These real credential/secret usages are not reflected in the declared metadata, which is a proportionality/transparency issue.

Persistence & Privilege

The skill is not always-enabled and does not claim system-wide persistence. It stores task delivery state under its own 'state/' directory and writes transient reports to /tmp. It does not modify other skills' configs. Remote SSH flows rely on the user's existing SSH keys/hosts; that is expected but should be acknowledged by users.

What to consider before installing

This skill appears to do what it says (manage Claude Code runs inside tmux) but you should not install or run it without reviewing and consenting to several things: 1) Inspect the scripts yourself — they will read your project directory, run 'git diff', and by default run 'npm run lint' and 'npm run build' (npm scripts can execute arbitrary code). 2) The startup command runs 'claude --dangerously-skip-permissions' — this disables internal permission checks in the Claude CLI and increases safety risk; avoid or remove that flag unless you trust the environment and prompts. 3) The startup sets local proxy env vars (127.0.0.1:6152/6153); confirm you understand what local services are listening there (a proxy could be used to capture/exfiltrate data). 4) The wake callback uses the OpenClaw CLI to send text and report paths; the skill does not declare that OpenClaw CLI auth or network access is required — ensure your OpenClaw credentials and endpoints are configured and you are okay with reports/notifications being sent externally. 5) Remote flows copy report files via scp/ssh to a 'mini' host — verify SSH targets and keys before using remote features. Recommended actions before running: run 'scripts/bootstrap.sh' to surface missing tools; add/verify presence of 'jq' and the OpenClaw CLI; run the scripts in an isolated/test repo first; remove or edit the '--dangerously-skip-permissions' flag and proxy exports if you do not want those behaviors; and do not run these scripts on repositories containing secrets unless you fully trust the workflow.

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

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

# 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 {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