Documentation — Spybara

cli-reference.md +38 −1

Details

27| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |27| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |

28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |

31| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt (print mode only; added in v1.0.54) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |

32| `--append-system-prompt` | Append custom text to the end of the default system prompt (works in both interactive and print modes; added in v1.0.55) | `claude --append-system-prompt "Always use TypeScript"` |

33| `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` |35| `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` |

75 77

76For more details on creating and using subagents, see the [subagents documentation](/en/docs/claude-code/sub-agents).78For more details on creating and using subagents, see the [subagents documentation](/en/docs/claude-code/sub-agents).

77 79

80### System prompt flags

82Claude Code provides three flags for customizing the system prompt, each serving a different purpose:

85| :----------------------- | :--------------------------------- | :------------------ | :------------------------------------------------------------------- |

90**When to use each:**

92* **`--system-prompt`**: Use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.

93 ```bash theme={null}

94 claude --system-prompt "You are a Python expert who only writes type-annotated code"

95 ```

97* **`--system-prompt-file`**: Use when you want to load a custom prompt from a file, useful for team consistency or version-controlled prompt templates.

98 ```bash theme={null}

99 claude -p --system-prompt-file ./prompts/code-review.txt "Review this PR"

100 ```

101

102* **`--append-system-prompt`**: Use when you want to add specific instructions while keeping Claude Code's default capabilities intact. This is the safest option for most use cases.

103 ```bash theme={null}

104 claude --append-system-prompt "Always use TypeScript and include JSDoc comments"

105 ```

106

107<Note>

108 `--system-prompt` and `--system-prompt-file` are mutually exclusive. You cannot use both flags simultaneously.

109</Note>

110

111<Tip>

112 For most use cases, `--append-system-prompt` is recommended as it preserves Claude Code's built-in capabilities while adding your custom requirements. Use `--system-prompt` or `--system-prompt-file` only when you need complete control over the system prompt.

113</Tip>

114

78For detailed information about print mode (`-p`) including output formats,115For detailed information about print mode (`-p`) including output formats,

79streaming, verbose logging, and programmatic usage, see the116streaming, verbose logging, and programmatic usage, see the

80[SDK documentation](/en/docs/claude-code/sdk).117[SDK documentation](/en/docs/claude-code/sdk).

sub-agents.md +92 −0

Details

241> Ask the debugger subagent to investigate this error241> Ask the debugger subagent to investigate this error

242```242```

243 243

244## Built-in subagents

245

246Claude Code includes built-in subagents that are available out of the box:

247

248### Plan subagent

249

250The Plan subagent is a specialized built-in agent designed for use during plan mode. When Claude is operating in plan mode (non-execution mode), it uses the Plan subagent to conduct research and gather information about your codebase before presenting a plan.

251

252**Key characteristics:**

253

254* **Model**: Uses Sonnet for more capable analysis

255* **Tools**: Has access to Read, Glob, Grep, and Bash tools for codebase exploration

256* **Purpose**: Searches files, analyzes code structure, and gathers context

257* **Automatic invocation**: Claude automatically uses this agent when in plan mode and needs to research the codebase

258

259**How it works:**

260When you're in plan mode and Claude needs to understand your codebase to create a plan, it delegates research tasks to the Plan subagent. This prevents infinite nesting of agents (subagents cannot spawn other subagents) while still allowing Claude to gather the necessary context.

261

262**Example scenario:**

263

264```

265User: [In plan mode] Help me refactor the authentication module

266

267Claude: Let me research your authentication implementation first...

268[Internally invokes Plan subagent to explore auth-related files]

269[Plan subagent searches codebase and returns findings]

270Claude: Based on my research, here's my proposed plan...

271```

272

273<Tip>

274 The Plan subagent is only used in plan mode. In normal execution mode, Claude uses the general-purpose agent or other custom subagents you've created.

275</Tip>

276

244## Example subagents277## Example subagents

245 278

246### Code reviewer279### Code reviewer

374 407

375Claude Code intelligently selects subagents based on context. Make your `description` fields specific and action-oriented for best results.408Claude Code intelligently selects subagents based on context. Make your `description` fields specific and action-oriented for best results.

376 409

410### Resumable subagents

411

412Subagents can be resumed to continue previous conversations, which is particularly useful for long-running research or analysis tasks that need to be continued across multiple invocations.

413

414**How it works:**

415

416* Each subagent execution is assigned a unique `agentId`

417* The agent's conversation is stored in a separate transcript file: `agent-{agentId}.jsonl`

418* You can resume a previous agent by providing its `agentId` via the `resume` parameter

419* When resumed, the agent continues with full context from its previous conversation

420

421**Example workflow:**

422

423Initial invocation:

424

425```

426> Use the code-analyzer agent to start reviewing the authentication module

427

428[Agent completes initial analysis and returns agentId: "abc123"]

429```

430

431Resume the agent:

432

433```

434> Resume agent abc123 and now analyze the authorization logic as well

435

436[Agent continues with full context from previous conversation]

437```

438

439**Use cases:**

440

441* **Long-running research**: Break down large codebase analysis into multiple sessions

442* **Iterative refinement**: Continue refining a subagent's work without losing context

443* **Multi-step workflows**: Have a subagent work on related tasks sequentially while maintaining context

444

445**Technical details:**

446

447* Agent transcripts are stored in your project directory

448* Recording is disabled during resume to avoid duplicating messages

449* Both synchronous and asynchronous agents can be resumed

450* The `resume` parameter accepts the agent ID from a previous execution

451

452**Programmatic usage:**

453

454If you're using the Agent SDK or interacting with the AgentTool directly, you can pass the `resume` parameter:

455

456```typescript theme={null}

457{

458 "description": "Continue analysis",

459 "prompt": "Now examine the error handling patterns",

460 "subagent_type": "code-analyzer",

461 "resume": "abc123" // Agent ID from previous execution

462}

463```

464

465<Tip>

466 Keep track of agent IDs for tasks you may want to resume later. Claude Code displays the agent ID when a subagent completes its work.

467</Tip>

468

377## Performance considerations469## Performance considerations

378 470

379* **Context efficiency**: Agents help preserve main context, enabling longer overall sessions471* **Context efficiency**: Agents help preserve main context, enabling longer overall sessions

Documentation 2025-11-01 21:01 UTC to 2025-11-02 18:01 UTC