What is the --system-prompt Flag in Claude Code
The --system-prompt flag (introduced in v2.0.14) replaces Claude Code's entire system prompt with your custom instructions, giving you complete behavioral control while preserving tool capabilities. This is the nuclear option for system prompt customization.
How It Works
The --system-prompt flag replaces everything in Claude Code's system prompt except:
- Tool definitions (approximately
12ktokens of tool specifications) - One line: "You are a Claude agent, built on Anthropic's Claude Agent SDK."
This means you get almost complete control over Claude's behavior, personality, domain expertise, and interaction patterns. Unlike other customization options, you're starting from a blank slate.
# Interactive mode with complete system prompt replacement
claude --system-prompt "You are a Python code reviewer specializing in performance optimization. Focus on algorithmic efficiency, memory usage, and scalability. Provide specific recommendations with complexity analysis."
# Simple custom agent
claude --system-prompt "You are a helpful assistant focused on clarity and brevity."
Comparison: System Prompt Customization Options
Understanding when to use each flag:
| Flag | Works In | What It Does | Best For |
|---|---|---|---|
--system-prompt | Interactive + Print | Replaces entire prompt (except tools + 1 line) | Complete behavioral transformation, custom agents from scratch |
--system-prompt-file | Print only | Replaces entire prompt (except tools) from file | One-off specialized print mode tasks, scripting |
--append-system-prompt | Interactive + Print | Adds to existing prompt | Augmenting default behavior, adding expertise |
| Output Styles | Interactive + Print | Replaces personality sections, keeps structure | Domain transformation while preserving software focus |
When to Use --system-prompt
Perfect for:
- Custom agent creation - Building specialized agents from scratch without software engineering assumptions
- Complete behavioral overhaul - Transforming Claude into something entirely different
- Research and experimentation - Testing minimal system prompts to understand behavior
- Domain-specific specialists - Creating focused experts without irrelevant context
Not ideal for:
- Quick adjustments - Use
--append-system-promptor Output Styles instead - Preserving defaults - You lose all of Anthropic's carefully crafted instructions
- Beginners - Requires understanding what instructions are needed for good behavior
Technical Considerations
Tool Definition Overhead:
- The
~12ktokens of tool definitions cannot be removed or customized - These consume significant context window space regardless of your custom prompt
- Consider this overhead when designing complex system prompts
Context Window Impact:
- Adding large custom prompts (
10k+tokens) on top of tool definitions can exacerbate context window issues - Context degradation observed at
80-120ktokens, sometimes as early as80k - Keep custom prompts focused and concise for best results
Instruction Adherence:
- Your custom prompt is placed near the start of the system prompt (before tool definitions)
- LLMs maintain better context from the start and end of prompts
- This placement actually helps with instruction adherence despite tool bloat
Example Use Cases
Minimal assistant:
claude --system-prompt "You are a helpful assistant. Be concise and accurate."
Domain expert:
claude --system-prompt "You are a senior database architect with 15 years PostgreSQL experience. Prioritize data integrity, query performance, and scalability. Always consider normalization, indexing strategies, and replication when making recommendations."
Research mode:
claude --system-prompt "You are a research assistant. Always cite sources, maintain objectivity, and organize findings systematically. Never interpret data - present it verbatim."
Custom agent with specific rules:
claude --system-prompt "You are a code reviewer. Rules: 1) Always check for security vulnerabilities, 2) Analyze time/space complexity, 3) Suggest optimizations, 4) Flag potential bugs. Be direct and specific."
The --system-prompt flag gives you maximum control but maximum responsibility. You must provide all behavioral instructions, personality traits, and interaction patterns. Start simple and iterate based on results.
See Also: Output Styles|--system-prompt-file Flag|How to Update System Prompt|Configuration