Codiluce

Why Codiluce?

The comprehension gap is widening. More people and more agents are writing code, and every change is bigger than the last. Reading the diff no longer tells a team what the system does, which flows a change touches, or what it can break.

Codiluce keeps understanding in step with the code. It reads your repository and draws it as a map you can zoom, search and replay, in 3D or as a flat 2D plan, where every link between pages, requests, functions and tables comes with the evidence behind it. Your agents explain the code on that map, and you watch each of them walk through the files it touches while it works.

Multilingual compatibility milestone

The initial multilingual compatibility milestone is closed with documented limitations on main. The roadmap closure records the delivered language/import/framework subsets, existing correctness evidence and deferred follow-ups. The completed Flask comparison shows a 15.1% slowdown, above the unchanged 10% target; production performance, complete memory budgets, broader syntax/version coverage and native Windows/macOS qualification remain unqualified. Benchmarking and further optimization have stopped. See the capability/version matrix for the supported static subsets.

Quick start

Run it inside the repository you want to see:

npx codiluce@latest start .

Codiluce indexes the code, starts a local server and opens the map in your browser. You need Node.js 22.12 or newer.

Keep the command running while using the map. After restarting it, finish any setup questions and open the printed URL; a browser tab left open while the server is stopped cannot load agent activity or explanations.

The first time, it asks whether to precompute architecture snapshots (optional; Git file evolution is available immediately), which API keys to use for the optional language-model features, and which coding agents to connect. Enter keeps the defaults; codiluce setup asks again. The analysis lives in .codiluce/, which hides itself from Git.

On your first visit, the map offers a two-minute tour. It follows one of your files across the map, its code, the flow it is part of, what depends on it and its history. Take it again, or one of its chapters, from Help at the foot of the rail.

Want it always at hand? Run npm install --global codiluce, then codiluce start . in any repository.

Work with your agents

Codiluce is made for code that agents write. Connect Claude Code, Codex, OpenCode, Pi or another supported harness: they explain the code on your map, and Agents shows you what every session is touching while it works.

Twelve harness families have adapters, including Cursor, GitHub Copilot, Gemini CLI, Cline, Antigravity, Windsurf / Devin Desktop, OpenClaw and Hermes. New adapters are experimental and expose separate MCP, activity and history capabilities. See the connection guide for exact runtime profiles and limitations.

npx codiluce@latest harness setup --agent opencode          # preview MCP and activity files
npx codiluce@latest harness setup --agent opencode --apply  # merge the configuration
npx codiluce@latest harness setup --agent pi --apply

Ask your agent, read the answer on the map

Connect your agent to Codiluce's MCP server, from the repository:

claude mcp add codiluce -- npx -y codiluce@latest mcp

Keep @latest (or a version): with a bare codiluce, npx starts any global install or cached copy first, which can be older than your map.

codiluce setup (also offered on the first start) detects installed harnesses and connects their MCP server, and their activity hooks for this repository, so their work also shows in Agents. Then ask in your own words, for example "Use Codiluce to explain how checkout works, and publish it." Its tools read the index (flows, blast radius, history, source), so the agent starts from what the code provably does instead of guessing from file names.

• Watch it explain. While the agent works, the map's Explain column shows a card with what it is explaining, your question and each tool it calls.
• Every link checked. publish_explanation checks that every file, symbol and flow the answer names exists, then saves it in the column. Point at a link and that code lights up on the map; click it to open it.
• Never silently stale. Each explanation is pinned to the commit it was written against and says when the code it links changes.
• No agent at hand? With an Anthropic or OpenAI key, ask in the column itself, with files and folders attached by @.
• Start from a template. Open Templates in Explain, or type / in an empty question. Search common questions, fill their placeholders, then ask in the map or copy the question for your agent. MCP clients also expose them as prompts.

This is the beginning of the README. Read the rest at the original. Read the full README ↗