Skip to main content

Skill: ca-leash

Source: ludus/skills/ca-leash/SKILL.md

name: ca-leash description: Spawn focused Claude Code sub-agents for deep research, multi-file analysis, and document creation. Use when work is too large for inline context or requires many turns of focused execution. metadata: openclaw: emoji: "🦾" requires: env: []​

ca-leash — Your Personal Sub-Agent

ca-leash spawns a headless Claude Code agent as a background process for focused work. You keep your context lean; the sub-agent handles the heavy lifting.

Quick Reference​

CommandDescription
ca-leash start "<prompt>" --cwd <path>Start session (detaches by default)
ca-leash start -f "<prompt>"Start in foreground (blocks, streams output)
ca-leash --json status <id>Check status: RUNNING, STOPPED, ERROR
ca-leash log <id> -n 10Last 10 output messages
ca-leash log <id> --offset NRead from message N (for incremental reads)
ca-leash attach <id>Stream live output (blocks, Ctrl+C to detach)
ca-leash send <id> "msg"Send follow-up message to running session
ca-leash interrupt <id>Interrupt current query (session stays alive)
ca-leash stop <id>Gracefully stop session

All commands support --json for machine-readable output.

Core Workflow​

Write Prompt File → Start → Monitor → Collect Result
  1. Write a prompt file to /workspace/prompts/<task-slug>.md — include scope, deliverable, constraints, and output location
  2. Start ca-leash (detaches, returns session ID immediately): 
    SESSION=$(ca-leash --json start "$(cat /workspace/prompts/<task-slug>.md)" --cwd /workspace | jq -r .session_id)
  3. Monitor — check status between other work: 
    ca-leash --json status $SESSION | jq -r .status   # RUNNING / STOPPED / ERROR
    ca-leash log $SESSION -n 5                         # peek at progress
  4. Collect — when status is STOPPED, read the result: 
    ca-leash log $SESSION -n 3    # last messages = summary

For short results, read from the log. For output > 50 lines, instruct the sub-agent to write a file and reference its path.

When to Use ca-leash​

Use ca-leash when...Work directly when...
Need to read/analyze many filesSimple lookup or status update
Producing a document > 50 linesAnswering a quick question
Deep research across reposTask takes 1-2 turns
Task would consume many turns in your contextReading metadata
Any work that writes code, docs, or reportsRelaying a single finding

Writing Good Prompts​

The prompt is the only communication channel. Include everything the sub-agent needs.

Bad prompt (too vague):

"Implement the factorial feature."

Good prompt (complete context):

"Task: Add factorial operation to the calculator.
 Spec: calc.sh must support 'fact N' returning N! (0! = 1, negative = error).
 Design decision: use 'fact' as the operator name (avoids shell conflicts).
 Tests must pass: bash test.sh
 Output: PR URL to stdout. Do not merge."

Key elements: task title, spec/constraints, prior decisions, output location, what NOT to do.

Error Handling​

Incomplete work (sub-agent stopped or timed out)​

ca-leash start \
  "<original prompt>

   NOTE: Previous run did not complete. Focus only on: <remaining step>.
   Skip steps already done: <what was completed>." \
  --cwd <same-cwd>

Resuming from checkpoint​

Check what was done (git log, file existence), then re-run with a prompt that starts from the checkpoint.

Assessing Output​

When ca-leash finishes (status=STOPPED), read the log and evaluate:

SignalMeaningAction
PR URL presentCode work completedProceed with review flow
"Tests pass: N/N"Implementation correctProceed
"Tests fail: X/N"Partial — needs retryRe-run with failure details
"Error: permission denied"Tool or auth issueEscalate
Truncated / no summarySession incompleteRe-run with tighter scope

When output is ambiguous, post it verbatim — don't guess at success.

Anti-Patterns​

  • No nested ca-leash — sub-agents must NOT spawn another ca-leash session
  • No trivial lookups — 1-2 file reads? Do it yourself. ca-leash overhead isn't worth it.
  • No orphaned sessions — always ca-leash stop <id> when done or on error
  • No guessing at output — if the summary is unclear, report it verbatim