Big Idea

The argument in one line.

AI coding agents fail on large codebases not because they lack intelligence, but because they lack context — and a tree of co-located AGENTS.md files gives them a map to navigate precisely to the right change without polluting the context window with everything else.

Who This Is For

Read if. Skip if.

READ IF YOU ARE…

You're using AI coding tools (Codex, Claude Code, Cursor, etc.) on a codebase larger than a weekend project and the agent keeps creating duplicate functions or putting code in the wrong place.
You've tried stuffing your entire repo into an AI's context window and found it made hallucinations worse, not better.
You maintain a multi-folder project and want agents to follow existing conventions without you narrating them in every prompt.
You want to know how the Agent Zero team built Space Agent — a large browser-runtime AI — entirely with AI coding tools in three weeks.

SKIP IF…

You're only working on small single-file scripts — the framework pays off at folder-depth, not file-count.
You want a packaged tool with a CLI installer — DOX is just Markdown files and conventions, not a product you install.

TL;DR

The full version, fast.

AI coding agents aren't making dumb mistakes because the underlying models are weak — they're making dumb mistakes because they can't see the whole codebase. DOX fixes this by placing an AGENTS.md file inside every meaningful folder of your repo, each documenting that folder's purpose, rules, and a child-docs index pointing further down the tree. When the agent needs to make a change, it starts at the root, reads only the path it needs, and arrives at the target folder with exactly the right context — no more, no less. The agent also updates the docs after every edit, keeping the map in sync with the actual code. There's nothing to install: you copy the DOX framework text into your existing AGENTS.md and tell the agent to index the repo.

Free for members

Chat with this breakdown — free.

Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.

Create a free account →

Chapters

Where the time goes.

00:00 – 01:00

01 · Hook — the context-awareness problem

Framing: AI agents aren't dumb, they're context-blind. Symptoms (wrong place, duplicate code, bloat) and the real question — minimum context, not maximum context.

01:00 – 03:05

02 · Origin: Space Agent

Why DOX was invented — Space Agent is a large, feature-rich browser AI built 100% by agents. The AGENTS.md hierarchy was the pattern that kept it coherent. Three weeks from blank repo to published.

03:05 – 07:00

03 · How the DOX tree works

Root AGENTS.md → child docs index → subfolder AGENTS.md files. Each file documents one domain. Agent traverses top-down, accumulates context from parents, reads only the path it needs. Updates docs after edits so the map stays current.

07:00 – 09:50

04 · Walking the Agent Zero codebase live

Live demo: root AGENTS.md → agents, API, configuration, docker subfolders. Memory plugin, agent profiles, child docs index shown. OCR reveals the exact DOX section format: Purpose, Ownership, Local Contracts, Core Guidance.

09:50 – 13:10

05 · Initializing DOX on an undocumented repo

Terminal demo with Codex CLI. Copy DOX AGENTS.md text → paste into project AGENTS.md → tell agent 'initialize docs index'. Agent crawls codebase, writes AGENTS.md in each subfolder, links them together. Takes ~5 minutes for a medium repo.

13:10 – 16:00

06 · Customizing documentation granularity

Enhancing the screen docs — telling the agent to create a per-file markdown doc for every Python file in a folder. The rule goes into that folder's AGENTS.md only, scoping it precisely. Any folder can have its own docs strategy.

16:00 – 18:20

07 · Live edit demo — agent reads docs before touching code

Ask Codex to change a plugin screen background to red. Agent explicitly says it will re-read the applicable DOX chain before editing. Navigates to the right TCSS file, makes minimal change, updates docs. Shows agent reading, not guessing.

18:20 – 19:08

08 · CTA — star, subscribe, copy and use

How to use in any AI agent that supports AGENTS.md (Agent Zero projects, Codex, Cursor, etc.). Clone the DOX repo or paste from GitHub. Star request (41 stars at time of recording).

Atomic Insights

Lines worth screenshotting.

