Metadata-Version: 2.4
Name: crg-lean
Version: 1.0.0
Summary: Token-efficient code-review-graph wrapper for AI coding agents
Project-URL: Repository, https://github.com/nofriiza/crg-lean
License: MIT License
        
        Copyright (c) 2026 Fajar Nofriza
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,claude,code-intelligence,code-review-graph,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# crg-lean

Token-efficient wrapper for [code-review-graph](https://github.com/tirth8205/code-review-graph).

The raw code-review-graph MCP tools return 15k–24k tokens per query — full absolute paths, raw graph edges, source code dumps. crg-lean strips the fat, converts paths to relative, and returns only what's useful: **10–87× fewer tokens per query**.

## Real measurements (53-file Next.js project)

| Query | Raw MCP | crg-lean | Reduction |
|---|---|---|---|
| detect changes | ~5,456 tok | ~156 tok | **35×** |
| impact radius | ~15,517 tok | ~179 tok | **87×** |
| minimal context | ~101 tok | ~73 tok | 1.4× |

## Requirements

- Python 3.8+
- [`code-review-graph`](https://github.com/tirth8205/code-review-graph) (`pip install code-review-graph`)

## Install

```bash
bash install.sh
```

Or manually:

```bash
cp crg-lean ~/.local/bin/crg-lean
chmod +x ~/.local/bin/crg-lean
```

## One-command project setup

Run once in any project directory:

```bash
crg-lean setup
```

This automatically:
1. Installs `code-review-graph` if missing (tries pipx → uv → pip)
2. Builds the code graph
3. Adds `.code-review-graph/` to `.gitignore`
4. Wires `SessionStart` + `PostToolUse` hooks in `.claude/settings.json`
5. Installs `post-commit`, `post-merge`, `post-rebase` git hooks (monorepo-aware)
6. Creates/updates `CLAUDE.md` with an architecture section

Idempotent — safe to re-run, skips steps already done.

## Commands

```bash
crg-lean setup                   # bootstrap a project (run once)
crg-lean changes                 # what changed since last commit + risk score
crg-lean find "<symbol>"         # locate a symbol → file:start-end (N lines)
crg-lean impact [file ...]       # blast radius — which files are affected
crg-lean context "<concept>"     # keyword search — does this already exist?
crg-lean stats                   # graph overview (files, nodes, languages)
crg-lean update-claude           # refresh architecture section in CLAUDE.md
```

## Surgical read workflow

```bash
# 1. Find exact location
crg-lean find "authenticate"
# → src/utils/jwt.ts:7-18  (12 lines)

# 2. Read only those lines
# Read(src/utils/jwt.ts, offset=7, limit=12)
# ~48 tokens vs ~1,200 for the full file
```

## Auto-updating CLAUDE.md

`crg-lean setup` installs three git hooks that keep `CLAUDE.md` current:

- `post-commit` — after every local commit
- `post-merge` — after every `git pull` (picks up changes from other machines)
- `post-rebase` — after every rebase

The hooks only update the `<!-- arch:start --> ... <!-- arch:end -->` block. Human-written content below `<!-- preserved-below -->` is never touched.

Works in monorepos — each service can have its own `CLAUDE.md` and the hooks update all of them.

## Claude Code skill

crg-lean ships as a Claude Code skill. Install it globally:

```bash
mkdir -p ~/.claude/skills/crg-lean
cp skills/crg-lean/SKILL.md ~/.claude/skills/crg-lean/SKILL.md
```

This tells Claude when and how to use crg-lean automatically, without being prompted.

## How it works

crg-lean starts the `code-review-graph serve` MCP server as a subprocess, calls tools via JSON-RPC, then post-processes responses:

- Strips absolute paths → relative paths
- Removes fat fields: `affected_flows`, `review_priorities`, `edges`, `impacted_nodes`, `context`
- Limits arrays to top N
- Returns plain text instead of JSON

The MCP server is started fresh per invocation (~0.5s). No persistent daemon.
