--system-prompt vs --append-system-prompt
People think --system-prompt and --append-system-prompt both just add rules. Only one of them adds. --append-system-prompt puts your text after Claude Code's default prompt. So Claude keeps its guide to the tools, its safety rules and its coding habits. --system-prompt throws the default away and uses only your text. For a coding task with a few extra rules, append. Replace only when Claude should not act as a coding helper at all.
--system-prompt Flag
It swaps the whole default prompt for yours.
--system-prompt replaces Claude Code's whole default system prompt with your own text. --system-prompt-file does the same with the text of a file. The default prompt holds the guide to the tools, the safety rules and the coding habits, so all of that goes too. Use it when Claude should not act as a coding helper at all.
--append-system-prompt Flag
It adds your text to the end of the default system prompt.
--append-system-prompt adds your text to the end of Claude Code's default system prompt. --append-system-prompt-file adds the text of a file. Claude keeps its tool guide and safety rules, and also follows yours. If you pass both forms, the file's text goes first.
In one line
- --system-prompt Flag
- It swaps the whole default prompt for yours.
- --append-system-prompt Flag
- It adds your text to the end of the default system prompt.