Class 04 — Controlling Claude

§ System Prompt

Replace vs. Append

Two strategies for customizing Claude's instructions. Replacing gives full control; appending keeps Claude Code's built-in capabilities intact.

--system-prompt replaces

Replace the entire default system prompt with custom text. Removes all Claude Code instructions — blank slate mode. Use when you need a completely custom persona.

claude --system-prompt "You are a Python expert"

--system-prompt-file print only

Load a system prompt from a file, replacing the default. Version-control your prompts alongside your code.

claude -p --system-prompt-file ./prompts/review.txt "q"

--append-system-prompt appends

Append custom text to the end of the default system prompt. Preserves all of Claude Code's built-in capabilities — recommended for most use cases.

claude --append-system-prompt "Always use TypeScript"

--append-system-prompt-file print only

Append file contents to the default prompt. Keeps Claude Code defaults intact while loading versioned addition files.

claude -p --append-system-prompt-file ./style-rules.txt "q"

Flag	Effect	Modes	Best for
--system-prompt	Replaces entire prompt	Both	Custom personas, blank-slate
--system-prompt-file	Replaces from file	Print only	Versioned templates
--append-system-prompt	Appends to default	Both	Adding rules, keeping defaults
--append-system-prompt-file	Appends file to default	Print only	Versioned additions

§ Permissions

The Permissions Ladder

From most locked to least — choose the level appropriate for your environment. The ladder goes one direction: unlocking.

1 --permission-mode plan Claude plans only — no writes, no execution. Review before anything runs.

2 --disallowedTools Remove specific tools from context entirely. Claude cannot even see them.

3 --tools "Bash,Read" Whitelist exactly which built-in tools are available. Use "" to disable all.

4 default (ask each time) Claude prompts for approval before sensitive operations. Standard interactive mode.

5 --allowedTools "Bash(git *)" Pre-approve specific tool patterns. Supports glob syntax — no prompt for matching calls.

6 --dangerously-skip-permissions Skip all permission prompts. Sandboxed/automated environments only.

--permission-mode

Begin in a specified permission mode. Options include plan (read-only planning), default, acceptEdits, bypassPermissions.

claude --permission-mode plan

--allowedTools

Tools that execute without prompting. Supports pattern matching: Bash(git log *) allows only matching git commands.

claude --allowedTools "Bash(git log *)" "Read"

--disallowedTools

Tools removed from the model's context entirely. Claude cannot call them even if it tries.

claude --disallowedTools "Bash(git push *)" "Edit"

--tools

Restrict which built-in tools are available. "" disables all, "default" enables all, or list specific names.

claude --tools "Bash,Edit,Read"

--permission-prompt-tool

Delegate permission decisions to an MCP tool in non-interactive mode. For automated pipelines that need dynamic approval logic.

claude -p --permission-prompt-tool mcp_auth "query"

--json-schema print only

Get validated JSON output matching a schema once the agent finishes. Structural guarantee for automation.

claude -p --json-schema '{"type":"object"}' "query"

§ Model & Context

Model Controls & Context Scope

Model Controls

--model

Set the model. Use alias (sonnet, opus, haiku) or full ID like claude-sonnet-4-6.

claude --model claude-sonnet-4-6

--fallback-model print only

Automatic fallback when the primary model is overloaded. Keeps pipelines running during busy periods.

claude -p --fallback-model sonnet "query"

--max-turns print only

Cap the number of agentic turns. Exits with an error if the limit is reached. No limit by default.

claude -p --max-turns 3 "query"

--max-budget-usd print only

Stop before exceeding a dollar cost. A safety rail for automated runs that might loop unexpectedly.

claude -p --max-budget-usd 5.00 "query"

--betas API key only

Beta API headers. Only for API key users (not subscription accounts).

claude --betas interleaved-thinking

Context & Settings

--add-dir

Add additional working directories. Validates each path exists. Repeatable for multi-repo contexts.

claude --add-dir ../apps ../lib

--settings

Load settings from a JSON file or raw JSON string, stacked on top of defaults.

claude --settings ./settings.json

--setting-sources

Comma-separated list of config layers to activate: user, project, local. Control which config files are read.

claude --setting-sources user,project

--plugin-dir

Load plugins from a directory for this session only. Repeatable — add multiple plugin directories.

claude --plugin-dir ./my-plugins

--disable-slash-commands

Disable all skills and slash commands for this session. For controlled environments where skill interference is unwanted.

claude --disable-slash-commands