treedocs

Swift CLI

Understand any codebase faster with a documented tree for every file and folder.

treedocs demo video

Readable Tree Output

Just run treedocs to see the repository at a glance. Current files render green, while stale or invalid entries render red so problems stand out immediately.

✅ The treedocs below is up to date with the filesystem.
.
├── README.md  User-facing overview, installation, and command usage documentation.
├── Sources/  Swift package source code for the treedocs executable.
│   └── treedocs/  Main treedocs executable target.
│       ├── Commands/  ArgumentParser command implementations for treedocs subcommands.
│       └── Core/  Core services for loading, scanning, rendering, and updating treedocs data.
├── site/  Static files deployed to the project GitHub Pages site.
│   ├── index.html  Landing page for the treedocs GitHub Pages site.
│   └── styles.css  Stylesheet for the treedocs GitHub Pages landing page.
└── old-file.swift  Stale entry: no matching path exists on disk.

Acclimate Faster

Give new teammates, future you, and coding agents the concise context they need to understand complex repositories so that they don't need to wander aimlessly.

Stay Current

Keep documentation from going stale with automatic drift checks that warn or fail. You can even install a Git pre-commit hook so that you never commit undocumented changes.

Review With Context

Store simple, human-readable, version-controlled summaries in treedocs.yaml so reviews are easier and agents spend fewer tokens rediscovering project structure.

Installation

treedocs currently supports macOS 13 and newer. Version 0.2.0 is source-build only, so installing through Homebrew, Mint, or mise requires a Swift 6-capable build environment, usually Xcode 16+.

mise

MISE_EXPERIMENTAL=true mise use -g spm:DandyLyons/treedocs@0.2.0

mise uses its Swift Package Manager backend. treedocs does not currently publish artifact bundles, so mise builds from source. The mise spm: backend is currently experimental, so set MISE_EXPERIMENTAL=true when installing.

Homebrew

brew install DandyLyons/tap/treedocs

The Homebrew formula builds treedocs from source through the DandyLyons tap.

Mint

mint install DandyLyons/treedocs@0.2.0
mint run DandyLyons/treedocs@0.2.0 --help

Mint builds the Swift executable package from the tagged GitHub source.

Quick Start

treedocs init      # Create a treedocs.yaml file
treedocs sync      # Synchronize treedocs.yaml with your current folder structure and check for errors.
treedocs show .    # Show the documented tree
treedocs check     # Check for errors in treedocs.yaml.
treedocs explore . # Progressive disclosure exploration of the codebase. Perfect for agent exploration.

The treedocs.yaml Schema

treedocs.yaml is a version-controlled map of your repository. It mirrors your file tree and stores a human-readable YAML description for every file and folder. This same description can be parsed and displayed with treedocs' rich tooling. The file format is defined by a canonical JSON Schema, which means editors, CI tools, and AI agents can all parse, validate, and understand the same structure.

Keeping docs up to date is an ongoing task, but treedocs makes it easy! Running treedocs sync updates your treedocs.yaml file, adding new paths and removing ghost paths. All that's left to do is add short descriptions. It's easy to update descriptions with treedocs update.

Or simply ask an agent to fill in your treedocs.yaml file for you. Agents are extremely good at filling in descriptions and everything can be validated with treedocs check.