Treedocs: Documentation that automatically checks for staleness

Treedocs is a Swift-based command-line interface (CLI) tool designed to eliminate documentation rot by mirroring a repository's file structure into a version-controlled treedocs.yaml file. By linking human-readable descriptions directly to filesystem paths, the tool enables developers to detect stale documentation and provide high-density context to both new teammates and AI coding agents.

Automated Drift Detection and Validation

Treedocs ensures documentation remains accurate by treating the filesystem as the source of truth. The tool identifies "stale" or "invalid" entries—paths listed in the documentation that no longer exist on disk—and highlights them in red during rendering.

To maintain this synchronization, Treedocs provides several key commands:

• treedocs sync: Reconciles the treedocs.yaml file with the current folder structure, adding new paths and removing ghost paths.
• treedocs check: Validates the YAML file for errors, including stale entries or missing descriptions.
• treedocs update: Allows for the efficient updating of existing descriptions.

Developers can integrate these checks into their workflow via Git pre-commit hooks to prevent undocumented changes from being committed to the repository.

Optimizing Context for AI Agents

Treedocs is specifically engineered to reduce token consumption and improve the efficiency of AI coding agents. Rather than forcing an agent to rediscover a repository's structure through repeated file listing, Treedocs provides a concise, structured map of the project.

Progressive Disclosure

The treedocs explore command implements a progressive disclosure system. This allows agents to explore the codebase incrementally, accessing only the necessary levels of detail. As noted by community members, this approach can be more performant than standard semantic or encoding-based RAG (Retrieval-Augmented Generation) systems because agents effectively utilize these "tables of contents" to navigate complex structures.

Standardized Schema

The treedocs.yaml format is governed by a canonical JSON Schema. This standardization ensures that editors, CI tools, and AI agents can parse and validate the project structure using a consistent, machine-readable format.

Installation and Requirements

Treedocs version 0.2.0 is currently source-build only and requires a Swift 6-capable build environment (typically Xcode 16+). It is supported on macOS 13 and newer.

Installation options include:

• Homebrew: brew install DandyLyons/tap/treedocs
• Mint: mint install DandyLyons/treedocs@0.2.0
• mise: MISE_EXPERIMENTAL=true mise use -g spm:DandyLyons/treedocs@0.2.0 (utilizing the experimental Swift Package Manager backend).

Community Insights

While the tool is praised for its approach to codebase acclimation, some users have noted platform limitations:

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

Other developers have highlighted the utility of similar LLM-focused documentation tools, such as llmdoc, which uses file hashing and LLM summaries to help models like Claude or Codex explore repositories without loading every file into the active context window.