I built treedocs, a CLI that shows a tree of your file structure, side-by-side with docs.
The idea is simple: your filesystem already tells you what exists, but not what each path is for. treedocs mirrors the file tree into a treedocs.yaml file and lets you define short descriptions, references, and links to files and folders. It can then render that back as a documented tree, detect drift when files move or disappear, and fail checks when descriptions are missing.
I originally wanted this for two related problems:
1. Helping humans acclimate to unfamiliar repositories faster.
2. Giving coding agents concise project context without forcing them to rediscover the repo structure over and over.
Some things it does:
- treedocs init creates a treedocs.yaml
- treedocs sync reconciles it with the filesystem
- treedocs check catches stale entries and missing descriptions
- treedocs explore implements progressive disclosure for efficient token usage.
- Nested treedocs.yaml files act as documentation boundaries for delegated subtrees
- The YAML format is backed by a public JSON Schema
I’d be interested in feedback on the file format, CLI ergonomics, and whether this kind of repo-level map is useful for your workflows.
This is very good - I have found that well-designed progressive disclosure systems like this tend to be far more effective and performant than cookie-cutter semantic / encoding-based RAG systems. Agents seem to love tables of contents.
I made a similar kind of tool [0] to scratch this itch too. Hashes all your files and adds a short llm summary for each one so Claude/Codex can quickly explore rather than load all those files into context.
7 comments
[ 2.8 ms ] story [ 23.5 ms ] threadI built treedocs, a CLI that shows a tree of your file structure, side-by-side with docs.
The idea is simple: your filesystem already tells you what exists, but not what each path is for. treedocs mirrors the file tree into a treedocs.yaml file and lets you define short descriptions, references, and links to files and folders. It can then render that back as a documented tree, detect drift when files move or disappear, and fail checks when descriptions are missing.
I originally wanted this for two related problems: 1. Helping humans acclimate to unfamiliar repositories faster. 2. Giving coding agents concise project context without forcing them to rediscover the repo structure over and over.
Some things it does: - treedocs init creates a treedocs.yaml - treedocs sync reconciles it with the filesystem - treedocs check catches stale entries and missing descriptions - treedocs explore implements progressive disclosure for efficient token usage. - Nested treedocs.yaml files act as documentation boundaries for delegated subtrees - The YAML format is backed by a public JSON Schema
I’d be interested in feedback on the file format, CLI ergonomics, and whether this kind of repo-level map is useful for your workflows.
Like ... what's wrong with what he posted?
I've seen thousands of Show HNs here, for like a decade. Very similar to this.
What rule did he break?
[0] https://github.com/tristanmatthias/llmdoc
Curious about why did you choose swift for this project?