System Prompt

You can't include a system prompt in the traditional sense, but CLAUDE.md files essentially work as system prompts. If you add a CLAUDE.md file to the root of the project that you are running Claude Code in, then it will get automatically pulled in as context. (You can also run /init in the Claude Code REPL, which will cause claude to create a CLAUDE.md file based on the codebase). You can also add CLAUDE.md files to sub directories with instructions scoped to those specific folders that get automatically pulled in when Claude reads/edits a file from that folder.

I believe you can also add a ~/.claude/CLAUDE.md file for a more global system prompt with user-specific instructions you want to exist across projects.

Outstanding!! Thank you this tool is outstanding.

is there a system message in claude code? I am just trying to figure out, if I have to be careful with the content in CLAUDE.md files, to not cause any ambiguities?!

!Image

It’s in the docs, it’s only available in the non-interactive mode. But you can easily script a set of subprocesses with -p —system-prompt —continue to give you a similar interface to the REPL while overriding the system prompt if you really think that helps.

As an additional note you should run away from ambiguity like it’s the devil, both with Claude and with humans.

But you can easily script a set of subprocesses with -p —system-prompt —continue to give you a similar interface to the REPL while overriding the system prompt if you really think that helps.

@rodat-dev can you elaborate?

Edit: Asked AI 😅:

The Subprocess Chain Approach:

  Instead of using Claude Code's interactive mode, you'd create a script that:

  1. Initial command with custom system prompt:
  claude -p "Your first task" --system-prompt "$(cat custom-prompt.md)" > output1.txt
  2. Continue the conversation using --continue:
  claude -p "Your next task" --system-prompt "$(cat custom-prompt.md)" --continue > output2.txt

  What --continue does:

  - Maintains context from previous commands in the same directory
  - Allows you to build up a conversation history
  - Each command still gets your custom system prompt

  Example pseudo-REPL script:

  #!/bin/bash
  SYSTEM_PROMPT=$(cat my-system-prompt.md)

  while true; do
      echo -n "> "
      read user_input

      if [ "$user_input" = "exit" ]; then
          break
      fi

      # Run claude with custom system prompt and continue flag
      claude -p "$user_input" --system-prompt "$SYSTEM_PROMPT" --continue
  done

  Key differences from true interactive mode:

  - No streaming: You'd see complete responses, not character-by-character
  - No built-in commands: Lose access to /help, /clear, etc.
  - Manual session management: You'd need to handle history yourself
  - Potential latency: Each command is a new process startup

  This gives you system prompt control at the cost of losing some interactive features. It's essentially building your own REPL wrapper around  Claude Code's non-interactive mode.

---

Some context:

GEMINI_SYSTEM_MD (Gemini CLI):

• Allows you to completely replace the root system prompt
• Set via environment variable: export GEMINI_SYSTEM_MD="Your custom system prompt"
• Overrides the built-in prompt entirely
• Full control over the AI's base behavior and instructions

CLAUDE.md (Claude Code):

• Supplements the existing system prompt, doesn't replace it
• Loaded as additional context alongside the hardcoded prompt
• Cannot override core behaviors defined in the base prompt
• Works more like "project instructions" added on top

Think of it like:

• Gemini CLI: You can swap the engine
• Claude Code: You can only add modifications/tuning to the existing engine

Important distinctions:

• Session persistence: Not applicable - this flag is for one-shot commands only
• Mid-session updates: Not possible - each -p command is a separate execution
• Interactive sessions: The --system-prompt flag doesn't work with interactive Claude Code sessions

For interactive sessions (the normal Claude Code experience), you're still limited to using CLAUDE.md files which supplement rather than replace the system prompt. The --system-prompt flag is only for single-command executions, making it quite different from Gemini CLI's GEMINI_SYSTEM_MD which works in interactive mode.

---

I'll open up a new issue: https://github.com/anthropics/claude-code/issues/2692

> But you can easily script a set of subprocesses with -p —system-prompt —continue to give you a similar interface to the REPL while overriding the system prompt if you really think that helps. @rodat-dev can you elaborate? Edit: Asked AI 😅: ``markdown The Subprocess Chain Approach: Instead of using Claude Code's interactive mode, you'd create a script that: 1. Initial command with custom system prompt: claude -p "Your first task" --system-prompt "$(cat custom-prompt.md)" > output1.txt 2. Continue the conversation using --continue: claude -p "Your next task" --system-prompt "$(cat custom-prompt.md)" --continue > output2.txt What --continue does: - Maintains context from previous commands in the same directory - Allows you to build up a conversation history - Each command still gets your custom system prompt Example pseudo-REPL script: #!/bin/bash SYSTEM_PROMPT=$(cat my-system-prompt.md) while true; do echo -n "> " read user_input if [ "$user_input" = "exit" ]; then break fi # Run claude with custom system prompt and continue flag claude -p "$user_input" --system-prompt "$SYSTEM_PROMPT" --continue done Key differences from true interactive mode: - No streaming: You'd see complete responses, not character-by-character - No built-in commands: Lose access to /help, /clear, etc. - Manual session management: You'd need to handle history yourself - Potential latency: Each command is a new process startup This gives you system prompt control at the cost of losing some interactive features. It's essentially building your own REPL wrapper around Claude Code's non-interactive mode. `` --- Some context: GEMINI_SYSTEM_MD (Gemini CLI): - Allows you to completely replace the root system prompt - Set via environment variable: export GEMINI_SYSTEM_MD="Your custom system prompt" - Overrides the built-in prompt entirely - Full control over the AI's base behavior and instructions CLAUDE.md (Claude Code): - Supplements the existing system prompt, doesn't replace it - Loaded as additional context alongside the hardcoded prompt - Cannot override core behaviors defined in the base prompt - Works more like "project instructions" added on top Think of it like: - Gemini CLI: You can swap the engine - Claude Code: You can only add modifications/tuning to the existing engine Important distinctions: - Session persistence: Not applicable - this flag is for one-shot commands only - Mid-session updates: Not possible - each -p command is a separate execution - Interactive sessions: The --system-prompt flag doesn't work with interactive Claude Code sessions For interactive sessions (the normal Claude Code experience), you're still limited to using CLAUDE.md files which supplement rather than replace the system prompt. The --system-prompt flag is only for single-command executions, making it quite different from Gemini CLI's GEMINI_SYSTEM_MD which works in interactive mode. --- I'll open up a new issue: https://github.com/anthropics/claude-code/issues/2692

Yep, but I don't see why you'd want to replace the system prompt built by Boris and all the people working to build Claude as a coding agent. It's their job to know the ins and outs of the model. You don't buy a Ferrari and your first thought is "but can I put my Volkswagen engine in it?". Not an attack, I'm no better, but I think supplementing what these guys have built is inevitably going to be the best option. They've done a phenomenal job with Claude Code.

@agentmish I fully agree with you. The usecases for completely replacing it with a "Volkswagen engine" 🙃 would be for an occasional niche "not-coding-agent" usecase.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.