# claudemd

**Auto-generate and maintain your CLAUDE.md from your codebase.**

Works with Claude Code, Cursor, GitHub Copilot, and Windsurf.

[![PyPI version](https://badge.fury.io/py/claudemd.svg)](https://badge.fury.io/py/claudemd)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/your-org/claudemd/actions/workflows/test.yml/badge.svg)](https://github.com/your-org/claudemd/actions)

---

## The Problem

Every developer using Claude Code, Cursor, or Copilot needs a `CLAUDE.md` context file. But:

- Writing it is tedious (30-60 minutes per project)
- It goes stale after every refactor
- Most are either too long (wastes context tokens) or too short (not helpful)
- No tooling exists to manage it

## The Solution

`claudemd` is a CLI tool that handles the full CLAUDE.md lifecycle:

```
# 1. Generate from scratch
$ claudemd generate
  Scanning directory structure...
  Detecting technology stack: Python, FastAPI, PostgreSQL
  Analyzing git history: 234 commits, 3 authors
  Generating with Claude...
  Written to CLAUDE.md (342 tokens)

# 2. Check for staleness after a refactor
$ claudemd check
  Staleness score: 38/100
  [WARN] References 'old_handlers.py' which no longer exists
  [WARN] References directory 'lib/' which no longer exists

# 3. Update only the stale sections
$ claudemd update
  Updated CLAUDE.md

# 4. Lint for quality issues
$ claudemd lint
  Quality Score: 87/100
  [WARN] References to 1 file that doesn't exist
  Token count: 342 / 1500 recommended (22.8%) - GOOD
```

---

## Installation

```bash
pip install claudemd
```

**Prerequisites:**
- Python 3.9+
- An [Anthropic API key](https://console.anthropic.com/) (for `generate` and `update` commands)

```bash
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
```

---

## Commands

| Command | Description |
|---|---|
| `claudemd generate` | Scan your codebase and generate a CLAUDE.md from scratch |
| `claudemd check` | Check your CLAUDE.md for staleness (dead refs, age, missing sections) |
| `claudemd update` | Update only the stale sections, preserving manual customizations |
| `claudemd lint` | Validate quality (token count, missing sections, dead references) |
| `claudemd tokens` | Show token breakdown by section |
| `claudemd init` | Create `.claudemd.toml` config file |

### Options

```bash
# Generate with a specific model
claudemd generate --model claude-sonnet-4-6

# Generate and also write to Cursor and Copilot formats
claudemd generate --also .cursor/rules/project.mdc --also .github/copilot-instructions.md

# Preview generation without writing
claudemd generate --dry-run

# Check and fail in CI if staleness >= 30
claudemd check --threshold 30

# Update a specific section
claudemd update --section "Architecture"

# Lint with JSON output (for tooling)
claudemd lint --format json

# Run on a different project directory
claudemd --project /path/to/project generate
```

---

## Configuration

Create `.claudemd.toml` in your project root (run `claudemd init`):

```toml
[claudemd]
# Output file path
output = "CLAUDE.md"

# Also write to these paths
also_generate = [".cursor/rules/project.mdc"]

# Max tokens in generated file
max_tokens = 2000

# Directories to exclude from scanning
exclude = ["node_modules", ".git", "dist", "build", "__pycache__"]

# Default model (haiku = fast/cheap, sonnet = best quality)
model = "claude-haiku-4-5-20251001"
```

### Preserving Manual Sections

Mark sections you've written manually with `<!-- MANUAL -->` — they'll never be overwritten by `claudemd update`:

```markdown
## Team Conventions
<!-- MANUAL -->
- We use conventional commits: feat/fix/chore/docs
- All database migrations must be reviewed by @team-lead
- Never merge on Fridays
```

---

## CI/CD Integration

Add to `.github/workflows/ci.yml`:

```yaml
- name: Check CLAUDE.md staleness
  run: |
    pip install claudemd
    claudemd check --threshold 40
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

This will fail the CI run if the staleness score is 40 or higher, prompting developers to run `claudemd update`.

---

## Supported Formats

| File | Tool |
|---|---|
| `CLAUDE.md` | Claude Code |
| `.cursorrules` | Cursor (legacy) |
| `.cursor/rules/*.mdc` | Cursor (current) |
| `.github/copilot-instructions.md` | GitHub Copilot |
| `AGENTS.md` | OpenAI Codex |

---

## Supported Tech Stacks

**Languages:** Python, JavaScript/TypeScript, Rust, Go, Java, Kotlin

**Frameworks detected:** FastAPI, Flask, Django, Next.js, React, Vue, Svelte, Express, Axum, Gin, Echo, Spring Boot

**Tools detected:** Docker, GitHub Actions, GitLab CI, pre-commit, ESLint, Prettier

**Package managers:** pip, conda, npm, yarn, pnpm, bun, cargo, go modules

---

## How It Works

1. **CodebaseScanner** — Builds a directory tree, counts files by type, finds entry points and key configs
2. **StackDetector** — Reads `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod` to detect tech stack
3. **GitAnalyzer** — Reads git log to find recently modified files, hot spots, branching strategy
4. **DocReader** — Reads README, CONTRIBUTING, and existing docs for project context
5. **ClaudeGenerator** — Synthesizes all data into a high-quality, concise CLAUDE.md via Claude API

For `check` and `update`, **StalenessChecker** compares file references in CLAUDE.md against the actual filesystem.

---

## Development

```bash
git clone https://github.com/your-org/claudemd
cd claudemd
pip install -e ".[dev]"
pytest tests/ -v
```

### Running Tests

```bash
pytest tests/                          # All tests
pytest tests/test_stack_detector.py   # Stack detection tests
pytest tests/test_linter.py            # Linter tests
```

---

## License

MIT License. See [LICENSE](LICENSE).

---

## Related Projects

- [jupyter-claude-assistant](../jupyter-claude-assistant) — AI coding assistant for JupyterLab
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Curated Claude Code resources
