adr-gen

adr-gen is a standalone CLI that generates Architecture Decision Records (ADRs) by combining:

• Claude/Codex session history from disk (~/.claude/projects/..., ~/.codex/sessions/...)
• Git history (git diff, git log, git diff --stat)

It writes MADR-style markdown files into your repository (default: docs/adr) and updates INDEX.md.

Install

# if published on npm
npm install -g @dinogit/adr-gen

# works immediately (no npm publish needed)
npm install -g git+https://github.com/dinogit/adr-gen.git

Distribution

• GitHub install:
  • Always available once code is on GitHub.
  • npm install -g git+https://github.com/dinogit/adr-gen.git
• npm install (npm install -g @dinogit/adr-gen):
  • npm package page: https://www.npmjs.com/package/@dinogit/adr-gen
  • Works after package is published to npm under the @dinogit/adr-gen name.
  • Publish steps:
    • npm login
    • npm run release:check
    • npm publish --access public
    • npm view @dinogit/adr-gen version

Project Architecture

• Session source layer:
  • Claude/Codex loading is encapsulated in src/session-sources.ts with source loaders per backend.
• Provider client layer:
  • LLM provider clients are isolated in src/provider-clients.ts behind a provider registry.
• ADR generation layer:
  • Prompt building + schema validation in src/llm.ts.
• Orchestration layer:
  • End-to-end pipeline stages in src/pipeline.ts.
  • Runtime UX + output rendering in src/main.ts.

Provider Modes

• Local CLI providers (default, no API key in adr-gen):
  • claude (uses your local Claude CLI login/session)
  • codex (uses your local Codex CLI login/session)
• API providers (optional fallback):
  • anthropic
  • openai

Safe API Auth Setup (macOS, optional)

If you choose API providers, store keys in macOS Keychain once:

adr-gen auth --provider anthropic
adr-gen auth --provider openai

This opens the provider key page and stores your key via macOS Keychain prompts (key is not printed or saved in shell history).

Clear a stored key:

adr-gen auth --provider openai --clear

Usage

# default: local Claude CLI provider, compare current branch vs main, analyze last 5 sessions
adr-gen

# first-time setup for an existing repository:
# creates docs/adr + INDEX.md and a baseline ADR if none exists
adr-gen init

# first-time setup without creating baseline ADR
adr-gen init --no-baseline

# configure Claude + git hooks automatically
adr-gen setup-hooks

# choose conversation source logs explicitly (what generated the code)
adr-gen --source claude
adr-gen --source codex
adr-gen --source auto

# local Codex CLI provider
adr-gen --provider codex

# target a specific branch
adr-gen --branch feature/auth-refactor

# restrict sessions by date
adr-gen --date 2026-02-14

# restrict sessions by date range
adr-gen --from 2026-02-01 --to 2026-02-14

# include a custom number of recent sessions
adr-gen --sessions 3

# custom output directory
adr-gen --output docs/adr

# dry run (no files written)
adr-gen --dry-run

# skip index update
adr-gen --no-index

# generate only when architectural signals are detected
adr-gen --if-architectural

# output machine-readable JSON summary
adr-gen --json

# print timing and token estimate metrics
adr-gen --timings

# select model (provider-specific)
adr-gen --provider claude --model sonnet
adr-gen --provider codex --model gpt-5

# API fallback providers
adr-gen --provider anthropic --model claude-sonnet-4-6
adr-gen --provider openai --model gpt-4.1
adr-gen --api-key sk-...

Tip: running on main with little or no diff often produces a weak ADR. Use it on a feature branch (main..HEAD) after meaningful changes. While generating, the CLI shows a live loading indicator. Use Ctrl+C to cancel cleanly, or --quiet to suppress progress output. Output is colorized with a built-in lightweight formatter (no Chalk-style plugin dependency), with an animated status bar and summary panel. Set NO_COLOR=1 to disable colors and ADR_GEN_ASCII=1 to force plain ASCII symbols.

Configuration File

adr-gen automatically loads config from project root (git top-level), using:

1. adr-gen.config.json (preferred)
2. .adrgenrc

Example:

{
  "output": "docs/adr",
  "format": "madr",
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "autoIndex": true,
  "sources": ["claude", "codex"],
  "branchBase": "main",
  "autoDetectArchitectural": true,
  "timings": false
}

Notes:

• CLI args override config values.
• sources maps to --source (["claude","codex"] -> auto).
• autoDetectArchitectural: true is equivalent to defaulting --if-architectural.
• timings: true is equivalent to defaulting --timings.

Integration Points

Claude Code hook (post-session)

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "adr-gen --if-architectural --quiet",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Git hook (pre-push)

#!/bin/sh
adr-gen --branch "$(git branch --show-current)" --quiet

GitHub Action

- name: Generate ADR
  run: adr-gen --branch ${{ github.head_ref }} --output docs/adr

One-step hook setup

adr-gen setup-hooks

Defaults:

• updates .claude/settings.local.json with a Stop hook
• updates .git/hooks/pre-push
• hook command: adr-gen --if-architectural --quiet

Release Profile

Local release checks:

npm run ci:verify

This runs:

• lint (npm run lint)
• typecheck (npm run typecheck)
• tests (npm test)
• pack smoke (npm run pack:dry-run)
• install smoke (npm run install:smoke)

CI workflow:

• .github/workflows/ci.yml
• Node matrix: 18 + 20
• Includes install smoke on built tarball

Requirements

• Node.js >=18.17
• For local mode: installed and authenticated claude or codex CLI
• For API mode: API key via Keychain/env/--api-key
• A git repository with a valid compare range (main..HEAD by default)
• Claude/Codex session logs for that repository under ~/.claude/projects and ~/.codex/sessions

Output

• ADR files: docs/adr/NNNN-title.md
• Index file: docs/adr/INDEX.md

The generated ADR template includes:

• Context
• Decision
• Alternatives Considered
• Consequences
• Changes (from git diff --stat)

Session selection is prioritized by git commit window (git log <base>..<target> timestamps), then constrained by --date or --from/--to, then limited by --sessions. Conversation source selection is controlled by --source and is independent from --provider.