dotmd
CLI for managing markdown documents with YAML frontmatter.
Index, query, validate, and lifecycle-manage any collection of .md files — plans, ADRs, RFCs, design docs, meeting notes. Built for AI-assisted development workflows where structured docs need to stay current.
Install
npm install -g dotmd-cli # global — use `dotmd` anywhere
npm install -D dotmd-cli # project devDep — use via npm scripts
# requires Node.js >= 20
Claude Code plugin (recommended)
If you drive dotmd from Claude Code, install the dotmd plugin. It teaches every session and subagent the dotmd workflow and guards the wrong-moves agents keep making (committing session-local prompts, cat-ing prompts instead of consuming them, hand-editing status:):
/plugin marketplace add reowens/dotmd
/plugin install dotmd@dotmd
The plugin bundles the hooks (SessionStart/SubagentStart priming, a PreToolUse guard) and a canonical workflow skill, so guidance travels to every repo automatically — no per-repo setup. It calls the dotmd CLI, so keep npm install -g dotmd-cli installed too. (Source: plugins/dotmd/ in this repo.)
Upgrading to 0.57.0+: per-repo .claude/commands/{plans,docs,baton}.md scaffolding is retired — that guidance now ships via the plugin's workflow skill and /plans, /docs, /prompts, /baton commands. On the next dotmd hud (SessionStart), dotmd removes those generated files (only banner-stamped <!-- dotmd-generated --> ones — your hand-authored command files are never touched). If you'd committed them, you'll see deletions to commit — that's expected. Run claude plugin update dotmd@dotmd to pick up /baton.
Quick Start
dotmd init # creates dotmd.config.mjs, docs/, docs/docs.md
dotmd new my-feature # scaffold a new doc with frontmatter
dotmd list # index all docs grouped by status
dotmd check # validate frontmatter and references
dotmd context # compact briefing (great for LLM context)
dotmd doctor # auto-fix everything in one pass
Shell Completion
# bash
eval "$(dotmd completions bash)" # add to ~/.bashrc
# zsh
eval "$(dotmd completions zsh)" # add to ~/.zshrc
Auto-Detected From Your Markdown
dotmd reads what's already in your .md files — you don't have to migrate everything into frontmatter to get useful output.
Add - [ ] checkboxes anywhere in the body:
## Polish
- [x] Index regen on every mutation
- [x] Auto-checklist progress bars
- [x] Untagged docs surfaced in `list`
- [ ] SessionStart hook auto-wired by init
- [ ] Bulk-tag prompt for brownfield repos
dotmd list picks them up — zero config, no extra field:
Polish-Pass 2d ██████░░░░ 3/5
Same story for these signals, each picked up from body text when the matching frontmatter field is missing:
| Field | Falls back to | Example body |
|---|
title | first # H1 heading | # Auth Token Refresh |
summary | first > blockquote line (skipping Status note lines) | > One-line summary of what this doc covers. |
current_state | **Status:** ..., - Status: ..., or > Status note (...): ... lines (skipped on terminal docs to avoid stale claims) | **Status:** Phase 2 underway |
next_step | first bullet under a ## Next Step (or ## Suggested Next Step) H2 section | ## Next Step
- wire token refresh into middleware |
| Body links | inline [text](path.md) references | validated as ref edges by check |
Explicit frontmatter always wins. Body extraction is a cushion for partially-tagged docs, not a replacement for it.
What It Does
