Show HN: Treedocs: Documentation that automatically checks for staleness

A handy code map wins fans, but the Mac-only catch and flagged post spark side-eye

TLDR: Treedocs is a new tool that keeps project notes matched to real files so teams can understand messy codebases faster and spot outdated documentation. Commenters loved the idea, but the real fireworks were over the post being flagged and the tool only working on Mac, which left some readers impressed and others annoyed.

A new tool called Treedocs landed on Hacker News promising to solve one of coding’s least glamorous headaches: figuring out what all the folders and files in a project actually do. In plain English, it creates a living map of a codebase, marks missing or outdated notes in red, and can even stop people from committing changes if the documentation has drifted out of date. It’s basically a house map for messy digital mansions — and the crowd was immediately split between “finally!” and “wait, why is this already weird?”

The biggest drama wasn’t even the tool at first — it was the thread itself. One commenter was baffled that the creator’s post got flagged, asking why a perfectly normal product demo was suddenly “dead.” That instantly gave the launch a faint free-speech-on-the-forum subplot. Meanwhile, another user delivered the classic buzzkill in five words: great idea, shame it’s Mac-only. For plenty of readers, that was the real scandal. If your shiny organizer only works on one kind of computer, is it a breakthrough or a gated party?

Still, the fans came in hot. One person praised the project’s “progressive disclosure” style — basically, revealing information step by step instead of dumping everything at once — and declared that bots love a good table of contents. Another jumped in with peak internet energy: “I made something similar too,” linking their own rival-ish tool for AI-assisted file summaries. So yes, Treedocs launched as a tidy documentation helper, but the comments turned it into a full-on mini-drama about platform lock-in, moderation mysteries, and whether AI needs cliff notes for your code.

Key Points

  • Treedocs is a Swift CLI that documents repository structure by rendering files and folders with human-readable descriptions.
  • The tool detects stale or invalid documentation entries by comparing `treedocs.yaml` with the filesystem and can warn or fail on drift.
  • Documentation is stored in a version-controlled `treedocs.yaml` file whose format is defined by a canonical JSON Schema.
  • Version 0.2.0 supports macOS 13 and newer and currently installs by building from source with a Swift 6-capable environment.
  • The article lists core commands for initialization, synchronization, display, validation, exploration, and updating repository documentation.

Hottest takes

"Why is @DandyLyons' comment flagged and dead?" — moralestapia
"Maaan, this seems so great except it's MacOS only." — matneyx
"Agents seem to love tables of contents." — miketromba
Made with <3 by @siedrix and @shesho from CDMX. Powered by Forge&Hive.