LeanCI

Dependency-aware AI pull request review with measured Paritok compression.

LeanCI is a GitHub Action that reviews PRs beyond the diff: it expands Python imports, call sites, and related tests, runs an OpenAI-compatible agent through a local Paritok proxy, then posts findings plus an honest cost receipt (tokens / estimated USD / reduction %).

Built with Paritok.

Judge quick links: PR #3 · Actions run 30629133302 · Demo · Screenshots · Sample metrics · Demo instructions

---

🎬 Demo

Watch the product walkthrough: https://youtu.be/q11tOEWsQZM

Repository copy: docs/media/leanci-demo.mp4

---

Project overview

LeanCI makes deep, cross-file PR review affordable by putting Paritok token compression on the agent tool path. Judges and adopters can verify savings with a dual-run receipt, not marketing claims.

Type	Composite GitHub Action + Python package (leanci)
Language (MVP)	Python 3.11+
License	Apache-2.0
Demo	demo/ planted cross-file bug + mode=dual_run workflow

---

Problem statement

AI PR reviewers are useful but expensive: tool-heavy agent loops send large contexts (files, search hits, history) to the LLM on every turn. Teams either:

1. Review only the diff and miss cross-file contract breaks, or
2. Expand context aggressively and burn tokens until the review no longer pencils out.

Cross-file bugs (e.g. a helper’s return type changes while callers still assume the old shape) are exactly what shallow diff review misses—and what deep review costs the most to find.

---

Solution

LeanCI combines three ideas:

1. Bounded dependency expansion — seed from the PR diff, then add imports, reverse call sites, and related tests under hard caps.
2. Paritok on the compressed path — the agent talks to a local Paritok OpenAI-compatible proxy; Paritok compresses eligible tool/content traffic to the upstream model.
3. Measured economics — optional dual_run executes an uncompressed baseline on the same expansion set and publishes a side-by-side cost receipt with honesty labels when compression is weak.

The demo proves the loop: a planted validate_charge tuple/bool contract break is caught citing both payments/charge.py and api/checkout.py, with metrics + assert gate.

---

How Paritok is used

Paritok sits on the compressed agent path, not as a decorative badge:

1. The Action starts a local Paritok OpenAI-compatible proxy on the GitHub runner (use_gpu_server: true — see paritok.yaml.example).
2. Eligible tool/content traffic is compressed on Paritok’s hosted GPU, then forwarded to the upstream OpenAI-compatible model.
3. Receipts attribute primary input tokens to the Paritok /stats domain (content Paritok intervenes in), with assumptions labeled on the PR comment.
4. Optional mode: dual_run runs an uncompressed baseline on the same expanded file set so savings are measured side-by-side.
5. When compression is weak, receipts include honesty labels — do not market a fixed savings rate. Compression depends on workload.

Hackathon / demo proof: PR #3 + Actions run 30629133302 → 22,601 → 9,405 Paritok-domain input tokens (58.4%), est. USD $0.001130 → $0.000470. Smaller repositories may show much lower savings. Sample artifact: examples/leanci-metrics.dual_run.30629133302.json.

---

Architecture

GitHub Action (action/)
  └─ ParitokGateway (local proxy) ──► Paritok GPU + upstream LLM
  └─ python -m leanci
        ├─ DiffCollector
        ├─ DependencyExpander → ContextManifest
        ├─ AgentRuntime ↔ ToolHost (read/search)
        │     └─ LLMClient(compressed via Paritok)
        ├─ DualRunController (optional)
        │     └─ LLMClient(uncompressed provider URL)
        ├─ FindingNormalizer
        ├─ ReceiptBuilder + PricingTable
        ├─ GitHubPublisher (idempotent PR comment)
        └─ MetricsExporter (leanci-metrics.json artifact)

Data that leaves the runner: PR source needed for the review (to Paritok GPU + upstream LLM), GitHub API comment traffic, and Actions logs/artifacts. There is no LeanCI-hosted database.

---

Workflow

Consumer (default): Paritok-only

