io.github.SaiNarayana-B/patchwork

Official

by SaiNarayana-B · Python

patchwork — Codebase Conventions for AI Agents

Scan any codebase, generate CONVENTIONS.md, expose conventions as MCP tools for AI agents.

Scans codebases to generate and expose coding conventions as MCP tools for AI agents.

README.md10 KBView on GitHub

patchwork

Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.

Every team that uses AI coding assistants hits the same wall: Claude writes getUserById in a codebase that uses get_user_by_id. Cursor creates components/userCard.tsx in a project that uses user-card.tsx. The agent invented a response shape that doesn't match the rest of the API.

You write a CLAUDE.md manually. It goes stale in two weeks. You write it again.

patchwork automates this. It scans your actual source code using AST analysis and detects what your team really does — not what you think you do.

What it detects

Category	What's mined
Naming	Functions, classes, variables, constants, files — with confidence score and real examples
Imports	Absolute vs relative, path aliases (`@/`, `src/`), barrel files, destructuring style
Structure	Source root, test layout, feature vs layer organisation, monorepo detection
Error Handling	try/except vs Result types, logging framework, custom exception naming, propagation style
Testing	Framework, assertion style, mocking library, coverage tool, fixture patterns
API Patterns	Response shape, route param style, ORM, async pattern, GraphQL/gRPC presence
Git Workflow	Commit message style, branch naming, co-change file pairs
Tech Stack	Frameworks, package manager, linters, formatters, type checker, build tool, scripts

Quick start

bash

pip install patchwork-conventions
cd your-project
patchwork scan

That's it. You'll get a CONVENTIONS.md like this:

markdown

# CONVENTIONS.md
> Auto-generated by patchwork on 2026-06-25

## Tech Stack
**Language:** python
**Runtime:** Python >=3.11
**Package Manager:** uv
**Frameworks:** fastapi, sqlalchemy
**Linters:** ruff
**Formatters:** ruff, black

## Naming Conventions

### Python
- **Functions:** `snake_case` (97% consistent)
  - Examples: `get_user`, `parse_response`, `create_session`
- **Classes:** `PascalCase` (100% consistent)
  - Examples: `UserService`, `AuthHandler`, `DatabaseClient`
- **Constants:** `SCREAMING_SNAKE`
  - Examples: `MAX_RETRIES`, `API_BASE_URL`
- **Files:** `snake_case`
- **Private prefix:** `_`
- **Test functions:** prefix `test_`

## Project Structure
**Source root:** `src/`
**Organisation:** layer-based
**Tests:** separate (`tests/`)

**Key directories:**
  - `src/` — source root
  - `tests/` — test suite
  - `migrations/` — database migrations

## Error Handling

### Python
- **Pattern:** try/except
- **Propagation:** raise
- **Logging:** `structlog`
- **Custom exception naming:** Error suffix
  - `ValidationError`, `AuthError`, `NotFoundError`

## Testing Conventions

### Python
- **Framework:** pytest
- **Coverage:** 34 test files / 89 source files (38% ratio)
- **Assertions:** `assert(...)`
- **Coverage tool:** `pytest-cov`
- **Patterns:** fixtures, factories

## Git Conventions
- **Commit style:** conventional commits
- **Examples:** `feat(auth): add JWT refresh`, `fix(api): handle null user`
- **Branch naming:** feature/name + fix/name

Why not argus or sourcebook?

Feature	patchwork	argus	sourcebook
AST-based naming analysis	✅ tree-sitter	❌ filesystem only	❌ not done
Confidence scores	✅ per-category	❌	❌
Real examples from your code	✅	❌	❌
Counter-examples (inconsistencies)	✅	❌	❌
Error handling pattern mining	✅	❌	❌
API response shape detection	✅	❌	❌
Co-change file pairs	✅	❌	✅
Convention checking (`check` cmd)	✅	❌	❌
MCP server with 8 tools	✅	❌	✅ (4 tools)
Watch mode	✅	✅ (`sync`)	✅
Zero LLM required	✅	✅	✅ (layer A)
Open source / MIT	✅	✅	❌ BSL

Commands

bash

# Generate CONVENTIONS.md
patchwork scan

# Generate for a specific path
patchwork scan /path/to/project

# Generate AGENTS.md
patchwork scan --agents-md

# Append to CLAUDE.md
patchwork scan --claude-md

# Output JSON (for programmatic use)
patchwork scan --json

# Print to stdout (don't write file)
patchwork scan --stdout

# Limit to specific languages
patchwork scan --lang python --lang typescript

# Re-scan and update, preserving manual edits
patchwork update

# Show what would change
patchwork diff

# Print detected conventions to terminal
patchwork show

# Auto-watch mode (regenerate on change)
patchwork watch

# Start MCP server
patchwork serve --stdio    # for Claude Code
patchwork serve --port 3742  # HTTP mode