AI coding agents don't fail because the model is too dumb — they fail because they can't see the full codebase structure at once, so they guess.
The real question isn't 'how do we give the agent more context?' — it's 'how do we give it exactly the minimum context it needs?'
A tree of AGENTS.md files is a map: the agent reads only the path from root to target, not every sibling branch.
Tightly coupling documentation to the code it describes (same folder) makes it far more likely to stay accurate than a wiki or README far from the code.
Parent AGENTS.md files hold high-level rules (conventions, architecture) that cascade down to every child; the agent accumulates both layers as it traverses the tree.
An agent that updates documentation after every edit turns the docs into a self-healing artifact — the next agent run starts from a current map.
Space Agent — a large browser-runtime AI with time-travel and user management — was built entirely by AI agents in about three weeks using this documentation pattern.
You can customize documentation granularity per folder: some folders get one AGENTS.md for the whole directory, others get one per file — the rules live in the AGENTS.md of that folder.
Shared utilities in one branch of the tree can be linked from sibling branches via the AGENTS.md, so the agent doesn't have to guess that helpers exist.
There is no install, no package, no vector store, no database — just Markdown files the agent already knows how to read and write.

Takeaway

Give your agent a map, not a dump.

CONTEXT DESIGN

The reason AI coding agents bloat and break large codebases is almost never model quality — it's that they're handed the whole map at once instead of a navigable path to the one folder that matters.

Placing a small AGENTS.md in each meaningful subfolder gives the agent a tree it can traverse — it reads only the path from root to target, so parent conventions cascade down without overwhelming the context window.
An agent that updates documentation after every edit turns the docs into a self-healing artifact — the next run starts from a current map, not a stale one from the initial setup.
Granularity is tunable per folder: one AGENTS.md for the whole directory is fine for stable folders; per-file markdown makes sense for high-traffic folders like helpers or screens.
Shared utilities don't need to live in every branch — you link them from the relevant AGENTS.md files, so the agent can find them without guessing they exist.
There's nothing to install: copy the DOX framework text into your existing AGENTS.md, tell your coding agent to index the repo, and it builds the full documentation tree automatically in roughly five minutes.
The same pattern works across agents — Codex, Claude Code, Cursor, or any tool that reads AGENTS.md — because it's just Markdown with a convention, not a proprietary plugin.

Glossary

Terms worth knowing.

DOX: A self-documenting AGENTS.md framework that attaches a small Markdown documentation file to every meaningful folder in a codebase, creating a tree the AI agent can navigate to reach the right context precisely.
AGENTS.md: A Markdown file placed in a project's root (and optionally subfolders) that AI coding tools read as persistent system context. DOX uses a hierarchy of these files — one per folder — rather than a single monolithic file.
Child DOX Index: A section at the bottom of each AGENTS.md file that lists the documentation files of that folder's direct subfolders, allowing an agent to walk the tree one level at a time.
Space Agent: An AI agent that runs entirely in the browser runtime, can execute code and build UIs on the fly, and was developed entirely by AI coding tools using the DOX framework — the project that originated the approach.
Context window: The fixed amount of text an AI model can read at once per request. DOX is explicitly designed to minimize unnecessary content in this window by giving the agent a targeted path rather than a full dump.
Codex CLI: OpenAI's command-line coding agent. Used in the demo to initialize a DOX index on an undocumented repository by pasting the DOX AGENTS.md text and telling the agent to crawl the codebase.

Resources

Things they pointed at.

02:10productSpace Agent (space-agent.ai) ↗

03:05linkDOX GitHub repo (agent0ai/dox) ↗

09:10linkAgent Zero Connector repo ↗

09:30toolCodex CLI (OpenAI)

19:00linkAgent Zero Skool community ↗

Quotables

Lines you could clip.

01:18

“The issue is not intelligence. It's context awareness. Your LLM is already smart enough to do any programming work better than you can. But where it fails is maintaining large code bases — it doesn't see behind the corner.”

Reframes the entire AI coding frustration in one sharp sentence — shifts blame from model to context design→ TikTok hook↗ Tweet quote

01:52

“The question is not how do we give it more context. The question is how do we give it exactly the right amount of context it needs. Not more, not less, minimum context required to make the minimal edit.”

Quotable philosophy on context engineering — counters the naïve 'bigger context window = better' assumption→ IG reel cold open↗ Tweet quote

05:32

“These markdown files are like a preview of the whole code base. It's like a map for the agent — and the agent only navigates the map until the point it needs to touch the actual code.”

Clean analogy that explains the whole system in one sentence→ newsletter pull-quote↗ Tweet quote

The Script

Word for word.

Read-along

Don't just watch it. Burn it in.

See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.

metaphor