1. PR opened / synchronized → .github/workflows/leanci.yml
2. Checkout with fetch-depth: 0
3. Start Paritok proxy (OPENAI_BASE_URL=http://127.0.0.1:8080/v1)
4. Diff → expand → agent (compressed) → normalize → receipt → PR comment
5. Upload leanci-metrics.json

Demo: dual-run + planted-bug assert

1. Changes under demo/ (and related paths) → .github/workflows/demo-leanci.yml
2. Same pipeline with mode: dual_run and LEANCI_PATH_PREFIX=demo/
3. Assert job runs scripts/assert_planted_bug.py on the metrics artifact

---

Screenshots / GIF

Assets under docs/media/ — numbers from a live dual-run on PR #3 (Actions run 30629133302): 22,601 → 9,405 Paritok-domain input tokens (58.4% reduction), estimated USD $0.001130 → $0.000470.

LeanCI + Paritok data flow: diff → expand → agent via Paritok → findings + receipt.

PR comment: high-severity planted contract break + dual-run cost receipt showing lower Paritok tokens/cost.

Side-by-side Uncompressed vs Paritok: ~58% fewer input tokens on the compressed path; parity true on both paths.

Green LeanCI Demo: dual_run + assert-planted-bug (same run as the receipt above).

Workflow: LeanCI Demo.

Installation

Local package (dev / tests)

git clone https://github.com/CodewithJha/leanci.git
cd leanci
python -m pip install -e ".[dev]"
python -m pytest

Optional: uv sync / uv run pytest if you use uv.

As a GitHub Action (this repo)

The composite action lives at action/ and is invoked with uses: ./action from workflows in this repository.

As a reusable Action (consumer repos)

After tagging a release (e.g. v0.1.0-mvp):

uses: CodewithJha/leanci/action@v0.1.0-mvp

---

GitHub Action setup

1. Add a workflow

Minimal consumer template (also see .github/workflows/leanci.yml):

name: LeanCI

on:
  pull_request:
    types: [opened, synchronize, reopened]
  workflow_dispatch: {}

permissions:
  contents: read
  pull-requests: write

jobs:
  leanci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: CodewithJha/leanci/action@v0.1.0-mvp   # or ./action in this repo
        with:
          # mode: paritok          # default
          # mode: dual_run         # demo / measurement only
          openai_url: https://api.groq.com/openai   # example upstream
          model: llama-3.1-8b-instant
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PARITOK_API_KEY: ${{ secrets.PARITOK_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

2. Action inputs (selected)

Input	Default	Notes
mode	paritok	paritok | dual_run
model	gpt-4.1-mini	Upstream model id
openai_url	(empty)	Passed to Paritok as --openai-url
max_files / max_bytes	20 / 400000	Expansion caps
max_tool_turns / max_findings	24 / 8	Agent / publish caps
severity_floor	medium	Drop findings below floor
fail_on_error	true	Fail job on hard review errors

3. Confirm success

• Workflow green
• PR comment containing <!-- leanci:review -->
• Artifact leanci-metrics → leanci-metrics.json

Target setup time: ≤ 10 minutes once secrets exist.

---

Required secrets

Configure under Settings → Secrets and variables → Actions:

Secret	Required	Purpose
PARITOK_API_KEY	Yes	Paritok GPU proxy (use_gpu_server: true)
OPENAI_API_KEY	Yes	Upstream provider key (OpenAI-compatible)
GITHUB_TOKEN	Automatic	Actions-provided; used for PR comments

Do not commit keys. Runtime config is written under $RUNNER_TEMP (see paritok.yaml.example); PARITOK_API_KEY is injected via the process environment.

---

Supported providers

LeanCI’s LLM client is OpenAI-compatible (/v1/chat/completions + tools). Anything Paritok can forward works in principle.

Provider	Notes
Groq	Used in this repo’s CI demos (openai_url: https://api.groq.com/openai). Cloudflare UA quirks handled via a small local forwarder when needed.
OpenAI	Default uncompressed dual-run base when LEANCI_OPENAI_URL is unset.
OpenRouter / others	Set openai_url + matching OPENAI_API_KEY; watch rate limits and tool-calling quality.

Dual-run uncompressed traffic uses LEANCI_OPENAI_URL (provider base, not the Paritok proxy).

---

Demo instructions

Verify without secrets (recommended for judges)

1. Open PR #3 and read the LeanCI review comment (finding + cost receipt).
2. Open Actions run 30629133302 — green leanci-dual + assert-planted-bug.
3. Skim docs/media/ and examples/ (real metrics JSON from that run).
4. Optional: watch the demo video once the YouTube/Vimeo link is added above.

Planted bug

See demo/README.md:

• demo/src/payments/charge.py — validate_charge returns (ok, reason)
• demo/src/api/checkout.py — still treats the return as a boolean (tuple is always truthy)
• demo/tests/test_checkout_happy.py — happy path only; CI stays green

Run the demo gate

1. Ensure PARITOK_API_KEY and OPENAI_API_KEY are set.
2. Open a PR that touches demo/ (or re-run LeanCI Demo via workflow_dispatch).
3. Wait for leanci-dual then assert-planted-bug.
4. Inspect the PR comment receipt and download the metrics artifact.
5. Locally (optional):

python scripts/assert_planted_bug.py --metrics path/to/leanci-metrics.json

---

Repository structure

leanci/
├── LICENSE
├── README.md
├── pyproject.toml
├── paritok.yaml.example
├── action/                 # Composite GitHub Action
├── src/leanci/             # Package: orchestrator, expand, agent, dual, receipt…
├── demo/                   # Planted-bug toy service + dual_run template
├── scripts/
│   └── assert_planted_bug.py
├── examples/               # Real dual-run metrics sample (run 30629133302)
├── docs/
│   ├── PRD.md
│   ├── media/              # Architecture, PR comment, receipt GIF, Actions
│   ├── devpost_submission.md
│   └── superpowers/specs/  # TDD
├── SUBMIT_NOW.md           # Devpost submit checklist
├── tests/
└── .github/workflows/
    ├── leanci.yml          # Consumer template (paritok)
    ├── demo-leanci.yml     # dual_run + assert
    └── demo-assert.yml

---

Limitations

• Python-first expansion — AST imports + ripgrep heuristics; not full program analysis.
• Heuristic, capped context — may miss distant callers when caps hit.
• Line numbers may be approximate; findings prefer file + symbol when unsure.
• Dual-run doubles LLM spend — opt-in; intended for demos/measurement.
• Provider tool-calling quality varies — some models emit malformed tool XML (retried / nudged).
• Compression % is workload-dependent — tiny demos may show ~0% reduction; receipts label near-ineffective compression honestly (do not market a fixed %).
• Private repos — code leaves the runner to Paritok + the LLM provider; hackathon demo is public.

Threat model (brief)

Trust boundary	What crosses it
GitHub runner → Paritok GPU	Review context / tool payloads (compressed path)
Runner / forwarder → upstream LLM	Chat + tools (compressed via Paritok; uncompressed on dual_run)
Runner → GitHub API	PR comment bodies (no secrets)

Secrets stay in Actions secrets / env; never in committed YAML.

---

Future work

Aligned with PRD stretch goals:

• TypeScript expansion (S1)
• Inline review comments (S2)
• Hard token/budget ceilings (S3)
• .leanci.yml policy packs (S4)
• Org cost rollups (S5)
• Cross-PR compression cache (S6)
• Check-run gating on severity (S8)

---

Acknowledgements

• Paritok — token compression middleware that makes tool-heavy review economically viable; LeanCI’s compressed path is designed around Paritok’s OpenAI-compatible proxy and /stats attribution.
• GitHub Actions / checkout / artifact ecosystem.
• Upstream model providers used in demos (e.g. Groq OpenAI-compatible API).
• Spec and product direction in docs/PRD.md and the MVP TDD under docs/superpowers/specs/.

---

License

Copyright 2026 Priyanshu Jha. Licensed under the Apache License 2.0.