codetopo — development log

How codetopo got here, and where it is going — in plain words.

codetopo turns a source repository into a queryable code graph — symbols, calls, references, structure — with answers an AI coding agent can act on directly. This page is the public story of the build: what shipped, what it means if you use codetopo, and what is being worked on next. It is kept with the releases — every release adds its entry here in the same change. The demo itself is on the front page.

The story so far

November 2, 2026 — 0.9.0: the analytics engine

codetopo's ranking learns the classic graph measures. Where it once ranked symbols four ways, it now answers nine: the original four, unchanged to the byte, plus five measures every network-science textbook defines — which symbols everything flows through, which sit closest to all the rest, and which matter because important things point at them. Three new tools join the seventeen, on the command line, over HTTP, and through the agent tools alike: one finds the natural communities inside a codebase and scores how cleanly they separate; one lays the graph out in dependency order; and one draws it — a force-directed map as SVG, drawn identically every time it is asked. Every number still travels with its method and its settings; where a measure honestly cannot converge on a very large graph, codetopo says so, with the reason, instead of returning half an answer. The proof is pinned in the open: the new measures were checked against the standard reference implementations (networkx and igraph) and agree to the last decimal places that matter, twice-run outputs are byte-identical, and on a graph of forty thousand symbols the slowest measure finishes in about half a minute. The schema stays at 1.2 — nothing stored changes, and snapshots keep reading. All eight crates move to 0.9.0 together. 0.9.0 is a release candidate since November 2, 2026 — it graduates after a clean watched week.

November 2, 2026 — 0.8.0: Python joins

codetopo now reads Python. Files ending .py and .pyi are indexed through the same contract as Rust and TypeScript/JavaScript: packages and modules (an __init__.py stands for its package), classes, functions and methods, module-level variables, and imports — absolute, relative, and future — resolved at module level. Protocol classes are recognised as interfaces. Every Python symbol carries the measured fields the analytics engine feeds on — its signature, its line span, and its counted decision points — so complexity, coupling, and ranking work on Python code exactly as they do on the other languages, on the command line, over HTTP, and through the seventeen agent tools alike. The schema that describes all of this rises to 1.2, additively: snapshots written by older versions keep reading. Where Python defines a name twice — an overload, a property and its setter — the index says so, with both locations, instead of silently picking one. The proof is pinned in the open: hand-counted fixtures, a known-answer package whose expected graph is published arithmetic, and a cross-check against a real-world codebase (pallets/click) reconciled row-for-row against CPython's own count of its definitions. All eight crates move to 0.8.0 together. 0.8.0 is a release candidate since November 2, 2026 — it graduates after a clean watched week.

October 30, 2026 — Listing copy brought current

A housekeeping pass over the pages that directories and agents read: the launch guide, the Gemini extension manifest, and the agent install guide still described the twelve tools of an older release. They now name all seventeen, including the diagnostics, ranking, comparison, metrics, and history tools the analytics work added. No code changed.

October 25, 2026 — 0.7.0: the analytics engine, complete

codetopo now measures what it indexes. Every function and method carries its size in lines and its cyclomatic complexity — counted decision points plus one, with the counting rules published and the method stated wherever the number appears. Types carry coupling and cohesion measurements: how many other types they touch, what they can reach, and how far their methods share the type's own state. Packages carry their dependency balance — what depends on them, what they depend on, and how much of that points outward — with links to external libraries counted separately, never merged in. And on your own machine, codetopo reads a repository's git history to find its hotspots — the files that change often and are complex at once, both factors always shown — and the files that change together, reported as the counts themselves. Hosted indexes carry no history, and there the answer is honestly "not measured", never an invented number. Every one of these is a measurement with a stated method; codetopo still ships no verdicts about whether code is good. All of it arrives on the same three doors — command line, HTTP, and the agent tools — and all eight crates move to 0.7.0 together. 0.7.0 is a release candidate since October 25, 2026 — it graduates after a clean watched week; the published packages and the hosted service pick it up at graduation.

October 20, 2026 — 0.6.0: the analytics get deeper

codetopo's answers grow a layer. Asking about one symbol now returns its dossier — the symbol itself plus every connection it has, grouped by kind, with the counts stated first — the shape the design specified from the start. The warnings recorded while an index was built (dependency cycles, symbols defined twice, calls that resolve to nothing) can now be read by agents too, not only printed by the command line. Symbols can be ranked by how much depends on them, how much they depend on, and how much breaks if they change — measurements, with the method stated beside the numbers, never a score of whether code is good. And two indexes can be compared directly: what was added, what was removed, what changed, and how the blast radius of every touched symbol moved. All of it arrives on the same three doors — command line, HTTP, and the agent tools — and all eight crates move to 0.6.0 together. 0.6.0 is a release candidate since October 20, 2026 — it graduates on October 27, 2026 after a clean watched week; the published packages and the hosted service pick it up at graduation.

