adrs

A command-line tool for creating and managing Architecture Decision Records (ADRs).

Features

• adr-tools compatible - works with existing ADR repositories
• Multiple formats - supports Nygard (classic) and MADR 4.0.0 formats
• Template variants - full, minimal, and bare templates
• Tags support - categorize ADRs with tags (NextGen mode)
• Full-text search - search ADR titles and content
• Repository health checks - doctor command finds issues
• Config discovery - automatically finds ADR directory from subdirectories
• Import/Export - JSON-ADR format with federation support
• MCP server - AI agent integration via Model Context Protocol
• Cross-platform - macOS, Linux, and Windows binaries

Installation

Homebrew (macOS/Linux)

brew install joshrotenberg/brew/adrs

Cargo

cargo install adrs

Docker

docker run --rm -v $(pwd):/work ghcr.io/joshrotenberg/adrs init

Binary releases

Download from GitHub Releases.

Quick Start

# Initialize a new ADR repository
adrs init
Create your first decision
adrs new "Use PostgreSQL for persistence"
List all ADRs
adrs list
Check repository health
adrs doctor

Usage

adrs [OPTIONS] <COMMAND>
Commands:   init         Initialize a new ADR repository   new          Create a new ADR   edit         Edit an existing ADR   list         List all ADRs   search       Search ADRs for matching content   link         Link two ADRs together   status       Change an ADR's status   config       Show configuration   doctor       Check repository health   generate     Generate documentation (toc, graph, book)   export       Export ADRs to different formats   import       Import ADRs from different formats   template     Manage ADR templates   completions  Generate shell completions   cheatsheet   Show quick reference for common workflows
Options:       --ng         Enable NextGen mode with YAML frontmatter   -C, --cwd <DIR>  Run from a different directory   -h, --help       Print help   -V, --version    Print version

Examples

Create ADRs with different formats

# Classic Nygard format (default)
adrs new "Use REST API"
MADR 4.0.0 format
adrs new --format madr "Use GraphQL"
Minimal template
adrs new --variant minimal "Quick decision"
With tags (NextGen mode)
adrs --ng new --tags security,api "Use JWT for authentication"

Search and filter

# Full-text search
adrs search postgres
Filter by status
adrs list --status accepted
Filter by tag (NextGen mode)
adrs --ng list --tag security

Supersede and link decisions

# Supersede an existing ADR
adrs new --supersedes 2 "Use MySQL instead"
Link related ADRs (auto-derives reverse link)
adrs link 3 Amends 1

Generate documentation

# Table of contents
adrs generate toc > doc/adr/README.md
Graphviz dependency graph
adrs generate graph | dot -Tsvg > doc/adr/graph.svg
mdbook
adrs generate book && cd book && mdbook serve

Import/Export

# Export to JSON-ADR format
adrs export json > decisions.json
Import from another repository
adrs import decisions.json --renumber

MCP Server (AI Integration)

adrs includes an MCP (Model Context Protocol) server for AI agent integration (enabled by default).

Add to Claude Desktop config (claudedesktopconfig.json):

{
  "mcpServers": {
    "adrs": {
      "command": "adrs",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

The MCP server provides 15 tools for reading, creating, and managing ADRs.

Library

adrs is built on the adrs-core library, which can be used independently:

[dependencies]
adrs-core = "0.7"

use adrs_core::Repository;
let repo = Repository::open(".")?; for adr in repo.list()? {     println!("{}: {}", adr.number, adr.title); }

See library documentation for more details.

Documentation

Full documentation: joshrotenberg.com/adrs

Contributing

Contributions welcome! See issues or open a new one.

License

MIT or Apache-2.0