Run a task via the Claude Code CLI (`claude -p`) in the background and report results back. Use to offload work to a sub-Claude instance while conserving the current session's context.
Delegates a task to a headless Claude Code subprocess, waits for completion, then summarizes the result back into the conversation.
claude -p "<prompt>" --dangerously-skip-permissions --output-format text
| Flag | Purpose |
|---|---|
-p| Non-interactive print mode — required for scripted use |
--dangerously-skip-permissions | Bypass all permission prompts (use in trusted local workspaces only) |
--output-format text | Plain text output — avoids JSON noise in context |
Optional flags to add when relevant:
| Flag | When to add |
|---|---|
--model <model> | User specifies a model (e.g. sonnet, opus, haiku, or full ID) |
--effort <level> | Set reasoning effort: low, medium, high, max |
--continue | Resume the most recent Claude session in the current directory |
--resume[=sessionId] | Resume a specific previous session |
--add-dir <path> | Grant access to an additional directory |
--permission-mode auto | Auto-approve edits without full bypass (lighter alternative to --dangerously-skip-permissions) |
--append-system-prompt <prompt> | Add extra instructions on top of the default system prompt |
--agent <agent> | Use a specific configured agent |
Use the Bash tool with run_in_background: true. Write output to a temp file so you can read it later without flooding context:
claude -p "<prompt>" --dangerously-skip-permissions --output-format text > /tmp/claude-agent-output.txt 2>&1
Once the background task completes, read /tmp/claude-agent-output.txt with the Read tool. Then:
The entire point of this skill is to save context. Apply these rules strictly:
git diff --stat to summarize the scope rather than showing diffs inline# Refactor a file
claude -p "Refactor src/app/shared/llm.py to support a new LLM provider" \
--dangerously-skip-permissions --output-format text
# Read-only analysis
claude -p "Explain how the skill loader works in src/app/agents/skills/loader.py" \
--output-format text --permission-mode plan
# Use a specific model with higher effort
claude -p "Add unit tests for GeminiCISChat in src/tests/shared/" \
--dangerously-skip-permissions --output-format text --model opus --effort high
# Resume previous session
claude -p "Continue the refactor from last time" \
--dangerously-skip-permissions --output-format text --continue
# Use a specific agent
claude -p "Review this PR for security issues" \
--dangerously-skip-permissions --output-format text --agent code-review