00:00Welcome. Today I'm about to show you how you can leverage a single small Markran file to fix your AI coding agent's biggest issue ever.

00:09My name is Jan. I'm the developer of AgentZero and SpaceAgent, and today, I will show you how to properly use docs.

00:16It is extremely simple. No installation. No requirements.

00:19And the best part is that it actually fixes the issue. So now what is the issue?

00:26Obviously, is the reliability of coding AI agents. And we all know the symptoms. You give your AI agent the task.

00:33It will do the task, but in a wrong place, breaking your conventions, duplicating functionality instead of extending a function that could have just one line added, it will create a brand new helper module, etcetera.

00:46Your code base will bloat, and this makes things even worse for the future. And you know how this ends.

00:53Right? Never ending cycles of debugging, fixing one thing breaks another, your agent is confused from all the code, etcetera.

01:01So now I will show you what docs actually is, why is it so simple and why it works so well, why did we develop it, and how can you use it in your project. So first, we need to identify what is the real problem here.

01:17The issue is not intelligence. It's context awareness. Because your agent is already smart enough.

01:24Your LLM is smart enough to do any programming work better than you can. But where it fails is maintaining large code bases. Because it doesn't see behind the corner.

01:36It does not know the context of your full code base. And that's why it makes these simple mistakes because it simply cannot see the big picture.

01:46And throwing more tokens at it, that's not a solution. The question is not how do we give it more context. The question is how do we give it exactly the right amount of context it needs?

01:59Not more, not less, minimum context required to make the minimal edit, and that's it. Now to understand why did I develop docs, we need to take a look at Space Agent because this is where it started.

02:14Space Agent, if you don't know what it is, it's an AI agent that runs completely in the browser runtime.

02:23It can execute code. It can generate its own UIs on the fly.

02:28It can communicate to external services. You tell it to build you something. It will build it on the fly right away in the browser.

02:35And it has a ton of advanced features like, uh, user management, uh, groups. It is extensible in many, many ways.

02:44It has a large code base, a lot of layers, a lot of concepts, a lot of cool features like the time travel, and it was completely developed by AI. I didn't write a single line of code on this project, and it took me about three weeks to completely develop, polish, and publish this.

03:04And so since the very beginning, I knew that I cannot be writing code here. It's not possible in 2026.

03:11You need to have a team of agents that will do this for you, but you need them to do it reliably and to write good quality code, maintain maintain the right principles and best practices, etcetera.

03:24And so the very thing I did inside Space Agent was creating this agents dot m d file, where back then it wasn't called docs framework.

03:38It was just the first prototype of a self documenting framework built specifically for the Space Agent project. But it was mostly what Docs Framework is now. It explained to this agent to read documentation before editing, update documentation after editing, maintain the documentation in a hierarchy corresponding to the code base, and how the documentation should look like.

04:09So like we say here, docs is a self documenting agents dot m d framework. The big difference here is that it's not a single agent's dot m d file.

04:23It's not a documentation that's detached from the code base somewhere, what we are used to. A lot of projects have their documentations in a wiki somewhere or in separate folder.

04:34Here, we tightly couple the documentation with the code base. And I can show it to you here.

04:46This is the code base of agent zero, for example. It's a very large project, very large code base, very deep.

04:54And it all starts with the top level agents dot m d file.

05:01Here we have our origin original agent zero instructions, and somewhere here starts the docs framework, which is one of the beauties of it.

05:11You can simply take the markdown from the GitHub repo, copy paste it into your existing agents dot m d. It does not mess up your existing instructions.

05:20It just adds the, let's say, responsibility to your agent for the documentation.

05:29Now the agent knows that it needs to crawl the hierarchy of agents dot m d files because each agents dot m d is created in every subfolder throughout the codebase except for some temporary files and garbage, etcetera.

05:50And every agents dot m d file is responsible for a single domain, a single folder, but it contains a child docs index.

06:00And we are now in the top level agents dot m d. And here we have our subfolders agents, API configuration, docker, etcetera.

06:09Each of these have their own agents dot md files inside that document that one specific domain. And for example, in the agents, we will once again find child docs index at the end, documenting individual agents inside of the system.

06:29And why this tree structure is so important is that this way, the agent can always take the fastest, most straightforward path to the place where it needs to make the changes.

06:44So if I tell the agent, uh, create an API endpoint for me, right in the top agents dot m d file that the agent can see at all times, it can see that there is a documentation for API endpoints.

