alt Hacker NewsHi HN,
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.
Replies
This is lovely! I'd done something similar in my own setup.
I'm curious what your experience has been with fork/merge – why a monolithic file rather than something more diffuse?
The question is who maintains it. I think, LLM is the only practical option. In my agent rules, I tell it to maintain INDEX.md on each level. That takes 1 line of instruction and starting with an example file. Then, it self-maintains.