Prompt overrides

Kolega Code can load repository-local Markdown templates that replace its base system prompts. This is useful when a project needs a different operating style, stricter rules, or specialized instructions for sub-agents.

File layout

Create uppercase Markdown files under .kolega/prompts/:

.kolega/prompts/
  CODER.md          # CoderAgent, all coder modes
  PLANNING.md       # PlanningAgent
  GENERAL.md        # GeneralAgent sub-agent
  INVESTIGATION.md  # InvestigationAgent sub-agent
  BROWSER.md        # BrowserAgent sub-agent
  COMPACTION.md     # conversation compaction summarizer

Only these uppercase filenames are recognized. Lowercase aliases such as coder.md are ignored. Every file is optional: you can override only CODER.md, only COMPACTION.md, or any subset. Missing files fall back to Kolega Code’s bundled or host-provided defaults.

CODER.md is the only coder override. It applies to the coder agent in every coder mode, even though Kolega Code internally has separate hosted prompt template slots for cli, code, vibe, and fix.

Generate starter files

In the TUI, run:

/prompts dump

From a terminal, run:

kolega-code prompts dump --project .

Both commands create any missing files in .kolega/prompts/ from Kolega Code’s current bundled/base prompts. Existing files are skipped by default so local edits are not overwritten.

To dump only specific starter files, pass one or more prompt selectors:

/prompts dump coder compaction

kolega-code prompts dump coder compaction --project .

Supported selectors are coder, planning, general, investigation, browser, compaction, and all. Filename aliases are also accepted case-insensitively, so CODER.md, coder.md, and CODER all select the coder prompt.

To overwrite existing files:

/prompts dump --force

kolega-code prompts dump --project . --force

--force also works with selective dumps:

kolega-code prompts dump compaction --project . --force

To see which overrides exist:

/prompts list

kolega-code prompts list --project .

To validate existing overrides before restarting or sharing a repository:

/prompts validate

kolega-code prompts validate --project .

Validation uses the same strict Jinja rendering check that runs during startup. Missing optional files are not errors. The terminal command exits 0 when all existing supported overrides are valid (or no overrides exist), and exits 1 when any override cannot render.

Dumped files are editable Markdown templates. Environment values are written as Jinja tags, not frozen current values. For example:

- Working directory: {{ context.project_path }}
- Is directory a git repo: {{ context.is_git_repo }}
- Platform: {{ context.platform }}
- Model: {{ context.model_name }}
- Model supports vision: {{ context.model_supports_vision | lower }}

The bundled prompts deliberately omit values that change while a session runs — the date, repository guidance, and project memory. Anything in the system prompt is processed ahead of every message, so a change there invalidates the cached prefix for the whole conversation; those values are delivered to the agent as <system-reminder> context updates instead, each time they change. The variables remain available to your overrides if you want them, at that cost.

Template variables

Override files are rendered with a limited Jinja variable context. These variables are available:

• context.system_name
• context.project_path
• context.is_git_repo
• context.platform
• context.date_today
• context.model_name
• context.model_supports_vision
• context.available_ports
• context.workspace_id
• context.workspace_environment_variables
• mode
• project_template_slug

Common fields are also available as top-level aliases:

• system_name
• project_path
• is_git_repo
• platform
• date_today
• model_name
• model_supports_vision
• available_ports
• workspace_id

model_supports_vision is true when the selected model accepts image input. It does not indicate that the model can generate images.

Project override templates can use variables, conditionals, and loops over the exposed values. Project-local {% include %} and {% import %} are not supported.

How overrides are applied

Agent prompt overrides replace the bundled base system prompt for that agent type. Kolega Code still appends dynamic runtime/project sections after your override, including:

• matching prompt extensions, such as skills or gigacode guidance
• host-provided workspace_memories, labelled as host workspace context
• enabled private project memory, including its backend policy and bounded MEMORY.md index
• AGENTS.md or legacy KOLEGA.md project guidance

These sections remain distinct and survive coder, planning, and sub-agent prompt overrides. They are also different from resumable session history and the Planning tab’s transient task list. Project memory is not generated from either: Kolega Code performs no completed-turn transcript review or automatic memory authoring.

Only the private Markdown backend’s MEMORY.md index is injected automatically, up to 200 lines or 25 KiB; linked topics require read_memory. Memory is treated as untrusted observations rather than instructions. Private project memory is owner-controlled state and is not secret-scanned or redacted before injection. Disabling project memory removes both its context and tools without deleting its private data.

COMPACTION.md is different: it fully replaces only the system prompt used by the conversation compaction summarizer. The user prompt containing the conversation history is still generated by Kolega Code.

Each override file is capped at 128 KiB. If a file is unreadable, too large, or cannot be rendered, Kolega Code logs a warning and falls back to the normal bundled/host prompt.

Security note

Prompt overrides let a repository influence agent behavior. Review .kolega/prompts/ in untrusted projects just as you would review AGENTS.md, scripts, hooks, or other project-local automation.