Claude Code Pro ⚡

intent

run multi-file coding tasks in background tmux sessions without polling overhead. this skill uses completion callbacks (the task notifies you when done) instead of polling every 30 seconds, cutting supervision tokens by 80-97%. use it for refactors, new features, and multi-file changes that benefit from background execution. skip it for simple single-file edits, bug fixes under 3 files, or tasks needing frequent mid-execution feedback. the core trade-off: upfront clarity (detailed requirements) trades for token efficiency (no polling).

inputs

tmux and claude cli

• tmux binary installed and in PATH
• claude CLI installed and in PATH (for any inline Claude calls during task execution)
• bash 4+ for script execution

task definition

• task description (inline via --task flag or file via --task-file)
• working directory where code lives (e.g., ~/project)
• session label for identification (e.g., auth-refactor, jwt-migration)
• completion callback command (required; appended to task prompt so task can signal done)

environment setup

• $HOME or equivalent for locating scripts and default working directories
• tmux socket isolation via -L cc socket (doesn't interfere with existing tmux sessions)
• network access to any external services the task invokes (APIs, git servers, etc.)

optional external connections

• git remote if task involves pushing branches (requires git auth configured, e.g., SSH keys or GitHub token in git config)
• API keys for services touched by the task (passed via env vars or .env file in working directory)

edge cases and setup

• if tmux session limit is hit, old cc-* sessions may fail to spawn. monitor and cleanup with --all flag.
• if claude CLI is not installed but task requires it, script will fail at invoke time.
• if working directory doesn't exist, start.sh will fail.
• if task requires git push, ensure git user and SSH keys are configured.

procedure

step 1: decide whether to use this skill

• input: task scope (count files affected, estimate complexity)
• if fewer than 3 files AND straightforward fix, just read + edit directly in your agent. skip this skill.
• if 3+ files OR multi-step refactor OR exploration-heavy, continue to step 2.
• output: decision logged in agent reasoning (keep for audit trail)

step 2: write detailed requirements upfront

• input: task description, acceptance criteria, file list, edge cases
• compose requirements in prose or structured format. be explicit about what done looks like.
• store in file or keep in memory for --task inline flag.
• output: clear task prompt (50-200 words, specific file names, expected file count)

step 3: start the task with completion callback

• input: task description, working directory, session label, completion callback command
• run bash {baseDir}/scripts/start.sh --label <label> --workdir <dir> --task "<prompt + callback>"
  • or use --task-file <path> for longer requirements
  • callback must be appended: openclaw system event --text "Done: <brief desc>" --mode now
• example:

  bash {baseDir}/scripts/start.sh \
    --label jwt-migration \
    --workdir ~/myproject \
    --task "Refactor auth.js to use JWT tokens. Files: auth.js, middleware.js, tests/auth.test.js. When completely finished, run: openclaw system event --text \"Done: JWT auth refactor\" --mode now"
  

• output: tmux session spawned with socket -L cc, named cc-<label>. session id or confirmation printed to stdout.

step 4: wait for completion signal

• input: nothing (agent sleeps)
• background task executes. agent does other work (zero tokens spent).
• tmux session runs in background, isolated via -L cc socket.
• output: completion event received from task (text "Done: ..." from step 3 callback)

step 5: verify task result with lightweight monitoring

• input: session label, line count (recommend 50 for efficiency)
• run bash {baseDir}/scripts/monitor.sh --session <label> --lines 50
  • or --json flag for structured output if agent needs to parse
• output: last 50 lines of tmux session buffer (or full JSON blob if --json)

step 6: optional follow-up or adjustment

• input: additional instructions or clarifications (use sparingly)
• if task needs mid-execution feedback, run bash {baseDir}/scripts/send.sh --session <label> --text "<prompt>"
• if task context is getting large, use --compact flag to reduce token footprint
• output: prompt delivered to tmux session
• note: this is a fallback. design tasks upfront to minimize mid-execution changes.

step 7: cleanup

• input: session label
• run bash {baseDir}/scripts/stop.sh --session <label> to kill tmux session
• or --all to kill all cc-* sessions
• output: session terminated, resources freed

step 8: fallback polling (if notification never arrives)

• input: session label
• if no "Done: ..." event after 15 minutes of waiting, run one lightweight poll:

  bash {baseDir}/scripts/monitor.sh --session <label> --json --lines 100
  

• read output to infer task status (look for error messages, completion markers, or final file state)
• output: last 100 lines of buffer, structured JSON
• decision: if task appears stuck, send diagnostic prompt or kill session

decision points

before starting: dispatch decision

• if task scope is < 3 files (single file fix, isolated bug): skip this skill. just read + edit directly.
• if task is single bug fix: skip. inline edits are faster and cheaper.
• if task requires extensive code exploration across many files: start this skill.
• if task is multi-file refactor (3-10 files): start this skill.
• if task is new feature spanning 5+ files: start this skill.
• if you need real-time feedback or frequent corrections mid-task: skip this skill (polling overhead would be unavoidable).

during execution: monitoring cadence

• if notification arrives within 15 minutes: proceed to step 5 (verify result with lightweight monitor).
• if no notification after 15 minutes: assume task is delayed or stuck. run fallback poll in step 8.
• if poll reveals error or incomplete state: send diagnostic prompt (step 6) or kill and retry (step 7).

after verification: accept or retry

• if result looks correct (code compiles, tests pass, files match requirements): cleanup (step 7) and done.
• if result is incomplete or has bugs: use send.sh to send corrections (step 6), go back to step 4 wait. or kill session (step 7) and restart.

network or auth failures

• if task fails due to missing git credentials or API key: kill session, set env var or config, restart.
• if network timeout during task: kill session and retry; no partial state is retained.

output contract

successful task completion produces:

• modified files in the working directory specified in step 3 (--workdir)
• all file changes staged or committed according to task instructions (agent must specify "commit" or "leave staged")
• zero or minimal error logs in tmux session buffer (task completes cleanly)
• completion event with text "Done: " received in step 4

monitoring output (step 5) is one of:

• plain text: last N lines of tmux session (default 50 lines)
• json: structured object with fields: {"status": "running|done|error", "lines": [...], "last_timestamp": "..."}

session list (optional list.sh) outputs:

• human-readable: table with columns (label, uptime, status)
• json: array of session objects with fields (label, pid, created_at, buffer_size)

failure modes:

• if tmux session crashes: file changes may be partial or lost. agent must re-run task.
• if network or auth fails mid-task: session halts. cleanup required. restart task from step 2.
• if callback command is malformed or not executed: agent never receives notification. fallback poll in step 8 must trigger.

outcome signal

the task succeeded if:

1. completion event arrived (text "Done: ..." from callback in step 3)
2. lightweight monitor (step 5) shows expected output or file changes
3. working directory has modified files that match task requirements (verify with git diff, ls -la, or agent read)
4. no error messages in tmux buffer (no "error", "fatal", "failed" keywords in last 100 lines)

the task failed if:

1. no completion event after 15 minutes (step 8 fallback poll triggered)
2. fallback poll reveals error messages or incomplete state
3. tmux session crashed or became unresponsive
4. working directory has no changes or changes don't match requirements

token efficiency validation:

• if you started this skill and got a result with < 1000 supervision tokens total (including wait time): skill worked as designed.
• if you burned > 5000 supervision tokens (multiple polls or frequent corrections): task was too small or requirements were unclear. future tasks should skip this skill or use better upfront specs.

---

files and scripts

script	purpose	inputs	outputs
scripts/start.sh	launch claude code in tmux with task and callback	--label, --workdir, --task or --task-file	session id, confirmation
scripts/monitor.sh	lightweight output capture, optional json	--session, --lines (default 50), optional --json	text or json blob
scripts/send.sh	send follow-up prompt or compact signal	--session, --text, optional --compact	confirmation
scripts/list.sh	list active cc sessions	optional --json	human-readable table or json array
scripts/stop.sh	kill session(s)	--session or --all	confirmation

completion callback template

always append this to your task prompt in step 2-3. the task itself must run this command when done:

openclaw system event --text "Done: [brief description of what was accomplished]" --mode now

example:

Task: Refactor auth module to JWT.
...
When completely finished, run: openclaw system event --text "Done: JWT auth refactor, all tests passing" --mode now

this is non-negotiable. without the callback, the skill degrades to polling.

agent workflow (tl;dr)

1. decide: is this a 3+ file task? no → just read+edit. yes → continue.
2. start: start.sh with detailed task + callback.
3. wait: sleep. zero tokens.
4. notified: receive "Done: ..." event.
5. check: monitor.sh --lines 50 to confirm.
6. cleanup: stop.sh to end session.
7. fallback: if no notification after 15 min, one poll with --json.

design choices

• isolated tmux socket (-L cc): doesn't interfere with user's existing tmux sessions.
• cc- prefix: easy to list, filter, and bulk-stop all claude code sessions.
• bracketed paste mode: multi-line prompts work without escaping issues.
• json output option: agent can parse structured data with fewer tokens than scraping text.
• callback-driven: task signals completion; agent doesn't guess or poll.
• upfront requirements: longer initial prompt, zero mid-task corrections, net token savings.

---

credits: original skill by swaylq (clawhub). enriched for implexa quality standards with explicit decision trees, edge case handling, and structured output contracts.