# System prompt

Override or extend the built-in instructions.

Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and zot-docs guidance for every run. Per-invocation, `--system-prompt` still wins; delete the file to revert to the default.

Custom prompts still receive appended instructions and generated context, including `AGENTS.md`, skills, auto-swarm guidance when enabled, and the date, working directory, and `Platform: <goos>/<goarch>` footer. On Windows the footer also notes that the `bash` tool runs cmd.exe, not a POSIX shell. Use `--no-context-files` to omit `AGENTS.md` instructions for one run.

Use `--append-system-prompt` (repeatable) to layer extra instructions on top without blowing the default away.

## Extension replacements

[Extensions](/docs/extensions) can subscribe to `before_agent_start` to inspect and replace the complete assembled prompt before the first model call. Unlike `SYSTEM.md` or `--system-prompt`, this replacement happens after generated context and appended instructions have been added. The host uses the returned string exactly, including an empty string, without appending anything else.

The result stays stable across ordinary follow-up messages and tool-loop steps. Model/session changes, conversation clears, and explicit prompt rebuilds trigger a new preparation pass from the base prompt. If a reset occurs while an extension is responding, the stale preparation is discarded and retried against the current base.

Subscribed extensions can see and replace every system instruction, including private context-file content. This does not alter tool permissions. See [Extensions](/docs/extensions) for the protocol, Go SDK hook, timeout behavior, and size limits.