claudemd

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

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

---

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

pip install claudemd

Prerequisites:

• Python 3.9+
• An Anthropic API key (for generate and update commands)

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

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

[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:

## 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:

- 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

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

Running Tests

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.

---

Related Projects

• jupyter-claude-assistant — AI coding assistant for JupyterLab
• awesome-claude-code — Curated Claude Code resources