Metadata-Version: 2.4
Name: adrchive
Version: 0.2.0
Summary: AI-powered ADR generator for Claude Code. Captures architectural decisions from coding sessions.
Project-URL: Homepage, https://github.com/teczerniec/adrchive
Project-URL: Repository, https://github.com/teczerniec/adrchive
Project-URL: Issues, https://github.com/teczerniec/adrchive/issues
Author-email: Timothy Eczerniec <teczerniec@gmail.com>
License-Expression: MIT
Keywords: adr,ai,architecture,claude,decision-records,documentation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.42.0
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pip-audit>=2.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pipx install adrchive
```

## Quick Start

```bash
# 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:
```bash
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):
```bash
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`):
```bash
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:

```bash
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:

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

### `adrchive promote`

Promote a draft to the canonical ADR directory:

```bash
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:

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

### `adrchive supersede`

Create a new ADR that supersedes an existing one:

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

### `adrchive link`

Create a bidirectional relationship between ADRs:

```bash
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:

```bash
adrchive index
```

### `adrchive audit`

Interactive codebase audit for undocumented decisions:

```bash
adrchive audit
```

## ADR Format

adrchive produces MADR 4.0 formatted records with YAML frontmatter:

```markdown
---
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:

```yaml
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

```bash
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
