DOX: a self-documenting AGENTS.md tree for AI coding agents

The problem DOX targets: an agent that edits without local context

Most agent instruction files are a single document at the repository root. That works until a repository has areas with genuinely different rules: a migration folder where files must be append-only, a generated client that should never be hand-edited, a test suite with its own fixture conventions. A root-level file either grows into a long list of exceptions or stays short and silent about the local cases. DOX's answer is to split instructions along the directory tree. The root AGENTS.md holds project-wide instructions plus a top-level index, and child AGENTS.md files hold instructions for specific areas. The README states the intended loop plainly: before any edit, the agent walks the docs tree from the root to the area it will touch, reads the relevant local guidelines, makes the edit, then updates the affected AGENTS.md files after meaningful changes. The audience is narrow but real: teams already using an agent that reads AGENTS.md files, working in a repository where directory-level rules differ enough to be worth writing down. It is not a linter, not a code generator and not a service. It is a convention plus a prompt.

How the docs tree is traversed and kept current

The mechanism is a filesystem hierarchy that mirrors your source layout. The root AGENTS.md carries two things: project-wide instructions and an index of the top-level areas. Each child AGENTS.md carries instructions local to that area, and the README describes the agent walking from the root down to the directory it is about to modify. That walk is the whole data flow. There is no index file to regenerate, no cache and no build step, because the index is just prose and links inside Markdown. The second half of the loop is maintenance: after meaningful changes the agent updates the affected AGENTS.md files. This is where DOX behaves differently from a static instruction file. A conventional AGENTS.md is written once by a human and slowly goes stale. DOX asks the agent to keep the tree current as part of the same task, which is why the project calls it self-documenting. The trade-off is visible immediately: you are trusting the same model that just edited your code to also edit the documentation describing that code. Nothing in the repository layout suggests a validation step, a schema or a check that the index still matches the directories on disk. If the agent skips the update, the tree drifts, and a stale child AGENTS.md is worse than no child file because the next run will treat it as authoritative.

Setting up DOX and running a first real edit

There is no installation. The README says this directly: no dependencies, no package, no runtime. DOX is the contents of the repository's own AGENTS.md file, copied into your project. If your project already has an AGENTS.md, the README's instruction is to copy the contents of the DOX file into it; if you do not have one, copy the file into the project root. The README gives a link to AGENTS.md in the repository as the file to copy, and the only prompt it supplies is the initialization line below, which you give to your agent rather than to a shell.

Initialize DOX tree for this project now.

What you should see afterwards is a root AGENTS.md containing project-wide instructions and a top-level index, plus child AGENTS.md files in the areas the agent decided to document. Check the diff before committing it. The README does not describe how the agent chooses which directories get a child file, so the shape of the tree is the agent's judgement on the first run, and reviewing that first diff is the cheapest moment to correct it. From then on, the intended workflow is unchanged: ask for a change in an area, and the agent should read the path from the root down to that area before editing.

What DOX does not do, and when it is the wrong tool

DOX has no enforcement layer. Nothing in the repository layout indicates a validator, a CLI, a pre-commit hook or a CI check, and the README does not document rollback if an agent rewrites a child AGENTS.md badly. Everything depends on the agent honoring the instructions it reads. If your agent only loads the root AGENTS.md and ignores nested ones, the entire tree is dead weight and you will have added several files that no run ever reads. That is the first thing to confirm before adopting it. The second limitation is cost. Walking a docs tree from the root to the target area consumes context on every task, and the root index grows as the project grows. A repository with a handful of directories and uniform conventions gains nothing from a hierarchy; a single well-written root AGENTS.md is cheaper and easier to keep accurate. DOX is also a poor fit for generated or vendored trees, where a child AGENTS.md would document code nobody edits by hand. And because the agent maintains the files, the quality of your AGENTS.md tree is only as good as the model writing it. There is no test that fails when a child file describes a directory that no longer exists.

DOX against a plain AGENTS.md file and against agent-zero

The honest alternative is the thing most teams already have: one AGENTS.md at the root, written and maintained by hand. The difference is purely structural. A single file keeps all instructions in one place, which means one file to review and one file to update, and it scales down perfectly. It scales up badly, because every local exception has to be written in a document that is read on every unrelated task. DOX moves those exceptions next to the code they govern, at the cost of more files and a maintenance loop delegated to the agent. Neither approach validates anything; both are just text the model may or may not follow. A second reference point is Agent Zero, the framework by the same creator, linked from the DOX README. Agent Zero is an agent framework, so it decides how the agent runs. DOX sits at a different layer: it is context for whatever agent you already use, and the README lists Codex, Claude Code and OpenCode as tools that support AGENTS.md files. If you are choosing how to run an agent, DOX is not the answer. If you have already chosen and want better local context, it is.

Maintenance, licence and what a DOX tree costs you over time

The repository was last pushed on 2026-09-01, so it is not abandoned, but the project is small enough that the maintenance question is really about your repository, not theirs. There are no releases to upgrade and no dependency to bump, which removes an entire category of maintenance work. The recurring cost is the docs tree itself: every directory that gains a child AGENTS.md is another file that can go stale, and the root index is another list to keep accurate. Because the agent is supposed to update them, the practical cost lands in code review. A pull request that changes behaviour in a documented area should also change the AGENTS.md beside it, and someone has to notice when it does not. The licence is MIT, which is permissive and places few obligations on reuse; the LICENSE file is the authority on the exact terms, and if you plan to redistribute the AGENTS.md contents inside a commercial product, read it rather than this summary. There is no separate licence for the instructions themselves as far as the repository layout shows.

Editorial conclusion

Adopt DOX if you already run an AGENTS.md-aware agent on a repository large enough that a single root instruction file is too coarse, and you are willing to review the child files the agent writes. Do not adopt it if you expect a tool that enforces anything: there is no CLI, no schema and no runtime, so nothing stops an agent from ignoring the tree. Before you commit, verify three things on your own repository: that your agent actually loads AGENTS.md files from subdirectories rather than only the root, that the root file's top-level index stays short enough to be read on every edit, and that the agent's own diff to the AGENTS.md files is something you are prepared to read in code review.

Frequently asked questions

Official sources

1. agent0ai/dox on GitHub
2. Issues
3. License: MIT
4. Project website
5. README