docs: document AGENTS.md persistent instructions [release=skip]

commit: 30f9ca597a924654ff7dce9beb3bdf6bd39c50a6
author: patriceckhart · 3mo ago · 2026-07-08 05:26 UTC
parent: d5769b9
signature: unsigned

1 file · +31 -1

M README.md +31 -1


@@ -18,8 +18,8 @@ Yet another coding agent harness, lightweight and written (vibe-slopped) in go.
18	18		- built-in telegram bot.
19	19		- extensions in any language via subprocess + json-rpc. None installed by default; opt in with `zot ext install` or `zot --ext`. See [docs/extensions.md](docs/extensions.md).
20	20		- user and extension themes via JSON; see [docs/themes.md](docs/themes.md).
	21	+	- standing instructions via `AGENTS.md` files (global and per-project); see [Persistent instructions](#persistent-instructions-agentsmd).
21	22		- reusable instructions via `SKILL.md` files; see [docs/skills.md](docs/skills.md).
22		-	- no community atm.
23	23
24	24		## Install
25	25

@@ -107,6 +107,7 @@ $ZOT_HOME/
107	107		├── auth.json # api keys and oauth tokens (mode 0600)
108	108		├── sessions/ # jsonl transcripts, one dir per cwd
109	109		├── models-cache.json # live /v1/models discovery cache (6h ttl)
	110	+	├── AGENTS.md # optional: global instructions appended to the prompt
110	111		├── SYSTEM.md # optional: replaces the default system prompt
111	112		├── skills/ # optional: user SKILL.md files
112	113		├── themes/ # optional: user theme JSON files

@@ -116,6 +117,35 @@ $ZOT_HOME/
116	117
117	118		Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and guidelines for every run. `--system-prompt` still wins per-invocation. Delete the file to revert to the default.
118	119
	120	+	## Persistent instructions (AGENTS.md)
	121	+
	122	+	Use `AGENTS.md` to give zot standing instructions that layer on top of the default system prompt, without replacing it. This is the friendliest way to shape behavior (for example, taming local models that jump straight to code edits) because it adds guidance rather than taking over the base identity the way `SYSTEM.md` does.
	123	+
	124	+	zot discovers `AGENTS.md` files automatically at startup and loads them in this order:
	125	+
	126	+	1. `$ZOT_HOME/AGENTS.md` (global, machine-wide instructions that apply to every project).
	127	+	2. Every `AGENTS.md` from the top-most parent directory down to the current working directory. More specific (deeper) files may override earlier ones.
	128	+
	129	+	All discovered files are appended to the prompt in that order, so a global baseline can be refined per project.
	130	+
	131	+	For a general, non-project-specific instruction set, put your rules in `$ZOT_HOME/AGENTS.md`, for example:
	132	+
	133	+	```markdown
	134	+	Treat questions and discussions as requests for explanation. Do not edit files or run tools unless explicitly asked to make a change. Ask before modifying code.
	135	+	```
	136	+
	137	+	`AGENTS.md` vs the other mechanisms:
	138	+
	139	+	\| Mechanism \| Scope \| Effect \|
	140	+	\|---\|---\|---\|
	141	+	\| `$ZOT_HOME/AGENTS.md` \| global, every run \| appended to the default prompt \|
	142	+	\| `./AGENTS.md` (and parent dirs) \| project \| appended to the default prompt \|
	143	+	\| `$ZOT_HOME/SYSTEM.md` \| global, every run \| replaces the default prompt entirely \|
	144	+	\| `--append-system-prompt <text>` \| single run \| appends for one invocation (repeatable) \|
	145	+	\| `--system-prompt <text>` \| single run \| replaces the prompt for one invocation \|
	146	+
	147	+	> Note: zot does not read a `CLAUDE.md` instruction file. The only Claude-compatible thing it picks up is skills under `.claude/skills/`. If you are migrating from Claude Code, move that content into `AGENTS.md` (global or per-project) and zot will use it.
	148	+
119	149		## Changelog on update
120	150
121	151		The first time you launch a newer zot binary, the TUI shows the GitHub release notes once in a dismissible overlay. Press any key to close. The version is recorded in `config.json`'s `last_changelog_shown` so the same release notes never reappear. Fresh installs don't see a changelog (no upgrade has happened yet). The fetch is best-effort: a network failure or a missing release page silently skips, with another attempt on the next launch.


@@ -18,8 +18,8 @@ Yet another coding agent harness, lightweight and written (vibe-slopped) in go.
18		- built-in telegram bot.	18		- built-in telegram bot.
19		- extensions in any language via subprocess + json-rpc. None installed by default; opt in with `zot ext install` or `zot --ext`. See [docs/extensions.md](docs/extensions.md).	19		- extensions in any language via subprocess + json-rpc. None installed by default; opt in with `zot ext install` or `zot --ext`. See [docs/extensions.md](docs/extensions.md).
20		- user and extension themes via JSON; see [docs/themes.md](docs/themes.md).	20		- user and extension themes via JSON; see [docs/themes.md](docs/themes.md).
			21	+	- standing instructions via `AGENTS.md` files (global and per-project); see [Persistent instructions](#persistent-instructions-agentsmd).
21		- reusable instructions via `SKILL.md` files; see [docs/skills.md](docs/skills.md).	22		- reusable instructions via `SKILL.md` files; see [docs/skills.md](docs/skills.md).
22	-	- no community atm.
23			23
24		## Install	24		## Install
25			25

@@ -107,6 +107,7 @@ $ZOT_HOME/
107		├── auth.json # api keys and oauth tokens (mode 0600)	107		├── auth.json # api keys and oauth tokens (mode 0600)
108		├── sessions/ # jsonl transcripts, one dir per cwd	108		├── sessions/ # jsonl transcripts, one dir per cwd
109		├── models-cache.json # live /v1/models discovery cache (6h ttl)	109		├── models-cache.json # live /v1/models discovery cache (6h ttl)
			110	+	├── AGENTS.md # optional: global instructions appended to the prompt
110		├── SYSTEM.md # optional: replaces the default system prompt	111		├── SYSTEM.md # optional: replaces the default system prompt
111		├── skills/ # optional: user SKILL.md files	112		├── skills/ # optional: user SKILL.md files
112		├── themes/ # optional: user theme JSON files	113		├── themes/ # optional: user theme JSON files

@@ -116,6 +117,35 @@ $ZOT_HOME/
116			117
117		Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and guidelines for every run. `--system-prompt` still wins per-invocation. Delete the file to revert to the default.	118		Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and guidelines for every run. `--system-prompt` still wins per-invocation. Delete the file to revert to the default.
118			119
			120	+	## Persistent instructions (AGENTS.md)
			121	+
			122	+	Use `AGENTS.md` to give zot standing instructions that layer on top of the default system prompt, without replacing it. This is the friendliest way to shape behavior (for example, taming local models that jump straight to code edits) because it adds guidance rather than taking over the base identity the way `SYSTEM.md` does.
			123	+
			124	+	zot discovers `AGENTS.md` files automatically at startup and loads them in this order:
			125	+
			126	+	1. `$ZOT_HOME/AGENTS.md` (global, machine-wide instructions that apply to every project).
			127	+	2. Every `AGENTS.md` from the top-most parent directory down to the current working directory. More specific (deeper) files may override earlier ones.
			128	+
			129	+	All discovered files are appended to the prompt in that order, so a global baseline can be refined per project.
			130	+
			131	+	For a general, non-project-specific instruction set, put your rules in `$ZOT_HOME/AGENTS.md`, for example:
			132	+
			133	+	```markdown
			134	+	Treat questions and discussions as requests for explanation. Do not edit files or run tools unless explicitly asked to make a change. Ask before modifying code.
			135	+	```
			136	+
			137	+	`AGENTS.md` vs the other mechanisms:
			138	+
			139	+	\| Mechanism \| Scope \| Effect \|
			140	+	\|---\|---\|---\|
			141	+	\| `$ZOT_HOME/AGENTS.md` \| global, every run \| appended to the default prompt \|
			142	+	\| `./AGENTS.md` (and parent dirs) \| project \| appended to the default prompt \|
			143	+	\| `$ZOT_HOME/SYSTEM.md` \| global, every run \| replaces the default prompt entirely \|
			144	+	\| `--append-system-prompt <text>` \| single run \| appends for one invocation (repeatable) \|
			145	+	\| `--system-prompt <text>` \| single run \| replaces the prompt for one invocation \|
			146	+
			147	+	> Note: zot does not read a `CLAUDE.md` instruction file. The only Claude-compatible thing it picks up is skills under `.claude/skills/`. If you are migrating from Claude Code, move that content into `AGENTS.md` (global or per-project) and zot will use it.
			148	+
119		## Changelog on update	149		## Changelog on update
120			150
121		The first time you launch a newer zot binary, the TUI shows the GitHub release notes once in a dismissible overlay. Press any key to close. The version is recorded in `config.json`'s `last_changelog_shown` so the same release notes never reappear. Fresh installs don't see a changelog (no upgrade has happened yet). The fetch is best-effort: a network failure or a missing release page silently skips, with another attempt on the next launch.	151		The first time you launch a newer zot binary, the TUI shows the GitHub release notes once in a dismissible overlay. Press any key to close. The version is recorded in `config.json`'s `last_changelog_shown` so the same release notes never reappear. Fresh installs don't see a changelog (no upgrade has happened yet). The fetch is best-effort: a network failure or a missing release page silently skips, with another attempt on the next launch.