System Prompt Flags
Level 5 · Scripts and servers
How to replace or add to Claude Code's system prompt at launch. Then how to keep it fixed when you resume, and run the main chat as your own agent.
Course contentsLesson 16 of 17
Level 1 · Get started
Level 2 · Inside a conversation
Level 3 · Parallel work and review
Level 4 · Setup and extensions
Level 5 · Scripts and servers
After this lesson you can
- Choose between replacing and adding to the prompt
- Run the main session as a custom agent
- Define helpers for one session in JSON
11 mincovers 8 glossary entries
Worth reading first: Tool and Settings Flags
How to change the system prompt and the agent at launch
Claude Code starts every chat with a long system prompt. It is a guide to its tools, safety rules and coding habits. Four flags change it. Two replace it: --system-prompt with your text, and --system-prompt-file with a file. Two add to the end: --append-system-prompt and --append-system-prompt-file. All four work in a chat and in -p.
The choice is whether Claude should still act as a coding helper. Adding keeps the tool guide and safety rules and puts your rules on top, such as always reply in French. Replacing drops all of it. Use it only when the job is not coding at all, and then write what the job needs yourself.
You can mix them. A replace flag and an add flag together give your text, then your extra rules. When you pass both add forms, the file's text comes first, even if you typed it second. For rules every chat in a project needs, CLAUDE.md is the better home.
A chat keeps the prompt it started with. Claude Code builds it on the first request and stores it with the session. Later requests reuse it, even after --resume, until the chat is compacted. So new flag text on a resumed chat waits. The last flag in the table, set to off, rebuilds the prompt on every request instead.
--exclude-dynamic-system-prompt-sections helps when many people run the same job. Some parts of the prompt change per person, such as where auto memory lives. This flag moves them into the first message. The rest of the prompt is then the same for all, so the prompt cache can be shared. It is meant for -p runs.
--append-subagent-system-prompt adds your text to every subagent's prompt in a -p run, nested ones too. A forked subagent is left out. It reuses the main chat's own prompt. --agent goes further for the main chat. It runs as one of your custom agents, with that agent's prompt, tools and model.
--agents defines helpers for this session in JSON, with no files to save. Each one gets a name, a description of when to use it, a prompt, and if you like its tools and model. Claude Code checks the JSON at launch and stops if it is wrong. --agent picks who leads, and --agents adds the team.
The five system prompt flags
| Flag | What it does | Keeps the tool guide? |
|---|---|---|
| --system-prompt | Replaces the default prompt with your text | No |
| --system-prompt-file | Replaces it with a file's text | No |
| --append-system-prompt | Adds your text after the default | Yes |
| --append-system-prompt-file | Adds a file's text after the default | Yes |
| --system-prompt-snapshot | Set to off, rebuilds the prompt on every request | Not changed |
claude -p --append-system-prompt "Always reply in French" "Summarize README.md"
claude -p --system-prompt-file ./prompts/triage.txt "Sort these tickets"
claude --agent code-reviewer
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You review code for bugs."}}'Worked example
Jack turns Claude into a ticket sorter
Jack wants a -p job that sorts 200 support tickets into 5 groups. Nothing in it is code, so he passes --system-prompt-file with a 30-line prompt about the groups.
The coding rules are gone. The job no longer offers to fix the app when a ticket mentions a bug.
The words for this lesson8
Check yourself
When should you replace the system prompt rather than add to it?
Finished this lesson?
Marking it complete also marks its 8 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.