Content
# adr-skills
**adr-skills** is an MCP server for Claude Code that automatically captures development conversations and uses Claude Opus to generate, review, and manage Architecture Decision Records (ADRs).
> **TL;DR:** Install once, and every Claude Code session ends with a structured ADR saved to `~/.adr-mcp/adrs/` — no manual writing required.
[](https://glama.ai/mcp/servers/wooxogh/adr-mcp-setup)
## What problem does this solve?
Engineering teams make dozens of architectural decisions every week — which database to use, how to handle auth, whether to go monolith or microservices — but rarely write them down. Months later, nobody remembers why Redis was chosen over Memcached, or why the team avoided GraphQL.
**adr-skills** solves this by turning your existing Claude Code conversations into permanent, searchable ADR documents automatically.
## How it works
1. You have a normal development conversation in Claude Code
2. When the session ends, the Stop Hook captures the transcript
3. Claude Opus analyzes the conversation and extracts the architectural decision
4. A structured markdown ADR is saved to `~/.adr-mcp/adrs/ADR-0001-*.md`
5. Use `review_adr` to score quality, `link_adrs` to map dependencies, `check_stale_adrs` to surface outdated decisions
## Features
- **Auto session capture** — Stop Hook saves conversations automatically on Claude Code exit; no manual steps
- **AI-powered ADR generation** — Claude Opus extracts context, decision, and consequences from raw conversation
- **AI quality review** — Scores ADR completeness 0–100 and flags missing context, unconsidered alternatives, or optimistic consequences
- **Duplicate detection** — Warns when a new decision overlaps with a past one before saving
- **Markdown export** — Every ADR exported as `ADR-NNNN-slug.md`, ready to commit alongside your code
- **Status lifecycle** — Track decisions through `Proposed → Accepted → Deprecated → Superseded`
- **Dependency graph** — Link ADRs with `related_to`, `conflicts_with`, `depends_on` and visualize relationships
- **Stale ADR alerts** — Surface `Accepted` decisions older than N months that may need revisiting
- **Keyword search** — Find past decisions by technology name (e.g. Redis, JWT, PostgreSQL)
- **Timeline view** — Full decision history per project, correlated with git commits
## How is this different from existing ADR tools?
| Tool | Auto-capture from chat | AI generation | Quality review | MCP server |
|---|:---:|:---:|:---:|:---:|
| **adr-skills** | ✅ | ✅ Claude Opus | ✅ | ✅ |
| adr-tools (CLI) | ❌ | ❌ | ❌ | ❌ |
| mcp-adr-analysis-server | ❌ | ✅ OpenRouter | ❌ | ✅ |
| claude-historian-mcp | ✅ | ❌ | ❌ | ✅ |
| log4brains | ❌ | ❌ | ❌ | ❌ |
No existing tool combines automatic conversation capture with AI-powered ADR generation in a single MCP server. There is an [open feature request](https://github.com/anthropics/claude-code/issues/13853) on the Anthropic repo for native ADR support — adr-skills fills that gap today.
## Installation
```bash
git clone https://github.com/wooxogh/adr-mcp-setup.git
cd adr-mcp-setup
npm install
```
### Register with Claude Code
```bash
claude mcp add adr-skills node /absolute/path/to/adr-mcp-setup/index.js
```
### Environment setup
```bash
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env
```
> Without the API key, `generate_adr` falls back to keyword-based extraction and `review_adr` is unavailable. `.env` is in `.gitignore` — your key will never be committed.
### Enable auto session capture (Stop Hook)
Add to `~/.claude/settings.json`:
```json
{
"hooks": {
"Stop": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "node /absolute/path/to/adr-mcp-setup/hook.js"
}]
}]
}
}
```
## Tools (9 total)
| Tool | Description | Requires API key |
|---|---|:---:|
| `save_session` | Save a conversation to the database | ❌ |
| `generate_adr` | Auto-generate an ADR from a session | ❌ (AI mode: ✅) |
| `review_adr` | Score ADR quality and get improvement suggestions | ✅ |
| `update_adr_status` | Transition ADR through its lifecycle | ❌ |
| `link_adrs` | Create relationships between ADRs | ❌ |
| `get_adr_graph` | Visualize the ADR dependency graph | ❌ |
| `check_stale_adrs` | Find old Accepted ADRs that need revisiting | ❌ |
| `search_decisions` | Keyword search across all past decisions | ❌ |
| `get_timeline` | Decision history for a project | ❌ |
### `generate_adr` example output
```markdown
# ADR-1: Adopt Redis as the caching layer
## Status
Accepted
## Context
We needed pub/sub support for real-time notifications.
Memcached only handles simple key-value caching and could not meet this requirement.
## Decision
We adopted Redis as both cache and message broker.
It supports pub/sub, TTL, and persistence, and the team already has operational experience with it.
## Consequences
Real-time features can now be implemented without a separate message broker.
We must account for Redis operational costs and treat it as a potential single point of failure.
```
### `review_adr` example output
```
## ADR-1 Review — Score: 62/100
Good context, but decision rationale and risk coverage need work.
### Issues
🔴 [decision] No alternatives were considered before choosing Redis
🟡 [consequences] Risks are mentioned but mitigation strategies are missing
### Suggestions
1. Explicitly document why Memcached was rejected
2. Add a rollback plan if Redis becomes a bottleneck
```
### `get_adr_graph` example output
```
## ADR Dependency Graph
### depends on
ADR-5 "Use JWT for auth" → ADR-2 "Adopt Redis as cache"
### conflicts with
ADR-7 "Move to stateless sessions" ✕ ADR-2 "Adopt Redis as cache"
```
## FAQ
**Q: Do I need an Anthropic API key?**
No. Without a key, `generate_adr` uses keyword extraction as a fallback. With a key, Claude Opus produces significantly more accurate ADRs and `review_adr` becomes available.
**Q: Where are ADRs stored?**
Two places: SQLite database at `~/.adr-mcp/sessions.db` and markdown files at `~/.adr-mcp/adrs/`. The markdown files are git-committable.
**Q: Can I use this without the Stop Hook?**
Yes. Call `save_session` manually with your conversation text, then `generate_adr` with the returned session ID.
**Q: Does this work with other AI assistants besides Claude?**
The MCP server protocol is open, but the Stop Hook is Claude Code-specific. The database and markdown exports are tool-agnostic.
**Q: How does duplicate detection work?**
When generating an ADR, adr-skills extracts significant keywords from the title and decision text and queries for overlapping past ADRs. Matches are shown as warnings — the new ADR is still saved.
**Q: What ADR format does this use?**
The [Michael Nygard ADR format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) (Title, Status, Context, Decision, Consequences), which is the most widely adopted format in the software industry.
## Project structure
```
adr-mcp-setup/
├── index.js ← MCP server — 9 tool definitions and routing
├── db.js ← SQLite CRUD (sessions, adrs, adr_relations tables)
├── adr.js ← ADR extraction and AI review logic (Claude Opus)
├── hook.js ← Claude Code Stop Hook for automatic session capture
├── .env.example ← Environment variable template
└── package.json
```
**Database:** `~/.adr-mcp/sessions.db`
**ADR files:** `~/.adr-mcp/adrs/ADR-NNNN-slug.md`
## Requirements
- Node.js 18+
- Claude Code CLI
- Anthropic API Key *(optional — required for AI generation and review)*
