Claude Code system prompt: what is in it, and how to append to it or replace it

Claude Code sends Claude a system prompt of its own — how to behave, how to use its tools, safety rules — that you never see in the session. You change it at launch: --append-system-prompt adds your text after it, --system-prompt replaces it. CLAUDE.md is not part of it; Claude Code sends that as a message after the system prompt.

What is in Claude Code's system prompt

Anthropic describes it, in the Agent SDK docs, as the prompt the CLI uses, "with tool usage instructions and security and safety instructions", written for a coding agent in a repository with a human watching and steering. The docs describe it; they do not print it.

Two things often taken for it are not:

• Anthropic's "System prompts" release notes cover claude.ai and the Claude phone apps. They "do not apply to the Claude API", and they are not Claude Code's prompt.
• The Piebald-AI/claude-code-system-prompts repository (MIT) extracts the prompt's parts from each Claude Code release — on 20 October 2026 its README was at v2.1.304 and counted more than 500 strings: the main prompt in pieces, tool descriptions, the Plan and Explore agents' prompts, the compaction prompt. It is read out of the program, not Anthropic's documentation.

To see how much room it takes in your own session, run /context: the system prompt is one of the rows in what fills the context window.

The five system prompt flags

claude --append-system-prompt "Write commit messages in Conventional Commits"
claude --append-system-prompt-file ./team-rules.md

You can combine them: a replacement plus an appended file, or, from Claude Code 2.1.283, a flag together with its own file form. With --append-system-prompt-file and --append-system-prompt together, the file's contents come first whatever order you type them in.

Append or replace?

Append, for coding work. Replacing removes the instructions Claude Code relies on — in the SDK docs' words, you "take responsibility for replacing the tool guidance and safety instructions your agent still needs". Anthropic's own table calls the append route "the lowest-risk customization": "Nothing is removed."

Replace when the agent is not Claude Code any more: a different name, a non-coding job, no human in the loop.

Why a resumed session ignores the new text

Claude Code builds the system prompt once, on a conversation's first request, and records it. Every later request reuses that recording — after --resume and --continue too — until the conversation is compacted. So new flag text, or none, reaches an old conversation only after /compact or in a new one.

While you are still tuning the wording, --system-prompt-snapshot off rebuilds the prompt on every request (Claude Code 2.1.257 or later).

System prompt, CLAUDE.md, output style: which one

• CLAUDE.md "is delivered as a user message after the system prompt, not as part of the system prompt itself". The project-root file reloads from disk after compaction. What to put in it: CLAUDE.md.
• Output styles change the instructions Claude Code sends with every request. A custom style drops Claude Code's software engineering instructions unless its frontmatter has keep-coding-instructions: true. Pick one with /output-style, or "outputStyle" in settings.
• Subagents run their own system prompt; output styles and the main session's auto memory do not reach them, except a fork of the conversation, which inherits both. --append-subagent-system-prompt adds to theirs, with -p only.

A system prompt per project: Caprock

The flags are per launch, so a project's own rules mean retyping them or wrapping claude in a script. Caprock's desktop app keeps them with the project instead. Write them as you add a project, or later on the New agent sheet under Project instructions. Every session Caprock starts in that project then gets them:

• Claude Code through --append-system-prompt, after Claude Code's own prompt, which stays in place. Since 0.81.0.
• Codex as its developer instructions, -c developer_instructions=… — Codex's own setting for "additional developer instructions injected into the session" — beside the repository's AGENTS.md. Since 0.82.0.
• Grok Build through --rules, which appends to Grok's system prompt. Since 0.99.0.

What to expect:

• Up to 16 KB, since they travel on the command line.
• Kept by Caprock, on your machine, not in the repository: CLAUDE.md is untouched, and teammates do not get them.
• Only sessions Caprock starts, from the app or a paired phone. A claude you start in your own terminal does not get them, and neither do OpenCode, Gemini CLI and Hermes Agent.
• The recording rule still holds. Caprock passes the flag when it continues a session too, but a conversation keeps the prompt it started with until it is compacted, so edited instructions reach the next new one.

Install Caprock to set them per project.