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. The bundled templates omit session-specific environment facts so equivalent agents can share the same cached system-prompt prefix. The same variables remain available to project overrides. If an override intentionally needs them, it can add Jinja expressions such as:

- 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 deliver working directory, Git status, platform, model, and vision capability in the initial runtime-authored <system-reminder source="session"> history message. Values that can change while a session runs — the date, repository guidance, and project memory — arrive as later <system-reminder> context updates. Anything added to a project override remains part of the system prompt and therefore changes its cache key.

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.