Show HN: Treedocs: Documentation that automatically checks for staleness

DandyLyons

Hi 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.

moralestapia

Why is @DandyLyons' comment flagged and dead? 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?

matneyx

Maaan, this seems so great except it's MacOS only.

miketromba

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.

tristanMatthias

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. [0] https://github.com/tristanmatthias/llmdoc