07:04Here is a short description, HTTP API handlers and WebSocket handler entry points. The agent will open that file, read about the purpose ownership, local contracts, aka rules, work guidance, how to test and verify.

07:20So the agent can quickly navigate to the relevant place, make the minimal edit, and most importantly, after any edit, update the documentation files, which keeps the documentation in sync with the actual code base.

07:36And I know this may seem like a simple concept. It actually is. And it may be hard to believe that this actually brings any real benefits to AI agents.

07:45But the difference between the input and output, what I mean is the size of the addition to your code base, no installation required, no manual work, and the output in terms of code quality and agent efficiency is so disproportional here that we had to release this as a standalone product.

08:09I say product, but of course, it's open source, just go and copy paste it. And we can probably best see it on the Space Agent itself, which was completely AI coded.

08:20We can take a look at the top level agents MD, and it will point us to the front end application, commands, packaging, server test.

08:30We can take a look into the server documentation, for example.

08:40And this will point us further into API endpoints, jobs, library, pages, router, runtime.

08:54You get the idea. Everything is thoroughly documented. The agent updates all the relevant documentation, not just the closest agent's MD file to where the agent does the edits, but also the parents if that is relevant.

09:09So if we change something about the concept, if I tell the agent that I want him to use different coding practices, different styling, formatting, whatever, it can update this in the parent files, agents dot m d, and this will be reflected anywhere down the tree.

09:32Because as the agent navigates the documentation hierarchy from top to bottom, it will keep in the context window all the information and instruction from the parents agent MD files and all the detailed instructions from the end of the tree.

09:48So once we get once we get deep enough like into, I don't know, maybe jobs, here we should have more specific instructions, function names, etcetera to the problem at hand in this folder.

10:06But in the parents, in the server, for example, we will have higher level instructions where to put stuff, how to work, how to organize code, etcetera.

10:19And all of this compounds as the agent traverses the tree. So no information is lost.

10:27Even if even if something is in a different branch of the tree, it can still be linked in the docs index or in one of the sections above.

10:38If you have a shared functionality like helpers, they can be in a different part of the tree and the agent can still link them together using these markdown files. So these markdown files are like a preview of the whole code base.

10:54It's like a map for the agent, and the agent only navigates the map until the point it needs to touch the actual code. And so we don't pollute the context window with any unrelevant information.

11:10It can see all of the documentation files on the path to the target.

11:17It doesn't see any of the sibling folders unless they are manually linked because they are relevant. Okay.

11:25Enough talking, I guess. I can show you how you can implement this into your own repository. It's it's very simple.

11:34All you need to do is open the agents dot m d from the docs repository. Simply copy the file, and let's go to terminal.

11:46Alright. I am in my terminal. I have cloned our agent zero connector.

11:51That is a repository that is not yet documented. So I will now simply start codex here, and I will tell codex add this at the end of agents m d here or create.

12:12I don't know if there's already agents dot m d in this repo. I don't really care. Codex will take this, add it at the end of the agents m d.

12:23And then I can tell it now initialize the docs index.

12:33Okay. I'm gonna put this to queue.

12:37And so now agents dot m d is either created or edited with the docs framework appended at the end.

12:47And so now codex will understand what docs means because agents dot m d is always included in the system prompt or in the context window.

13:00And now that I have told it to initialize the docs index, it knows what to do. It will start reading through the code base and creating this agents dot m d documentation points throughout the repository and linking these files together.

13:18It will probably take a few minutes because the LLM needs to read through all of the code base or most of the code base and manually write these documentation files.

13:30But in a bit, we should be able to see the first result.

13:36Okay. So it took about five minutes to index the existing code base.

13:42This is not a particularly large one. These are the agents md files created in the sub folders for dev tools documentation, for the source, for different screen styles, etcetera.

13:54So let's see how it went.

13:59Okay. So this is the top level agents m d. There were some instructions and links previously, so docs will start somewhere here.

14:10Here we have it. And here we have the child docs index.

14:17So we can take a look into, let's say, source, screens. And here we have the ownership, parent package, rules control, app integration, commands protocol.

14:29Screens should return typed results data classes or none, and no children under screens.

14:38We can enhance this. I can tell Codex, I want to enhance the documentation of screens.

