Project Context

Polytoken discovers the applicable AGENTS.md files and delivers their contents as system reminders in persisted conversation history, not in the provider system prompt. The model receives the instructions directly without needing to re-read the files. For an exceptionally large instruction file, Polytoken provides the file’s path and asks the model to read the file with the file tools. Standing instructions can describe how to build a project, which conventions to follow, and what to avoid.

The ordered project-instruction chain starts with the global config directory, $XDG_CONFIG_HOME/polytoken (default: ~/.config/polytoken), continues through filesystem ancestors and the project root, and then follows the current working-directory stack. Polytoken orders the chain from least-specific to most-specific. One chain reminder carries the instruction files in that order. Polytoken discovers the chain at startup and after a /daemon-reload, and checks chain membership each turn and when the working directory changes. When files join or leave the chain, Polytoken delivers the updated chain. Subagents also receive the instruction chain for their starting working directory.

AGENTS.md is the cross-agent convention other coding tools already use, and Polytoken reads the same file. In each directory, Polytoken matches filenames case-insensitively and prefers AGENTS.md, then CLAUDE.md, then GEMINI.md. The first matching file serves as that directory’s instruction file.

The model can encounter more instruction files while it works. Each file triggers one discovery reminder per context. A tool-discovered file’s contents arrive in that reminder after the current tool batch finishes, unless a file read already returned the contents to the conversation. After a context reset, Polytoken can deliver a previously discovered file again when the model re-encounters the file.

Polytoken also follows relative @path/to/file.md links in instruction files and delivers linked files through the same reminders. Each link resolves from the directory containing the instruction file, and linked files must stay inside the project.

A templated AGENTS.md

A plain AGENTS.md stays as written. With template rendering enabled, Polytoken renders the body whenever it loads the file for delivery, so the instructions can reflect the active model or the current setup. To enable rendering, add a frontmatter block with polytoken: true:

---
polytoken: true
---
Build the project with `just build` and run the tests with `just test`.

{% if is_model_variant("claude") %}
Prefer small, focused commits.
{% endif %}

A mapping value for polytoken, such as polytoken: {}, also enables template rendering. If the frontmatter omits polytoken or supplies another value, Polytoken uses the body verbatim, braces and all. The example above adds a line only when a Claude-family model is active. A template can read the same variables and functions facets use; see Templating.

History carries the rendered body. The provider system prompt never contains it. After local text compaction, Polytoken re-delivers the instruction-file bodies for the project chain and a small selection of recently used files. The root instruction file is always among them. For recently used files outside the project chain, Polytoken skips the body when the retained conversation already contains a verified complete read of the file’s current contents; those files need no reminder, because the conversation already carries their contents. Every other instruction file without a re-delivered body still reaches the model as a path in a list, so the model can re-read those files with the file tools.