Compounding context for AI-coding teams.
ESLint for intent — the linter, the wiki, and the memory your agents are missing.
illuminate.sh · single Rust binary · local-first · MIT
┌─────────────────────────────────────────────────────┐
│ │
▼ │
┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ capture │ → │ extract │ → │ graph │ → │ audit │ │
│ session │ │ entities │ │ + wiki + │ │ guards │ │
│ trails │ │ + edges │ │ index │ │ writes │ │
└─────────┘ └──────────┘ └──────────┘ └────┬────┘
▲ │
│ ▼
┌────┴────┐ ┌──────────┐
│ failure │ ← │ surface │
│ capture │ │ findings │
└─────────┘ └──────────┘
Three input mechanisms feed one knowledge graph, which powers two output surfaces (the linter for agents, the wiki for humans). The loop compounds — three months in, your graph knows what your team rejected, what failed, and what to surface before code is written.
cargo install --git https://github.com/rohansx/illuminate illuminate-cli --locked
cd your-project
illuminate init -n your-project
illuminate audit "add Redis caching to txn lookup"Expected output (with the no_redis policy from docs/GETTING_STARTED.md):
✗ Violations detected:
Policy: no_redis
Found: Redis
Reason: Use in-memory LRU with TTL instead — see dec-no-redis
Severity: Error (confidence: 1.00)
Exit code 2. Wire that into CI and you have machine-enforced architectural guardrails.
→ Full walkthrough: docs/GETTING_STARTED.md
illuminate wiki serve ships a real dashboard, not a CLI prompt:
Screenshots of the live dashboard are captured against
illuminate wiki serve --port 8765after running throughdocs/GETTING_STARTED.md. The capture script is atscripts/capture-screenshots.sh.
| View | URL | What you see |
|---|---|---|
| Home | / |
Stats cards (decisions / patterns / failures / modules / episodes), recent activity feed, quick links |
| Browse | /decisions, /patterns, /failures, /modules |
Filterable list views (status, tag, severity) |
| Page | /page/decisions/dec-no-redis |
Single decision rendered with front-matter card + body markdown + related panel |
| Search | /search?q=caching |
Two-pane: wiki pages + graph episodes (FTS5 + semantic) |
| Audit playground | /audit |
Paste a plan → see the audit response visually. The killer non-CLI surface for the rest of the team |
| JSON API | /api/{stats,pages,page/<id>,search,audit} |
Same data, machine-friendly, for ext integrations |
Dark mode, mobile responsive, no JS framework, no build step — single binary still.
AI coding agents now write a substantial fraction of production code. Tools to generate code have raced ahead. Tools to remember the reasoning behind that code, the failed attempts that shaped it, and the architectural decisions it has to respect — those have not.
Three losses compound silently in every team using Claude Code, Cursor, or Codex:
- Reasoning is lost the moment a session ends. A dev iterates with an agent for an hour, ships the code, and the next reviewer sees the diff and not a word of why.
- Decisions made today are forgotten by next week. "We rejected Redis" — and two weeks later an agent suggests Redis to a different dev, with no memory of the prior decision.
- Failures don't generalize. A bug ships, gets fixed, and the lesson lives only in a post-mortem nobody reads.
Inputs
- Prompt-trail capture — daemon watches Claude Code, Cursor, and Codex sessions and writes normalized trails to
.illuminate/trail/. - Decision extraction — git commits, PR descriptions, ADRs, README,
CLAUDE.md,.illuminate/interview.yamlrun through a local NER pipeline (GLiNER + GLiREL + embeddings via ONNX). - Failure capture —
illuminate failure logandwiki/failures/*.mdproduce graph entities that surface in future audits.
One graph
A bi-temporal, append-only knowledge graph stored as a single SQLite file in .illuminate/graph.db. Built on ctxgraph. Local-first, deterministic queries, no LLM in the query path.
Outputs
- The Linter (machine-readable) — when an agent proposes a change via MCP, Illuminate audits the proposal against the graph and
illuminate.tomlpolicies. Returns violations, warnings, relevant past decisions, prior failures, blast-radius from a code graph (Rust + Go + TS + Python + Java + C), all before code is written. - The Wiki (human-readable) — markdown pages in
git, browsable via the dashboard atilluminate wiki serve, in any editor, or in Obsidian. Decisions, patterns, anti-patterns, failures — all linked, all searchable.
> Add Redis caching to txn lookup endpoint
illuminate_audit response:
Warning: dec-2025-12-no-redis-payments
Team rejected Redis for this service 3 months ago.
Reason: deployment target disallows stateful sidecars.
Alternative: pat-lru-cache-with-ttl (LRU with 30s TTL).
See wiki/decisions/2025-12-no-redis-payments.md
Status: warn
The agent surfaces the past decision to the dev and proposes the LRU pattern instead. The dev didn't have to remember. The agent didn't have to guess.
# Cargo
cargo install --git https://github.com/rohansx/illuminate illuminate-cli --locked
# Homebrew (when published)
brew install rohansx/tap/illuminate
# Prebuilt
curl -L https://github.com/rohansx/illuminate/releases/latest/download/illuminate-x86_64-linux.tar.gz \
| tar xz
sudo mv illuminate /usr/local/bin/Requires Rust 1.85+ if building from source.
Aligned with docs/CLI.md:
illuminate init scaffold .illuminate/, run bootstrap
illuminate bootstrap ingest 5 sources (agent files, ADRs, git, README, interview)
illuminate audit "<plan>" check plan against policies + graph (exit 0/2/3)
illuminate audit-diff [BASE] audit changes since git base (default HEAD~1)
illuminate audit-pr <num> audit a GitHub PR (uses gh CLI; --comment posts back)
illuminate impact <files...> blast-radius for files (defined symbols, imports, BFS)
illuminate explain <path> decisions/patterns/failures touching a file
illuminate failure log ... record a new failure inline
illuminate decisions list/show/for <path>
illuminate patterns list/show
illuminate failures list/show
illuminate index build code-graph (symbols + edges)
illuminate search "<q>" FTS5 + semantic search across graph
illuminate rebuild rebuild graph.db from wiki + trail
illuminate wiki serve launch the dashboard at http://127.0.0.1:8765
illuminate wiki redact "<re>" bulk-redact regex across wiki + graph
illuminate trail import/list/register/watch/install-service
illuminate mcp serve MCP server (stdio default; --http for Streamable HTTP)
illuminate models download fetch ONNX models (~150 MB, optional)
audit exit codes: 0 pass, 2 violation (CI should block), 3 warn.
Drop-in GitHub Action — see docs/CI.md:
on: pull_request
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: rohansx/illuminate/.github/actions/audit-pr@masterCalls illuminate audit-pr ${{ github.event.pull_request.number }} --comment --format markdown. Posts findings as a PR comment via gh. Block on exit 2.
your-project/
├── .illuminate/
│ ├── illuminate.toml # config + policies (in git)
│ ├── interview.yaml # optional onboarding answers (in git)
│ ├── graph.db # SQLite (gitignored, regeneratable)
│ ├── index.db # code graph (gitignored)
│ ├── wiki/ # markdown (in git, team-shared)
│ │ ├── decisions/
│ │ ├── patterns/
│ │ ├── failures/
│ │ └── modules/
│ └── trail/ # raw session jsonl (gitignored)
└── CLAUDE.md # contains audit-pre-write directive
wiki/ is the team-shared source-of-truth. graph.db, index.db, and trail/ are local caches, regeneratable from wiki/ + agent session history.
See docs/SCHEMA.md for the wiki page schema.
Twelve Rust crates, one binary:
| Crate | Responsibility |
|---|---|
illuminate-core |
Graph API on top of ctxgraph |
illuminate-config |
Shared illuminate.toml parsers (audit, trail, extraction, mcp.http) |
illuminate-trail |
Session capture (Claude Code, Cursor, Codex) |
illuminate-extract |
NER pipeline (GLiNER + GLiREL via ONNX) |
illuminate-embed |
all-MiniLM-L6-v2 embeddings (local) |
illuminate-index |
tree-sitter symbols + edges (Rust/Go/TS/Python/Java/C) |
illuminate-audit |
Policy engine + graph queries + semantic top-k |
illuminate-bootstrap |
5 bootstrap sources |
illuminate-watch |
Daemon harness + git/GitHub ingestion |
illuminate-reflect |
Reflexion store (failure capture) |
illuminate-route |
Reading-plan generator (FTS5 + semantic RRF) |
illuminate-wiki |
Markdown layer + the serve dashboard |
illuminate-mcp |
JSON-RPC MCP server (stdio + HTTP) |
illuminate-cli |
The binary |
See docs/ARCHITECTURE.md for the two-graph diagram (code graph ↔ decision graph) and the audit lifecycle.
- Getting started — step-by-step walkthrough (validated end-to-end before each release)
- Product overview — what it does, why it works, how it positions
- Architecture — components, data flow, the two-graph join
- Schema — markdown wiki schema
- Ingestion — three input pipelines
- Audit — the linter, in detail
- Bootstrap — cold-start population (5 sources)
- CLI — command reference
- MCP — agent-facing tool contract (stdio + HTTP)
- Crates — per-crate API
- Privacy — data residency, threat model
- Roadmap — milestones
- Changelog — per-version log
- Local-first — all capture, storage, and queries run on the dev's machine. No required cloud.
- Single binary — no Docker, no Python, no Neo4j. One Rust binary, one SQLite file per repo.
- Deterministic queries — no LLM in the audit/query path. Same input → same output. LLM fallback only during ingestion (~30%, with PII strip via the optional
cloakpipefeature). - Append-only graph — bi-temporal storage. Supersession is a new fact, not a mutation.
- Markdown is source-of-truth — the graph indexes the wiki. Delete the graph; rebuild from wiki + trail.
- Compounding — the graph gets stronger with use. Three months in, switching off Illuminate means losing the team's accumulated context.
| Operation | Cost |
|---|---|
| ~70% of extraction (local ONNX) | $0 |
| ~30% of extraction (LLM fallback, optional) | ~$0.0003/episode |
| All queries / audit / search | $0 (fully local) |
| Per 1,000 episodes | ~$0.30 (vs Graphiti's ~$1.80) |
Set [extraction.llm] provider = "none" to run fully offline at $0.
ctxgraph— bi-temporal knowledge graph engine (2.4× F1 vs Graphiti, ~250× faster)tree-sitter— incremental code parsing- GLiNER + GLiREL — local NER (ONNX)
axum— MCP HTTP transporttiny_http— wiki dashboard server
Format knowledge for Cursor / Codex parsers ported from codeburn (MIT). Edge model + impact_radius informed by code-review-graph (MIT). See docs/ARCHITECTURE.md's Related Projects section.
The closed loop is real and end-to-end:
- Capture: Claude Code, Cursor, Codex sessions all parsed.
- Extract: trail register / failures register run the GLiNER + GLiREL ONNX pipeline; entities and relations land in the graph.
- Audit: policies, decision conflicts, semantic top-k via
Graph::search_fused, code-graph blast-radius via recursive-CTE BFS over function-call edges. - Surfaces: CLI, MCP server (stdio + Streamable HTTP), GitHub Action, wiki dashboard at
illuminate wiki serve(home / browse / search / audit playground / JSON API). - Bootstrap: 5 sources wired (agent files, ADRs, git history, README/CONTRIBUTING, interview YAML).
See CHANGELOG.md for the per-version log and docs/ROADMAP.md for what's still deferred.
MIT.
Suggested GitHub repository metadata (paste into the About panel + Topics)
Description: Compounding context for AI-coding teams. ESLint for intent: capture prompt-trails → graph → audit agent plans before code is written. Single Rust binary, local-first, MCP-native.
Website: https://illuminate.sh
Topics:
knowledge-graph rust mcp ai-agents ci local-first linter
wiki-as-code claude-code cursor codex tree-sitter onnx
audit-tool decision-graph context-engineering