14:46I want all the Python files in the screens folder to have their own documentation. The same file name with markdown appended at the end.

14:57And they will document individual screens and they will be listed as child docs indices in their parent documentation file.

15:11And just like that, if we have something in our project that is not separated enough, like in agent zero, we, for example, have a helpers folder which contains maybe a 100 scripts by now, we can do it like this.

15:28We don't need to separate it into subfolders. We can simply tell the agent we want to change the documentation structure for this particular folder.

15:39We want to document each of these files individually. And it will simply put the rule into this agents. Md file, which will make it be applied only for this folder, and this folder can have its individual files documented separately.

15:55We can do this for any folder throughout the repo. We can tell the agent we want to do this for every single folder for the repo, and in that case, the agent would put it into the top level agents m d. It's up to us.

16:09The framework is really simple and customizable. You can simply tell the agent that you want to do something differently, and it will apply it to the correct agent m d files, and we can see the update here.

16:22So the agent m d in screens was updated. Somewhere here, it tells that every Python module in this folder must have a sibling markdown document.

16:34And just like that, every file in this folder is now documented. And let's do some edit.

16:42What do we have here? We have installed plugins.

16:49Okay. I'm gonna tell the agent that I want to change something in the plugins view.

16:55I wanna change the plugins view to have a different background color than the others.

17:02Once the user opens that screen, I want the background to change from black or whatever we use now to red.

17:13And obviously, I I have no intention in in keeping this edit. I just want to demonstrate how will codecs proceed.

17:27I will update the installed plug in screen styling. I will reread the applicable DOCSHIN. This is the important part.

17:34That the agent will read the DOCSHIN because it may have been changed. So it will start from the top, read through all the documentation, find the right documentation file for the plugins screen.

17:49I am looking at the existing installed plugin selectors now. The likely change is in a screen scoped TCSS rule.

17:57I have no idea what it's talking about, but now it has all the documentation. I don't need to worry about it.

18:07Right. So we have changed the installed plug in screen backdrop to red. The inner plug in stays dark.

18:15Updated the markdown documentation and verify the syntax. And of course, this is compatible with any AI agent that supports agents.

18:27Md. In agent zero, you can do this in projects, for example. When you create a new project, you can put it directly to the project instructions, or you can create it as an agents dot m d file inside that project.

18:43The agent will see it, or you can simply tell your agent to clone agent zero a I slash docs repository into your current workspace.

18:53It will do it for you. So this is the life changing Margrana file you've been looking for. You can thank me later.

18:59You can give us a star. We only have 41 of these by now. It's really fresh.

19:03You can subscribe to our channel if you like what we do, and see you next time.

The Hook

The bait, then the rug-pull.

The promise is blunt: one small Markdown file, no installation, no package, no server — and it actually fixes the reliability problem that drives AI coding agents off the rails on large codebases. Jan, the developer of Agent Zero and Space Agent, has already stress-tested it by building a full browser-runtime AI platform entirely with AI coding tools in about three weeks.

Frameworks

Named ideas worth stealing.

03:05model

DOX — self-documenting AGENTS.md hierarchy

Root AGENTS.md defines global rules + child docs index
Each subfolder gets its own AGENTS.md documenting that domain
Each AGENTS.md includes: Purpose, Ownership, Local Contracts, Core Guidance, Child DOX Index
Agent reads top-down, accumulates parent context, reads only the path to the target
Agent updates relevant AGENTS.md files after every edit

A tree of co-located Markdown files that act as a navigable map of the codebase. The agent reads only the path from root to the folder it needs to touch — no sibling branches, no full dump.

Steal forAny project where you want an AI coding agent to follow conventions, avoid duplication, and stay in the right layer of the codebase

CTA Breakdown

How they asked for the click.

VERBAL ASK

18:30subscribe

“You can give us a star. We only have 41 of these by now. It's really fresh. You can subscribe to our channel if you like what we do.”

Humble and honest — no fake urgency, acknowledges the project is brand new. Works because the product is free and the bar to act (starring a repo) is low.

MENTIONED ON CAMERA

02:10productSpace Agent (space-agent.ai) ↗

03:05linkDOX GitHub repo (agent0ai/dox) ↗

09:10linkAgent Zero Connector repo ↗

19:00linkAgent Zero Skool community ↗

FROM THE DESCRIPTION

PRIMARY CTAWhere the creator wants you to go next.