codegraph-ir 0.3.0

The deterministic contract layer for AI-modified codebases — effects, purity, contracts, and blast radius, with zero LLM calls.

CodeGraph IR (CGIR)

The deterministic contract layer for AI-modified codebases. Agents write more of the code than you can review. CGIR reads a repo and — with zero LLM calls — tells you what each component is (effects, purity, contract, entrypoints, call surface) and whether a change altered it. Think ruff, but for architecture instead of style: fast, static, hallucination-free.

Distributed as codegraph-ir; the command and import package are both cgir.

Install

uv tool install codegraph-ir      # isolated CLI (recommended); or: pipx install codegraph-ir
cgir --version

For library/agent use in a project: uv pip install codegraph-ir (extras: [mcp] for the agent server, [api] for the HTTP surface, [llm] for regeneration).

The local loop

cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
cgir watch .                         # keep it live: re-scan + show contract drift on save
cgir pack app.service.charge --repo .   # minimal context bundle for one component
cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests
cgir impact app.service.charge --candidate new.py --repo .   # radius narrowed by the real delta
cgir verify app.service.charge --candidate new.py --repo .   # contract-check an edit
cgir hook install                    # pre-commit seatbelt: block contract-breaking commits
cgir lsp                             # editor squiggles for pin violations + drift (cgir[lsp])

pack → edit → impact → verify → hook, with watch keeping the index fresh underneath — an always-on membrane you and your agent both consult.

Gate CI on contract drift

The GitHub Action scans a PR's base and head and fails the build on drift — a pure function that starts hitting the network, a service that stops persisting, a new POST /admin route — deterministically, with no per-seat LLM cost:

- uses: asonkiya/llm-semantic-compilers@v0
  with:
    fail-on: "effect-gain:net effect-gain:fs effect-gain:db effect-loss:net effect-loss:fs effect-loss:db"

The default rule set is evidence-based: replaying real commit history, the I/O effect rules fire on ~0–10% of commits, each a genuine change in a component's I/O surface.

Agents as first-class users

cgir mcp --index .cgir serves the index over MCP. Instead of grepping, an agent calls search / pack to load minimal context, impact to see what a change touches, and verify / impact_of_change to contract-check its own edit before proposing it. See examples/ for a worked agent-PR case study.

Setup guide for agents (MCP config + CLAUDE.md snippet): docs/agents.md. Or via the pre-commit framework: hook id cgir-contract-check.

Docs

• docs/strategy.md — positioning: the deterministic contract layer
• docs/status.md — what runs today, test coverage, milestones
• docs/gate-noise.md — false-alarm measurement on real history
• docs/github-action.md — CI contract-diff gate
• docs/experiment-log.md — rewrite-readiness / contract-preservation benchmarks
• docs/architecture.md — layered pipeline, data model, extension seams
• docs/languages.md — adding a language (the LanguageAdapter seam)
• Code-IR.md — full product specification
• RELEASING.md — how to cut a release

License

MIT — see LICENSE.