Topos¶
Code quality evaluation
Structural code quality your agents can measure — and optimize toward.
Stop paying agents to rediscover and repair their own structural mess. Topos gives coding agents concrete quality targets before complexity, coupling, and risky data paths compound into expensive context archaeology. Pick a preference ranking and Topos measures program structure — not just syntax — so agents can optimize toward the code shape you want on every pass.
Correctness is expected. Quality is the new currency.
Passing unit tests only proves that your code is a solution to a finite set of requirements. Agents have proved to be exceptional at this and will continue to improve. We believe the new currency is the quality of these solutions. Topos provides the structural evaluations that empower coding agents to find higher quality solutions.
Get started with the CLI, MCP server, or build from source.
MCP setup, the official registry listing, and how agents iterate toward quality targets.
Detailed overview of the Topos command-line interface and available tools.
Tell agents how to trade off SIMPLE, COMPOSABLE, and SECURE when GOLD stalls.
A breakdown of the structural and coupling metrics used to evaluate code quality.
Hint
Built on category theory, written in Rust. Topos models code quality as a structural property of programs using topos theory — the formalism is precise by design, not decoration. You don’t need the math to use Topos day to day; see Concepts for the foundations.
Beyond Correctness¶
Assume you passed the tests. How good is your solution?
Current code evaluations focus heavily on correctness — does the code pass the unit tests we created? But passing tests doesn’t guarantee that you’ve written good, secure, or maintainable code.
Topos fills this gap by measuring structural quality, ensuring that your code isn’t just correct, but built to last. It provides well-principled evaluations of a programs structure that agents can use to find better solutions.
The Medal Podium¶
Topos measures each file along four independent quality pillars. Each pillar is pass or fail on its own:
SIMPLE — The code avoids unnecessary complexity.
COMPOSABLE — The file keeps its outward dependency burden bounded.
SECURE — The code is free of operations that are known to expose security vulnerabilities.
NAVIGABLE — The code is shallow enough for an AI agent to read and change in one pass, rather than deeply nested.
Run topos evaluate or topos inspect on a file; Topos checks all four pillars and awards a Code Quality Medal from how many you pass. Which pillars you pass matters for diagnosis; the medal tier depends only on the count:
Pillars passed |
Medal |
Example (any combination with this count) |
|---|---|---|
4 of 4 |
|
SIMPLE + COMPOSABLE + SECURE + NAVIGABLE |
3 of 4 |
|
e.g. SIMPLE + COMPOSABLE + SECURE |
2 of 4 |
|
e.g. SIMPLE + SECURE, or COMPOSABLE + NAVIGABLE |
1 of 4 |
|
e.g. SIMPLE only, or NAVIGABLE only |
0 of 4 |
|
Fails every pillar (or the file could not be parsed) |
Manager Priorities & Agent Iteration¶
In a perfect world, every file would earn a 🏆 PLATINUM medal. In reality, managers and developers have a finite budget of time and tokens.
Topos allows you to set Preferences — an ordering of these medals based on your immediate priorities. Coding agents use this ranking to aim for 🏆 PLATINUM. If achieving 🏆 PLATINUM isn’t feasible within the budget, the preference ranking tells the agent exactly how to relax its goals, ensuring it still delivers the highest possible quality medal aligned with your priorities.
Quick look¶
Pick a preference ranking, then let your agent evaluate and iterate on its own output.
topos evaluate src/ -r --priority simple,composable,secure,navigable
topos config set --priority simple,composable,secure,navigable
topos inspect module.py
topos coverage src/logic.py --tests tests/test_logic.py
topos compare before.py after.py
Each file gets a verdict per quality generator. You always see which generator is the problem, not a single blended number.
How it works¶
Topos measures code along the four independent quality generators and maps them to a 16-element evaluation lattice:
SIMPLE — Built from the abstract syntax tree (AST) and control-flow graph (CFG). We calculate cyclomatic complexity of the CFG and entropy of the AST to assess complexity.
COMPOSABLE — Built from the module dependency graph (MDG) using GitNexus. File-level achievement gates the number of distinct external callees (fan-out); Martin instability, fan-in, and other graph metrics remain available for richer architectural diagnosis.
SECURE — Built from the code property graph (CPG). We calculate dangerous-API reachability and taint paths from the CPG to assess security.
NAVIGABLE — Built from the AST scope tree. We calculate depth-weighted nesting divergence (
Σ depth · ln(1 + fanout)) per function to assess how much cognitive load the code imposes on an AI agent reading it. Orthogonal to SIMPLE: that one counts branches, this one measures nesting.
SLOP to IDEAL (🏆 PLATINUM). Pillars abbreviate as Simple, Composable, Sc = Secure, Navigable.Hint
Four Independent Pillars: SIMPLE, COMPOSABLE, SECURE, and
NAVIGABLE are pairwise incomparable. A file can achieve any subset of
{S, C, Sc, N} independently, giving \(2^4 = 16\) verdicts.
🏆 PLATINUM is the intersection of all four. The Preferences (ranking)
determine the order in which an agent traverses through the lattice,
attempting to earn the highest possible medal.