Claude Subagent Quickstart

#CLI Basics

Never invoke subagents through ./runner—launch them inside tmux directly so the session can persist and bypass the runner timeouts. Example:

``bash tmux new-session -d -s claude-haiku 'claude --model haiku' tmux attach -t claude-haiku ``

Once inside the session, run /model to confirm the active alias (haiku maps to Claude 3.5 Haiku) and switch models if needed.

Need to queue instructions without attaching? Use bun scripts/agent-send.ts --session <name> -- "your command" to inject text into a running agent session (single Enter is sent by default).
Run Claude through the repo wrapper when you just need help (./runner claude --help), but for actual delegation launch Claude inside tmux so the work keeps running after you disconnect.
Two modes:
Always switch to the fast Haiku model upfront (claude --model haiku --dangerously-skip-permissions … or /model haiku in-session); it keeps turnaround under the runner’s limits.
Two modes:
One-shot tasks (single summary, short answer): run claude --model haiku --dangerously-skip-permissions --print … in a tmux session, wait with sleep 30, then read the output buffer.
Interactive tasks (multi-file edits, iterative prompts): start claude --model haiku --dangerously-skip-permissions in tmux, send prompts with tmux send-keys, and capture completed responses with tmux capture-pane. Expect to sleep between turns so Haiku can finish before you scrape the pane.
Ralph’s supervisor loop launches Claude the same way (claude --dangerously-skip-permissions "<prompt>") to keep the tmux automation flowing.

The CLI accepts the prompt as a trailing argument in one-shot mode. Multi-line prompts can be piped: echo "..." | ./runner claude --print.
Add --output-format json when you need structured fields (e.g., summary + bullets) for post-processing.
Keep prompts explicit about reading full files: “Read docs/example.md in full and produce a 2–3 sentence summary covering all sections.”

Produce the markdown inventory first (pnpm run docs:list) and feed batches of filenames to your Claude session.
For each batch, issue a single instruction like “Rewrite these files with YAML front matter summaries, keep all other content verbatim.” Haiku can loop over multi-file edits when you provide the explicit list.
After Claude reports success, diff each file locally (./runner git diff docs/<file>.md) before moving to the next batch.

Ralph (see scripts/ralph.ts) spins up tmux sessions, auto-wakes the worker, and calls Claude as the supervisor via claude --dangerously-skip-permissions.
Supervisor responses must end with either CONTINUE, SEND: <message>, or RESTART; Ralph parses these tokens to decide the next action.
To start Ralph manually: bun scripts/ralph.ts start --goal "…" [--markdown path]. Progress is tracked in .ralph/progress.md by default.
Send ad-hoc instructions to the worker session with bun scripts/ralph.ts send-to-worker -- "your guidance".