October 18–19, 2026 — The hosted API goes live

codetopo Hosted is a real thing you can buy now: US$19 a month for a hosted key — up to 25 indexes of your own and 10,000 queries a month — without running a server yourself. Before it opened, the whole trip was walked the way a customer walks it: pay, claim the key (it is shown exactly once), ask the API real questions about a real repository, cancel, and watch the key stop working. It all held.

October 14, 2026 — 0.5.0: one version everywhere

All seven crates moved onto a single version line, 0.5.0, and were published together: crates.io, the GitHub release, and the official MCP Registry all say the same number. Before this, different pieces of codetopo carried three different versions at once; now, whatever you install agrees with everything else.

October 14, 2026 — A hosted service, built in stages

Underneath the launch, the hosted path was assembled piece by piece, each piece tested before the next landed: a real key store, where your indexes belong to your key — another key asking for your index gets the same answer as asking for one that does not exist; hosted ingest, where you hand the API a public repository URL or an archive instead of a path on a machine; plan limits, the envelope that keeps one key from eating the host; and a billing bridge that turns a payment into a key and a cancellation into a revocation. When the first customer-walk found a rough edge — the claim page arrived blank and made you hunt down a session id — the page learned to arrive pre-filled.

October 14, 2026 — The release gate, and fixing what it found

codetopo went through the same release gate every product here faces, and the fixes shipped the same day. API errors no longer leak internal detail. The quickstart no longer plants a published example password — it generates a random one, and the server refuses a keys file still carrying the example. Older indexes stop being readable by every key once a second key exists. And the README says plainly how to delete your data and how to export it.

October 14, 2026 — Listed where agents look

Glama approved the listing after inspecting the running server itself — all twelve tools, live. The Smithery bundle was refreshed at 0.5.0, and a Gemini CLI extension in the repository puts codetopo in the Gemini extensions gallery. Whichever door your agent uses, it finds the same codetopo.

October 13, 2026 — 0.3.5: tools that introduce themselves

Every MCP tool gained a human-readable title and honest annotations — what it does, that it is read-only — so agent clients and directories can present the tools properly. The README gained a Privacy Policy section the same day.

October 11, 2026 — 0.3.4: Windows works

The MCP server had never compiled on Windows — one part of it used Unix-only plumbing. It has a proper Win32 implementation now, and CI builds the shipped binaries on Windows so this cannot silently break again. Found, fittingly, by making the first Windows build in the project's history.

October 10, 2026 — 0.4.0: a trust setup for editor agents

Agents that speak the Agent Client Protocol gained codetopo-trust-setup: a one-time setup in your terminal that creates a local proof-verification key. Snapshots the agent takes can then be signed, and its answers can cite who stands behind them. codetopo still has no accounts — the only secret is a key that never leaves your machine.

October 10, 2026 — 0.3.0: published, and measured at 10,000 files

All seven crates reached crates.io for the first time; a few small listing releases followed over the next day to get the registry pages rendering right. The same stretch brought codetopo render — a picture of your graph that is a pure function of the data, byte-identical on any machine — a self-hosted Docker container, and a demo snapshot that re-captures itself on every merge, so this site never goes stale. And the scale gate: a 10,000-file repository indexed in about 3.5 seconds. The gate earned its keep — a very deep call chain crashed the cycle detector, which is now built so depth is limited by memory, not by a stack.

October 5, 2026 — 0.2.0: the first public release

One engine, four doors. The core turns a repository into a graph — symbols, calls, references, structure — stored with a tamper-evident audit log. On top of it: a command-line tool, an HTTP API, an MCP server for agents, and an ACP agent for editors. All four answer the same questions with the same answers, because all four are thin doors over the same core.

What is coming

Drawn from the design in the repository (DESIGN.md). Directions, not promises — and no dates, because honest phase words beat invented deadlines.

Next — Deeper still: richer extraction

The design's derived views — complexity among them — need the extractors to capture more of each symbol than they do today: where it ends, its signature, its branching. With that in hand, codetopo can report coupling and complexity the same way it now reports structure: the measurement and its method, never a grade. That work is designed and waiting its turn.

After the hosted launch settles — A working graph you can shape

The design's surgical operations — expand, collapse, annotate, prune — let an agent grow and trim a working view of a codebase instead of re-asking from scratch every time.

Later — More languages

Rust, TypeScript/JavaScript, and Python are parsed today. Each language is a front end against one shared contract, so new languages slot in without changing the questions you can ask.

Later — Always-fresh maps for your repository

This demo already redraws codetopo's own map on every push. The design aims the same trick at your repository: current architecture maps in your docs and pull requests, rebuilt by CI, never stale.

Exploring — A fuzzy layer beside the exact one

The design leaves room for an optional embeddings overlay — fuzzy search next to the exact graph, never instead of it. It stays optional, and it stays later.