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.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
