dirmd

Generate markdown documentation from directory structure. Optimized for LLM ingestion.

Install

go install git.flo.fo/FLO/dirmd@latest

Linux only. Run dirmd -h for all flags.

Why

LLMs don't need 40k tokens of preamble. dirmd dumps a repo as markdown: tree + file contents, minus the noise. Everything filtered out stays visible in the tree (~ tests omitted, ~ ignored) so nothing vanishes silently — the model knows what exists and can ask for it.

Three ways to use it

One file — small repos. For small projects that fit in a context window comfortably:

dirmd -o out.md ~/repos/myproject

Everything lands in a single markdown file. Simplest, works fine until it doesn't.

Vertical slices — large repos. Once a single file gets too big to paste repeatedly, split it:

dirmd -o docs ~/repos/myproject --vertical-slices

This produces an index file (metadata + full tree + slice table) and one file per top-level directory. The full tree exists only in the index; every other file carries a one-line breadcrumb pointing back to it. Workflow: paste the index, then paste only the slice you need.

Slices + picks — you already know which files matter. Sometimes you need one specific file without its whole directory:

dirmd -o docs ~/repos/myproject --vertical-slices \
    --pick common/src/config.rs --pick init/src/main.rs

Picks are individual files written alongside the slices, in the same directory layout (common/config.rs.md next to common/common_myproject.md). Use this when you're mid-conversation, already know the relevant files, and want a single consistent snapshot containing exactly those.

Rule of thumb: one file for tiny repos, slices when you need to browse, picks when you already know the answer.