claude-code

Claude Code Delegation

Delegate coding work to Claude Code, Anthropic's autonomous coding agent CLI.

Setup (once): npm install -g @anthropic-ai/claude-code && claude auth login · verify with claude auth status / claude doctor. CI token: claude setup-token. Full auth/install variants → references/flags.md.

Platform check (before running anything): detect the OS first. All shell examples in this skill are POSIX (bash). Linux/macOS run them as-is. On Windows, run Claude Code natively in PowerShell/Git Bash for print and background modes, but interactive tmux orchestration requires WSL. Shell-syntax translation table (quoting, env vars, piping, paths) → references/platforms.md.

Mode Selection (decide FIRST)

Do NOT hand-roll tmux fan-outs for parallel work — prefer --bg + claude agents --json --all.

Print Mode (the 90% path)

terminal(command="claude -p 'Fix the auth bug in src/auth.py' \
  --allowedTools 'Read,Edit' --max-turns 10 --output-format json",
  workdir="/path/to/project", timeout=180)

Always set: workdir · --max-turns (5–10; print-mode only) · --allowedTools (least privilege: Read,Edit,Write,Bash, patterns like Bash(git *)).

JSON result fields: result (text) · session_id (for resume) · subtype (success | error_max_turns | error_budget) · total_cost_usd · num_turns · structured_output (with --json-schema).

Common variants:

git diff main... | claude -p 'Review for bugs' --max-turns 1     # pipe input, cheapest review
claude -p 'Continue: add pooling' --resume <session_id>          # resume; --continue = latest in cwd; --fork-session = branch
claude -p 'List functions' --output-format json --json-schema '<schema>' --max-turns 5   # structured extraction (needs turns to read files)
claude --bare -p 'task' --settings ci.json                       # CI: skips hooks/plugins/CLAUDE.md; auth = ANTHROPIC_API_KEY only
claude -p 'task' --max-budget-usd 0.50 --fallback-model haiku    # cost cap (min ~$0.05) + overload fallback

Streaming, stream-json events, bidirectional input, cache-reuse (--exclude-dynamic-system-prompt-sections) → references/print-mode.md.

Background Mode

claude --bg 'investigate flaky test in tests/api.test.ts'   # NOT compatible with -p
claude agents --json --all                                   # list/inspect
claude attach <id> | logs <id> | stop <id> | respawn <id> | rm <id>

Guardrails & Gotchas (violations break agents)

1. -p auto-skips trust/permission dialogs (any non-TTY does) — only run in trusted directories.
2. Interactive mode = tmux required (Windows: only inside WSL — never attempt tmux in PowerShell/cmd; fall back to -p or --bg); two startup dialogs, and the --dangerously-skip-permissions dialog defaults to "No, exit" (must send Down then Enter). Full patterns → references/interactive-tmux.md.
3. Session resume is per-directory — --continue only finds sessions from the same cwd.
4. Slash commands don't work in -p — describe the task in natural language instead.
5. Context >70% degrades quality — in interactive sessions monitor /context, use /compact.
6. Clean up: kill tmux sessions and claude stop/rm background sessions when done.
7. Don't kill slow sessions — capture progress first (tmux capture-pane / claude logs).
8. Report back: after completion, summarize what changed (use the JSON result + git diff).

References (read on demand)