adrchive

AI-powered ADR generator for Claude Code. Captures architectural decisions made during coding sessions and drafts Architecture Decision Records before they're lost.

The Problem

Developers make decisions during AI coding sessions — schema choices, infrastructure picks, library selections — that disappear when the session ends. adrchive hooks into Claude Code's lifecycle to capture those decisions as structured MADR 4.0 markdown files automatically.

The end goal: a repository of architectural decisions within your project that AI tools can consult later to understand not just the codebase, but the reasoning behind the code.

Installation

pipx install adrchive

Quick Start

# Initialize adrchive in your project
cd your-project
adrchive init

# With Claude Code hook auto-setup (works with Claude Max plans — no API key needed)
adrchive init --hooks

# Or with API key mode (separate Anthropic API billing)
adrchive init --hooks --mode command

# Manually draft an ADR via /adr slash command in Claude Code
# Or from the CLI (requires API key):
adrchive draft --summary "Chose Redis over Memcached for session caching due to pub/sub support"

# Review and promote a draft
adrchive promote

# Scan codebase for undocumented decisions (requires API key)
adrchive audit

API Key

Some features require an ANTHROPIC_API_KEY (separate from a Claude Max subscription):

Feature	Needs API key?
/adr slash command	No — Claude drafts directly
Auto-detection (agent mode, default)	No — uses Claude's session
Auto-detection (command mode)	Yes
adrchive draft / adrchive audit	Yes
adrchive promote/status/link/index	No — local file operations

If you have an API key:

export ANTHROPIC_API_KEY=your-key-here

How It Works

Automatic Mode (Claude Code Hook)

When configured with --hooks, adrchive detects architectural decisions automatically after each Claude Code response. Two modes are available:

Agent mode (default, no API key):

adrchive init --hooks

A Claude subagent reviews the recent conversation for architectural decisions. If found, it drafts ADRs directly. Uses your existing Claude Max plan — no separate API billing.

Command mode (requires ANTHROPIC_API_KEY):

adrchive init --hooks --mode command

A Python process applies tiered gating (file size delta → message count → Haiku classifier) before drafting via Sonnet. More efficient for high-volume sessions since the first two tiers are free and instant.

In both modes, drafts are never canonical — they require human review before promotion.

Manual Mode (/adr Slash Command)

Mid-session in Claude Code:

/adr Chose Redis over Memcached for session caching because of pub/sub support

Claude drafts the ADR directly using the full conversation context — the highest quality path since it was part of the discussion.

Audit Mode

For codebases that predate adrchive:

adrchive audit

Scans dependency manifests, schema files, Dockerfiles, CI configs, and more. Identifies decisions implied by the code that have no ADR, then walks you through an interactive Q&A to fill in context.

CLI Reference

adrchive init [--hooks] [--mode agent|command]

Initialize adrchive for a project. Creates:

• doc/adr/ and doc/adr/drafts/ directories
• .adr-config.yml with defaults
• ADR section in CLAUDE.md
• doc/adr/INDEX.md

With --hooks: configures Claude Code's Stop hook in .claude/settings.json and installs the /adr slash command to .claude/skills/adr/. Requires a Claude Code restart to take effect.

• --mode agent (default): uses a Claude subagent — no API key required
• --mode command: uses adrchive auto via shell script — requires ANTHROPIC_API_KEY

adrchive auto

Called by the Claude Code Stop hook. Reads session transcript from stdin JSON, applies tiered gating, classifies decisions, and drafts ADRs. Not typically invoked directly.

adrchive draft

Manually draft an ADR:

adrchive draft --summary "Description of the decision"
adrchive draft --transcript /path/to/session.jsonl

adrchive promote

Promote a draft to the canonical ADR directory:

adrchive promote                                    # interactive selection
adrchive promote --draft DRAFT-use-redis.md          # specific draft
adrchive promote --draft DRAFT-use-redis.md --status rejected

adrchive status

Change an ADR's status with transition validation:

adrchive status --adr 20260416-use-redis.md --set deprecated

adrchive supersede

Create a new ADR that supersedes an existing one:

adrchive supersede --old 20260410-use-mysql.md --summary "Switch to PostgreSQL for JSONB support"

adrchive link

Create a bidirectional relationship between ADRs:

adrchive link --from 20260416-use-redis.md --to 20260412-api-caching.md --type relates-to

Relationship types: supersedes, amends, relates-to, enables (and their reverses).

adrchive index

Regenerate the INDEX.md file:

adrchive index

adrchive audit

Interactive codebase audit for undocumented decisions:

adrchive audit

ADR Format

adrchive produces MADR 4.0 formatted records with YAML frontmatter:

---
status: draft
date: 2026-04-16
decision-makers: []
tags: [infrastructure, caching]
supersedes: []
links: []
---

# Use Redis for Session Caching

## Context and Problem Statement

We need a caching layer for session data that supports cache invalidation
across multiple application instances.

## Considered Options

- Redis
- Memcached
- In-process cache

## Decision Outcome

Chosen option: "Redis", because it supports pub/sub for cache invalidation
across instances.

### Consequences

- Good, because cache invalidation is straightforward via pub/sub
- Bad, because it adds operational complexity (another service to manage)

Status Lifecycle

Draft --> Proposed --> Accepted
                  \-> Rejected

Accepted --> Deprecated
         \-> Superseded

Once accepted, ADRs are immutable. To change a decision, create a new ADR that supersedes the old one.

Configuration

.adr-config.yml in your project root:

adr_dir: doc/adr                          # where promoted ADRs live
draft_dir: doc/adr/drafts                 # where drafts are written
min_confidence: 0.75                      # classifier confidence threshold
classifier_model: claude-haiku-4-5-20251001  # fast/cheap model for detection
drafter_model: claude-sonnet-4-6-20250514    # thorough model for drafting
min_new_messages: 4                       # minimum new messages before classifying
session_ttl_days: 7                       # cleanup stale session state after N days
suggested_tags:                           # project-specific tag vocabulary
  - infrastructure
  - database
  - api

Development

git clone https://github.com/teczerniec/adrchive.git
cd adrchive
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT