{
  "markdown": "# patchwork\n\n<!-- mcp-name: io.github.SaiNarayana-B/patchwork -->\n\n**Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.**\n\n[![PyPI](https://img.shields.io/pypi/v/patchwork-conventions)](https://pypi.org/project/patchwork-conventions/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![agent-skills](https://img.shields.io/badge/agent--skills-compatible-brightgreen)](https://github.com/topics/agent-skills)\n[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://github.com/topics/mcp)\n\n---\n\nEvery 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.**\n\nYou write a `CLAUDE.md` manually. It goes stale in two weeks. You write it again.\n\n**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.\n\n---\n\n## What it detects\n\n| Category | What's mined |\n|---|---|\n| **Naming** | Functions, classes, variables, constants, files — with confidence score and real examples |\n| **Imports** | Absolute vs relative, path aliases (`@/`, `src/`), barrel files, destructuring style |\n| **Structure** | Source root, test layout, feature vs layer organisation, monorepo detection |\n| **Error Handling** | try/except vs Result types, logging framework, custom exception naming, propagation style |\n| **Testing** | Framework, assertion style, mocking library, coverage tool, fixture patterns |\n| **API Patterns** | Response shape, route param style, ORM, async pattern, GraphQL/gRPC presence |\n| **Git Workflow** | Commit message style, branch naming, co-change file pairs |\n| **Tech Stack** | Frameworks, package manager, linters, formatters, type checker, build tool, scripts |\n\n---\n\n## Quick start\n\n```bash\npip install patchwork-conventions\ncd your-project\npatchwork scan\n```\n\nThat's it. You'll get a `CONVENTIONS.md` like this:\n\n```markdown\n# CONVENTIONS.md\n> Auto-generated by patchwork on 2026-06-25\n\n## Tech Stack\n**Language:** python\n**Runtime:** Python >=3.11\n**Package Manager:** uv\n**Frameworks:** fastapi, sqlalchemy\n**Linters:** ruff\n**Formatters:** ruff, black\n\n## Naming Conventions\n\n### Python\n- **Functions:** `snake_case` (97% consistent)\n  - Examples: `get_user`, `parse_response`, `create_session`\n- **Classes:** `PascalCase` (100% consistent)\n  - Examples: `UserService`, `AuthHandler`, `DatabaseClient`\n- **Constants:** `SCREAMING_SNAKE`\n  - Examples: `MAX_RETRIES`, `API_BASE_URL`\n- **Files:** `snake_case`\n- **Private prefix:** `_`\n- **Test functions:** prefix `test_`\n\n## Project Structure\n**Source root:** `src/`\n**Organisation:** layer-based\n**Tests:** separate (`tests/`)\n\n**Key directories:**\n  - `src/` — source root\n  - `tests/` — test suite\n  - `migrations/` — database migrations\n\n## Error Handling\n\n### Python\n- **Pattern:** try/except\n- **Propagation:** raise\n- **Logging:** `structlog`\n- **Custom exception naming:** Error suffix\n  - `ValidationError`, `AuthError`, `NotFoundError`\n\n## Testing Conventions\n\n### Python\n- **Framework:** pytest\n- **Coverage:** 34 test files / 89 source files (38% ratio)\n- **Assertions:** `assert(...)`\n- **Coverage tool:** `pytest-cov`\n- **Patterns:** fixtures, factories\n\n## Git Conventions\n- **Commit style:** conventional commits\n- **Examples:** `feat(auth): add JWT refresh`, `fix(api): handle null user`\n- **Branch naming:** feature/name + fix/name\n```\n\n---\n\n## Why not argus or sourcebook?\n\n| Feature | patchwork | argus | sourcebook |\n|---|---|---|---|\n| AST-based naming analysis | ✅ tree-sitter | ❌ filesystem only | ❌ not done |\n| Confidence scores | ✅ per-category | ❌ | ❌ |\n| Real examples from your code | ✅ | ❌ | ❌ |\n| Counter-examples (inconsistencies) | ✅ | ❌ | ❌ |\n| Error handling pattern mining | ✅ | ❌ | ❌ |\n| API response shape detection | ✅ | ❌ | ❌ |\n| Co-change file pairs | ✅ | ❌ | ✅ |\n| Convention checking (`check` cmd) | ✅ | ❌ | ❌ |\n| MCP server with 8 tools | ✅ | ❌ | ✅ (4 tools) |\n| Watch mode | ✅ | ✅ (`sync`) | ✅ |\n| Zero LLM required | ✅ | ✅ | ✅ (layer A) |\n| Open source / MIT | ✅ | ✅ | ❌ BSL |\n\n---\n\n## Commands\n\n```bash\n# Generate CONVENTIONS.md\npatchwork scan\n\n# Generate for a specific path\npatchwork scan /path/to/project\n\n# Generate AGENTS.md\npatchwork scan --agents-md\n\n# Append to CLAUDE.md\npatchwork scan --claude-md\n\n# Output JSON (for programmatic use)\npatchwork scan --json\n\n# Print to stdout (don't write file)\npatchwork scan --stdout\n\n# Limit to specific languages\npatchwork scan --lang python --lang typescript\n\n# Re-scan and update, preserving manual edits\npatchwork update\n\n# Show what would change\npatchwork diff\n\n# Print detected conventions to terminal\npatchwork show\n\n# Auto-watch mode (regenerate on change)\npatchwork watch\n\n# Start MCP server\npatchwork serve --stdio    # for Claude Code\npatchwork serve --port 3742  # HTTP mode\n```\n\n---\n\n## Claude Code integration\n\n### Option 1: CONVENTIONS.md (recommended)\n\n```bash\npatchwork scan      # run once\n# CONVENTIONS.md is automatically read by Claude Code\n```\n\n### Option 2: Append to CLAUDE.md\n\n```bash\npatchwork scan --claude-md\n```\n\n### Option 3: MCP server\n\n**Claude Code** — add to `~/.claude.json` (or run `claude mcp add` interactively):\n\n```json\n{\n  \"mcpServers\": {\n    \"patchwork\": {\n      \"command\": \"patchwork\",\n      \"args\": [\"serve\", \"/path/to/your/project\", \"--stdio\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"patchwork\": {\n      \"command\": \"patchwork\",\n      \"args\": [\"serve\", \"/path/to/your/project\", \"--stdio\"]\n    }\n  }\n}\n```\n\n**Cursor** — add to `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"patchwork\": {\n      \"command\": \"patchwork\",\n      \"args\": [\"serve\", \".\", \"--stdio\"]\n    }\n  }\n}\n```\n\nThen your AI agent can use 8 on-demand tools:\n\n| Tool | When to use |\n|---|---|\n| `patchwork_scan` | Get complete conventions overview |\n| `patchwork_naming` | Before writing new identifiers |\n| `patchwork_structure` | Before creating new files/directories |\n| `patchwork_stack` | When choosing libraries or commands |\n| `patchwork_errors` | Before writing error handling |\n| `patchwork_testing` | Before writing test files |\n| `patchwork_git` | Before writing commit messages |\n| `patchwork_check` | Validate a proposed name |\n\n### Option 4: Claude Code skill (SKILL.md)\n\nCopy `SKILL.md` from this repo to `~/.claude/skills/patchwork/SKILL.md` to get `/patchwork` slash commands.\n\n---\n\n## Watch mode (CI/auto-update)\n\n```bash\n# Keep CONVENTIONS.md updated as you code\npatchwork watch &\n\n# Or in CI — fail if conventions changed\npatchwork diff || (patchwork update && git add CONVENTIONS.md && git commit -m \"chore: update conventions\")\n```\n\n---\n\n## Python API\n\n```python\nfrom patchwork import scan\nfrom patchwork.scanner import ScanOptions\nfrom pathlib import Path\n\n# Full scan\nreport = scan(ScanOptions(root=Path(\".\")))\n\n# Render to markdown\nprint(report.to_markdown())\n\n# Render to JSON\nimport json\ndata = json.loads(report.to_json())\n\n# Access specific results\nnaming = report.naming.get(\"python\")\nprint(f\"Functions: {naming.functions.style} ({naming.functions.confidence:.0%})\")\nprint(f\"Examples: {naming.functions.examples}\")\n\nstructure = report.structure\nprint(f\"Source root: {structure.source_root}\")\nprint(f\"Organisation: {structure.organisation}\")\n```\n\n---\n\n## Supported languages\n\n| Language | AST (tree-sitter) | Fallback regex |\n|---|---|---|\n| Python | ✅ full | ✅ |\n| TypeScript | ✅ full | ✅ |\n| JavaScript | ✅ full | ✅ |\n| Go | ✅ (with `full` extra) | ✅ |\n| Rust | ✅ (with `full` extra) | ✅ |\n| Java | ✅ (with `full` extra) | ✅ |\n| Ruby, PHP, C#, C++ | ❌ | ✅ regex only |\n\nInstall full language support:\n\n```bash\npip install 'patchwork-conventions[full]'\n```\n\n---\n\n## How it works\n\n```\nyour codebase\n     │\n     ▼\nConfigDetector        ← reads package.json, pyproject.toml, go.mod, Cargo.toml\n     │\n     ▼\nFile discovery        ← respects .gitignore, skips node_modules etc.\n     │\n     ▼\nPer-language AST      ← tree-sitter parses every file into a syntax tree\n     │\n     ├── NamingMiner       → extracts function/class/variable names, classifies style\n     ├── ImportMiner        → detects import patterns, aliases, barrel files\n     ├── StructureMiner     → analyses directory layout, test co-location\n     ├── ErrorHandlingMiner → detects try/catch patterns, logging, custom exceptions\n     ├── TestingMiner       → identifies framework, assertion style, mocking\n     ├── APIPatternMiner    → finds response shapes, ORMs, route styles\n     └── GitPatternMiner    → mines commit history, branches, co-change pairs\n          │\n          ▼\n     ConventionReport\n          │\n          ├── CONVENTIONS.md  (default)\n          ├── AGENTS.md       (--agents-md)\n          ├── CLAUDE.md       (--claude-md, appends)\n          └── JSON            (--json)\n```\n\nAll analysis is **100% local** — no API calls, no telemetry, no data leaves your machine.\n\n---\n\n## Performance\n\nOn a 1,000-file TypeScript monorepo:\n- Without tree-sitter: ~0.8s\n- With tree-sitter (full AST): ~2.1s\n\nOn a 500-file Python project:\n- ~1.1s\n\nResults are deterministic — same codebase always produces the same output.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/yourusername/patchwork\ncd patchwork\npip install -e '.[dev]'\npytest\n```\n\nPull requests welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## License\n\nMIT — free for personal and commercial use.\n\n---\n\n## Topics\n\n`claude-code` · `agent-skills` · `mcp` · `context-engineering` · `hallucination-detection` · `code-conventions` · `static-analysis` · `tree-sitter` · `developer-tools` · `ai-coding`\n",
  "bytes": 10028,
  "sha": "5a25dba472fe697260755ac2b8061145611e9dcf40c2cfa054a94ef5866a22fc",
  "repo_slug": "sainarayana-b/patchwork",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sainarayana_b_patchwork_b51b6711/readme"
}