Claude Code integration

Option 1: CONVENTIONS.md (recommended)

bash

patchwork scan      # run once
# CONVENTIONS.md is automatically read by Claude Code

Option 2: Append to CLAUDE.md

bash

patchwork scan --claude-md

Option 3: MCP server

Claude Code — add to ~/.claude.json (or run claude mcp add interactively):

json

{
  "mcpServers": {
    "patchwork": {
      "command": "patchwork",
      "args": ["serve", "/path/to/your/project", "--stdio"]
    }
  }
}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json

{
  "mcpServers": {
    "patchwork": {
      "command": "patchwork",
      "args": ["serve", "/path/to/your/project", "--stdio"]
    }
  }
}

Cursor — add to .cursor/mcp.json in your project root:

json

{
  "mcpServers": {
    "patchwork": {
      "command": "patchwork",
      "args": ["serve", ".", "--stdio"]
    }
  }
}

Then your AI agent can use 8 on-demand tools:

Tool	When to use
`patchwork_scan`	Get complete conventions overview
`patchwork_naming`	Before writing new identifiers
`patchwork_structure`	Before creating new files/directories
`patchwork_stack`	When choosing libraries or commands
`patchwork_errors`	Before writing error handling
`patchwork_testing`	Before writing test files
`patchwork_git`	Before writing commit messages
`patchwork_check`	Validate a proposed name

Option 4: Claude Code skill (SKILL.md)

Copy SKILL.md from this repo to ~/.claude/skills/patchwork/SKILL.md to get /patchwork slash commands.

Watch mode (CI/auto-update)

bash

# Keep CONVENTIONS.md updated as you code
patchwork watch &

# Or in CI — fail if conventions changed
patchwork diff || (patchwork update && git add CONVENTIONS.md && git commit -m "chore: update conventions")

Python API

python

from patchwork import scan
from patchwork.scanner import ScanOptions
from pathlib import Path

# Full scan
report = scan(ScanOptions(root=Path(".")))

# Render to markdown
print(report.to_markdown())

# Render to JSON
import json
data = json.loads(report.to_json())

# Access specific results
naming = report.naming.get("python")
print(f"Functions: {naming.functions.style} ({naming.functions.confidence:.0%})")
print(f"Examples: {naming.functions.examples}")

structure = report.structure
print(f"Source root: {structure.source_root}")
print(f"Organisation: {structure.organisation}")

Supported languages

Language	AST (tree-sitter)	Fallback regex
Python	✅ full	✅
TypeScript	✅ full	✅
JavaScript	✅ full	✅
Go	✅ (with `full` extra)	✅
Rust	✅ (with `full` extra)	✅
Java	✅ (with `full` extra)	✅
Ruby, PHP, C#, C++	❌	✅ regex only

Install full language support:

bash

pip install 'patchwork-conventions[full]'

How it works

code

your codebase
     │
     ▼
ConfigDetector        ← reads package.json, pyproject.toml, go.mod, Cargo.toml
     │
     ▼
File discovery        ← respects .gitignore, skips node_modules etc.
     │
     ▼
Per-language AST      ← tree-sitter parses every file into a syntax tree
     │
     ├── NamingMiner       → extracts function/class/variable names, classifies style
     ├── ImportMiner        → detects import patterns, aliases, barrel files
     ├── StructureMiner     → analyses directory layout, test co-location
     ├── ErrorHandlingMiner → detects try/catch patterns, logging, custom exceptions
     ├── TestingMiner       → identifies framework, assertion style, mocking
     ├── APIPatternMiner    → finds response shapes, ORMs, route styles
     └── GitPatternMiner    → mines commit history, branches, co-change pairs
          │
          ▼
     ConventionReport
          │
          ├── CONVENTIONS.md  (default)
          ├── AGENTS.md       (--agents-md)
          ├── CLAUDE.md       (--claude-md, appends)
          └── JSON            (--json)

All analysis is 100% local — no API calls, no telemetry, no data leaves your machine.

Performance

On a 1,000-file TypeScript monorepo:

Without tree-sitter: ~0.8s
With tree-sitter (full AST): ~2.1s

On a 500-file Python project:

~1.1s

Results are deterministic — same codebase always produces the same output.

Contributing

bash

git clone https://github.com/yourusername/patchwork
cd patchwork
pip install -e '.[dev]'
pytest

Pull requests welcome. See CONTRIBUTING.md.

License

MIT — free for personal and commercial use.

Topics

claude-code · agent-skills · mcp · context-engineering · hallucination-detection · code-conventions · static-analysis · tree-sitter · developer-tools · ai-coding

Install

claude_desktop_config.json

{
  "mcpServers": {
    "patchwork": {
      "command": "uvx",
      "args": [
        "patchwork-conventions"
      ]
    }
  }
}