[taoeffect]

This PR greatly improves the system prompt handling of Crush.

• Closes Custom System Prompt #2677
• Closes Support system prompts globally(not per-project) #2057

Adds the ability to override the system prompt:

-p --sys-prompt                           Use a custom system prompt file

It does this while preserving all of the custom template logic in coder.md.tpl for injecting environment status, skills, memory, etc.

Users can also now override the default system prompt with their own by modifying ~/.config/crush/crush.json or their project-local .crush/crush.json:

{
  "options": {
    "system_prompt_path": "/path/to/system-prompt.md"
  }
}

Project-local override:

{
  "options": {
    "data_directory": "./.crush",
    "system_prompt_path": "./.crush/system-prompt.md"
  }
}

The existing non-templated system prompt directives have been moved to default_system_prompt.md and have been greatly improved.

Problems Fixed With Existing System Prompt

The existing system prompt had many problems:

1. It was very long and contained many DRY violations (repititions)
2. It contained self-contradictions like "read only target sections using offset and limit" vs "Read entire file before editing"
3. It was dogmatic about coding choices that should be left to users (e.g. "NEVER ADD COMMENTS")

So I first ran the original system prompt through Gemini 3.5 Flash, GPT-5.5, and Opus 4.7 to both condense it by fixing DRY violations, and also verifying multiple times that the condensed version preserved all original directives. Then I went manually in and made some adjustments to the original directives to make them less dogmatic and allow users to override the defaults (e.g. "NEVER COMMENT!") with their own directives.

The new default system prompt is now 38.8% shorter while preserving all directives and removing dogmatic language that infringes on reasonable user-choices.

AI Disclosure

GPT-5.5 (xhigh) and Qwen 3.7 Max were used in the coding of this PR with 2 rounds of review (GPT-5.5 and Copilot).

GPT-5.5, Opus 4.7, and Gemini 3.5 Flash were used in the refining, improvement, and verification of the new default system prompt, along with myself.

• I have read CONTRIBUTING.md.
• I have created a discussion that was approved by a maintainer (for new features).

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for customizing the agent “system prompt” via both config and a CLI runtime override, and threads that value through local and server-backed workspace creation into prompt rendering.

Changes:

• Add options.system_prompt_path (schema + config) and a runtime override (--sys-prompt / -p)
• Plumb SystemPromptPath through proto workspace creation, backend workspace creation, and prompt rendering
• Introduce a built-in default system prompt template and tests for schema + prompt + CLI + backend behavior

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
internal/proto/proto.go	Adds SystemPromptPath to workspace proto payloads
internal/config/store.go	Adds runtime override storage for system prompt path
internal/config/config.go	Adds options.system_prompt_path to config + JSON schema
internal/cmd/root.go	Adds --sys-prompt/-p flag and wires it into local/server setup
internal/cmd/system_prompt_test.go	New tests for flag presence/inheritance and local override plumbing
internal/cmd/schema_test.go	Ensures JSON schema includes system_prompt_path
internal/backend/backend.go	Applies system prompt override during workspace creation and exposes it via proto
internal/backend/backend_test.go	Tests backend workspace creation carries system prompt override through
internal/agent/templates/default_system_prompt.md	Adds embedded default system prompt content
internal/agent/templates/coder.md.tpl	Switches coder template to consume .SystemPrompt variable
internal/agent/prompts.go	Embeds default system prompt and applies as default option
internal/agent/prompt/prompt.go	Implements system prompt selection (default/config/override) + reads file
internal/agent/prompt/prompt_test.go	Tests default/config/override precedence for prompt building
README.md	Documents config + CLI usage for custom system prompts
.gitignore	Ignores .agents/* subdirectories

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Artyrm]

Yes, custom prompt is a must.

[taoeffect]

This feature is available in my fork which tracks upstream if you need it: https://github.com/taoeffect/crush

[Artyrm]

Thank you, I'll give it a shot.

[Jelloeater]

@taoeffect @Artyrm That would be a nice small patch. If i recall correctly you can do something similar with Pi https://github.com/earendil-works/pi/tree/main/packages/coding-agent#context-files and Opencode? https://www.reddit.com/r/opencodeCLI/comments/1p13hsz/default_prompts_for_models/

[andrinoff]

Thank you for your contribution! This pull request has merge conflicts and has had no activity for over 2 months, so we are closing it to keep the queue manageable. If you would still like to get this merged, please rebase onto the latest main branch and reopen it.

[taoeffect]

You mean you preferred your solution in #4141 over mine. That's fine but be honest.

[andrinoff]

That's not mine (look at the commit), and this PR was automatically closed. Does this one has something over the new one by Kieran?

[andrinoff]

Looking at this PR (and sorry I didn't see this PR earlier) it seems to miss out on:

1. Customisable prompts per agent (normal, subagents, planning, e.t.c.)

2. crushrc

3. Kieran's (again, not mine) implementation seems much smaller

If you do have any features to add to that PR, please, do say, either I'll pass it on to Kieran, or can apply a patch to the branch.

Sorry again for not noticing this PR earlier. Thank you for your work here!

[taoeffect]

I do see that Kieran's is more inline with Crush's current needs (i.e. the crushrc and the new (?) prompts for specific contexts).

I would request:

• Adding support for crush.json as well for those who prefer Crush's original config format
• Adding support for global vs project-local overrides (the way this PR does)
• Adding the ability to override from the CLI (the -p --sys-prompt from this PR)
• Improving the default system prompt (see the improvements made in this PR)