DOX: an AGENTS.md convention that makes the agent read before it edits
Self-documenting AGENTS.md
At a glance
- What is it?
- DOX is not a package or a runtime. It is a Markdown instruction file that defines a hierarchy of AGENTS.md files, a traversal rule for reading them, and an update rule for keeping them true. The discipline is the product.
- Who is it for?
- Adopt DOX if your repository is large enough that a single root AGENTS.md has become a junk drawer of unrelated rules, and if you are willing to review AGENTS.md diffs the same way you review code diffs. Skip it for small repositories where one file already fits in the agent's context, and for any workflow where you will not enforce the update step, because a stale child file is worse than no child file.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem DOX targets: agents editing files they never read about
A coding agent dropped into a repository has one context window and no local etiquette. The README describes the project to humans. The build files describe the build. Neither says that the files under services/billing follow a different migration rule than the files under services/auth, or that a particular directory holds generated code that should not be hand-edited. The agent infers, guesses, and sometimes edits the wrong layer. The README's own framing is blunt about the symptom: less guessing, less drift, less "why did it touch that file?"
DOX is aimed at the person who already maintains a root AGENTS.md and has watched it grow into a list of rules that apply to some directories and not others. It is also aimed at teams running several agents (the README names Codex, Claude Code and OpenCode as tools that read AGENTS.md files) that need the same local rules to reach all of them without a per-tool configuration file. The scope is deliberately narrow: project context for edits, nothing about running the agent, nothing about CI.
The mechanism: a docs tree, a root-to-target walk, and an update pass
DOX has three moving parts and no code. The first is structure. A root AGENTS.md holds project-wide instructions plus a top-level index. Child AGENTS.md files hold local instructions for specific areas. The index is what makes the tree traversable: without it, the agent has files but no route.
The second is the read rule. Before any edit, the agent walks the docs tree from the root down to the area it is about to touch. That walk is the whole point. The agent is not asked to read everything; it is asked to read the chain of documents that govern the target path, so the local guidelines are in context at the moment of the edit.
The third is the write-back rule. After meaningful changes, the agent updates the affected AGENTS.md files. This is what the repository name refers to: the documentation is meant to be maintained by the same loop that changes the code.
Read the three parts together and the design constraint becomes visible. The quality of the system depends on the index staying accurate. If a child file exists but is not linked from its parent, the walk never reaches it, and the local rules are effectively invisible. DOX does not ship a linter or a checker that would catch that. The README describes the loop; it does not describe a verification step for the loop.
Getting it running: one copy, one sentence, no install
The README's instructions are short. Copy the contents of the repository's AGENTS.md into your project's AGENTS.md file. The README states there is no installation, no dependencies, no package and no runtime, and that DOX is just a Markdown instruction for AI agents. The repository's own AGENTS.md is the artifact you copy, not a generated file.
For a project that has no AGENTS.md yet, the same copy goes into the project root, and the README says the agent will see the instructions and start building the DOX tree. For an existing project, the README gives the bootstrap prompt verbatim: Initialize DOX tree for this project now. The README states that the agent will then create all the child AGENTS.md files and indexes.
There are no config keys, no CLI flags and no environment variables to document, because there is no executable. The only inputs are the copied Markdown and the agent's willingness to follow it. That also means the trigger is agent-dependent: the README lists Codex, Claude Code and OpenCode as tools that support AGENTS.md, and says it works with any agent that supports AGENTS.md files. If your tool does not read AGENTS.md at all, DOX has no delivery path.
Where DOX breaks: the bootstrap pass and the stale child file
The bootstrap prompt is the weakest link. Initialize DOX tree for this project now asks an agent to invent a directory taxonomy for a codebase it has just met. Nothing in the README specifies a maximum depth, a naming rule, or a criterion for when an area deserves its own file rather than a paragraph in its parent. Two runs on the same repository can produce different trees, and a tree that is too granular makes the root-to-target walk expensive while a tree that is too coarse leaves the local rules in the root file, which is the problem DOX was meant to solve.
The second failure mode is drift in the other direction. The README says the agent updates affected AGENTS.md files after meaningful changes. Meaningful is not defined. An agent that judges a refactor to be routine will leave the child file describing the old layout, and the next agent will read that stale file with the same confidence as a fresh one. A wrong local rule is worse than a missing one, because it is followed. Nothing in the supplied material describes a staleness check, a timestamp convention, or a hook that fails when a directory changes without its AGENTS.md changing.
The third case is scale in the wrong direction. On a small repository, a single root AGENTS.md already fits in context, and splitting it adds a traversal step and a second file to maintain for no gain. DOX is the wrong tool when one file is enough.
Compared with AGENTS.md alone, and with a generated docs site
The nearest alternative is a plain single AGENTS.md: one file at the repository root, no index, no children, no traversal rule. The difference is not the format, since both are Markdown, but the addressing. A single file has to serve every directory at once, so its rules tend to be either global and vague or local and buried. DOX adds an index and per-area files so the agent reads the rules for the path it is editing. The cost is that the index and the children must be kept in sync, and a single file has no such obligation.
A second alternative is generated documentation, where a tool reads the source tree and emits reference pages. That approach is accurate about what exists and silent about what is allowed. DOX is the inverse: it carries intent and conventions, which no generator can infer from the code, and it depends on an agent to keep it current, which no generator needs. If your problem is that nobody knows what a module does, generation is the better fit. If your problem is that the agent keeps making edits that are locally wrong, DOX addresses that and generation does not.
Maintenance cost, licence, and the review burden DOX creates
DOX shifts work rather than removing it. Every meaningful change now has a documentation diff attached, and that diff lands in the same pull request as the code. The README's loop makes the agent responsible for producing it, but a human still has to review it, because an agent-authored rules file that nobody reads is a silent source of wrong instructions. The practical cost is proportional to the number of child files: each one is a file that can go stale, and each one has to be linked from its parent to be reachable at all.
The repository is MIT licensed, which permits use, modification and redistribution with the licence and copyright notice retained. That is a permissive fit for copying the AGENTS.md text into a commercial repository. This is a description of the licence, not legal advice; if the file is redistributed inside a product, check how your organisation handles notice retention.
The repository shows no releases, so there is no version to pin and no changelog to read before upgrading. Updating means re-reading the upstream AGENTS.md and deciding whether your local copy should absorb the changes, and since your copy has probably been edited to fit your project, that comparison is manual. The README's credit line points to Agent Zero, the agentic framework behind the project, which is the natural place to look for how the convention is expected to evolve.
Who should copy the file, and what to check before you do
Copy DOX into a repository when a single root AGENTS.md has stopped being enough: when the rules for one area contradict the rules for another, when reviewers keep catching the same locally wrong edit, or when several agents need the same conventions. Do not copy it into a small repository, and do not copy it into a workflow where AGENTS.md changes will be merged without review, because the update rule is the part that decays first.
Before the first run, verify three things. Open the upstream AGENTS.md and read the instruction text yourself, since that text is the entire product. Confirm that your agent loads a root AGENTS.md automatically, because the README's compatibility claim is a list of tools, not a guarantee for yours. Then decide the depth limit for the tree and write it into the root file before issuing the Initialize DOX tree prompt, so the first bootstrap does not produce a structure you have to unwind. If the resulting tree has a child file that no parent index links to, the walk will not reach it, and the local rules in it may as well not exist.
Editorial conclusion
Adopt DOX if your repository is large enough that a single root AGENTS.md has become a junk drawer of unrelated rules, and if you are willing to review AGENTS.md diffs the same way you review code diffs. Skip it for small repositories where one file already fits in the agent's context, and for any workflow where you will not enforce the update step, because a stale child file is worse than no child file. Before copying AGENTS.md into your project, read the file itself end to end, confirm your agent actually loads root AGENTS.md automatically, and decide who owns the child files under directories the agent rarely touches.
Community notes