A Claude Code plugin that automatically analyzes your session to detect architectural decisions and generates mADR (Markdown Any Decision Records) documents.
Every time you make a significant architectural decision in a Claude Code session — choosing a library, adopting a pattern, deciding on a structure — madr-gen finds it and asks if you want to document it. Documents are stored in docs/decisions/ following the MADR 4.0 format.
Claude Code has a built-in plugin system. Run the following two commands inside Claude Code to install madr-gen:
Step 1 — Register this repository as a marketplace
/plugin marketplace add JiHongKim98/madr-gen
Step 2 — Install the plugin
/plugin install madr-gen@JiHongKim98/madr-gen
That's it. The /madr command is now available in every session.
By default the plugin is installed for your user (all projects). You can change the scope with --scope:
| Scope | Command | Effect |
|---|---|---|
user (default) |
--scope user |
Available in all projects |
project |
--scope project |
Stored in .claude/settings.json, shared with teammates via git |
local |
--scope local |
Project-local only, gitignored |
# Example: share with teammates via version control
/plugin install madr-gen@JiHongKim98/madr-gen --scope project
/plugin # Open the interactive plugin UI
/plugin marketplace list # List registered marketplaces
/plugin update madr-gen@JiHongKim98/madr-gen # Update to latest version
/plugin uninstall madr-gen@JiHongKim98/madr-gen # Remove the plugin
/plugin disable madr-gen@JiHongKim98/madr-gen # Disable without uninstalling
Run the /madr command at any point during or at the end of a session:
/madr # Interactive: analyze session and select which ADRs to create
/madr scan # Quick scan: show detected decisions without writing files
/madr init # Initialize docs/decisions/, generate ADR index, and inject setup block into CLAUDE.md
madr-gen runs a 4-phase pipeline:
Phase 1: Detection (parallel)
└─ decision-detector (Sonnet)
├─ Reads JSONL session logs from ~/.claude/projects/<project>/
├─ Extracts User/Assistant conversation text
└─ Cross-references with git diff/log
Phase 2: Validation (sequential)
└─ duplicate-checker (Haiku)
└─ Reads docs/decisions/README.md index (status-aware)
→ only compares against active (Accepted/Proposed) ADRs
→ classifies each as: new / update / supersede / duplicate
Phase 3: Selection (interactive)
└─ AskUserQuestion (multi-select)
└─ Lists detected decisions with category, action type, and confidence
Phase 4: Writing (parallel)
└─ madr-writer (Sonnet) × N
├─ Creates or updates NNNN-kebab-case-title.md in docs/decisions/
└─ Regenerates docs/decisions/README.md index
ADR files follow the MADR 4.0 template:
docs/decisions/
├── README.md # Auto-generated ADR index (status table)
├── 0001-use-react-for-frontend.md
├── 0002-adopt-repository-pattern.md
└── 0003-use-vitest-for-testing.md
Each file contains:
---
status: accepted
date: 2026-03-04
decision-makers: kimjihong
supersedes: "0001" # optional: links to the ADR this decision replaces
---
# Use React for Frontend
## Context and Problem Statement
...
## Decision Drivers
* ...
## Considered Options
* React
* Vue
* Svelte
## Decision Outcome
Chosen option: "React", because ...
### Consequences
* Good, because ...
* Bad, because ...| Category | Examples |
|---|---|
| Technology | Library choices, framework selection, build tools |
| Architecture | Design patterns, module structure, API design |
| Convention | Naming rules, error handling, code style |
| Infrastructure | CI/CD, deployment, cloud services |
| Refactoring | Migration strategy, deprecation decisions |
Create .madr-gen.json in your project root to customize behavior:
{
"adrDirectory": "docs/decisions",
"templateStyle": "full",
"language": "auto",
"autoSuggest": true,
"categories": [
"technology",
"architecture",
"convention",
"infrastructure",
"refactoring"
]
}| Option | Default | Description |
|---|---|---|
adrDirectory |
docs/decisions |
Where ADR files are stored |
templateStyle |
full |
"full" (all sections) or "minimal" (context, options, outcome only) |
language |
auto |
"auto" matches session language, or force with "en", "ko", etc. |
autoSuggest |
true |
Whether to suggest existing ADR updates alongside new ones |
# Find session JSONL logs for any project
./scripts/find-session-logs.sh /path/to/project [max-age-hours]
# Extract conversation text from a session JSONL file
./scripts/extract-decisions.sh ~/.claude/projects/.../session.jsonl [max-lines]
# Generate/update the ADR index table in docs/decisions/README.md
./scripts/update-adr-index.sh [adr-directory]
# Inject/update the madr-gen setup block in CLAUDE.md
./scripts/setup-claude-md.sh [project-dir] [adr-directory]Run /madr init once per project. This:
- Creates the
docs/decisions/directory - Generates a
README.mdindex inside it - Injects a setup block into your
CLAUDE.md:
<!-- madr-gen:setup:start -->
## [IMPORTANT] Architecture Decisions
Read `docs/decisions/README.md` for the active ADR index before making architectural suggestions.
Before ending a session with significant architectural changes, run `/madr` to document decisions.
<!-- madr-gen:setup:end -->After init, future sessions will automatically read the ADR index and suggest /madr before ending.
madr-gen/
├── .claude-plugin/plugin.json # Plugin manifest
├── commands/madr.md # /madr command definition
├── agents/
│ ├── decision-detector.md # Detects decisions from session + git
│ ├── duplicate-checker.md # Prevents duplicate ADRs
│ └── madr-writer.md # Writes MADR 4.0 formatted files
├── hooks/
│ └── session-end-suggest.md # Planned: auto-suggest on session end
├── skills/madr-gen/SKILL.md # Full workflow orchestration
├── scripts/
│ ├── find-session-logs.sh # Session log discovery
│ ├── extract-decisions.sh # JSONL conversation extraction
│ ├── update-adr-index.sh # ADR index (README.md) generator
│ └── setup-claude-md.sh # CLAUDE.md setup block injection
└── .madr-gen.json # Default configuration
MIT