Structural code quality metrics for agent-written programs.
Docs ·
Quick Start ·
MCP Server ·
Issues
Passing unit tests proves your code works. Topos proves it's built to last. It measures program structure — complexity, coupling, and data-flow risk — not just syntax, so agents get a concrete target to optimize toward on every pass instead of a vague "clean it up."
curl -fsSL https://docs.krv.ai/topos/install.sh | sh
topos evaluate src/ -revaluate -r scores every file in src/ and prints a ranked digest: which pillars pass, the worst-scoring files, and the cheapest fixes to flip a failing pillar. Add -h to any command for help, or --json for CI.
Other install paths (PyPI, source checkout) and the full command tour live at docs.krv.ai/topos/installation.
Topos checks three independent pillars and awards a Code Quality Medal for how many pass:
- SIMPLE — avoids unnecessary complexity (AST entropy & CFG cyclomatic complexity)
- COMPOSABLE — cleanly decoupled from other modules (MDG Martin instability via GitNexus)
- SECURE — free of dangerous API reachability and taint paths (CPG analysis)
| Medal | Criteria |
|---|---|
| 🥇 GOLD | Passes all 3 (SIMPLE + COMPOSABLE + SECURE) |
| 🥈 SILVER | Passes 2 of 3 |
| 🥉 BRONZE | Passes 1 of 3 |
| ❌ SLOP | Passes 0 (or fails to parse) |
COMPOSABLE needs a cross-file dependency graph, which the CLI does not build automatically:
npm install -g gitnexus
topos depgraph generate
topos evaluate src/ -r --gitnexus-dir .gitnexusOther commands: topos inspect for per-file metrics, topos compare for AST edit distance between two versions, topos coverage for structural test coverage, and --preferences simple,composable,secure to tell agents which pillar to protect first when 🥇 GOLD isn't reachable. Full reference: docs.krv.ai/topos/cli.
Give any MCP-compatible agent — Claude Code, Cursor, Gemini CLI, Windsurf — a live feed of Topos verdicts so it can evaluate and iterate on its own output.
claude mcp add --transport stdio topos -- topos mcpSetup for Cursor, VS Code, Gemini CLI, Codex, and Windsurf, plus troubleshooting and the full MCP tool list: docs.krv.ai/topos/agents.
Topos measures code along the three pillars above and maps the result to an 8-element evaluation lattice — the three pillars are pairwise incomparable, and 🥇 GOLD is their intersection.
Evaluation lattice diagram
graph BT
SLOP["❌ SLOP<br/>No Medal"]
SIMPLE["🥉 BRONZE<br/>Simple"]
COMPOSABLE["🥉 BRONZE<br/>Composable"]
SECURE["🥉 BRONZE<br/>Secure"]
SC["🥈 SILVER<br/>S ∧ C"]
SSc["🥈 SILVER<br/>S ∧ Sc"]
CSc["🥈 SILVER<br/>C ∧ Sc"]
IDEAL["🥇 GOLD<br/>Quality Code"]
SLOP --> SIMPLE
SLOP --> COMPOSABLE
SLOP --> SECURE
SIMPLE --> SC
SIMPLE --> SSc
COMPOSABLE --> SC
COMPOSABLE --> CSc
SECURE --> SSc
SECURE --> CSc
SC --> IDEAL
SSc --> IDEAL
CSc --> IDEAL
style SLOP fill:#f8d7da,stroke:#842029,color:#000
style SIMPLE fill:#cd7f32,stroke:#5c3a1e,color:#fff
style COMPOSABLE fill:#cd7f32,stroke:#5c3a1e,color:#fff
style SECURE fill:#cd7f32,stroke:#5c3a1e,color:#fff
style SC fill:#c0c0c0,stroke:#4a4a4a,color:#000
style SSc fill:#c0c0c0,stroke:#4a4a4a,color:#000
style CSc fill:#c0c0c0,stroke:#4a4a4a,color:#000
style IDEAL fill:#ffd700,stroke:#856404,color:#000
Set your Preferences (e.g. simple,composable,secure) to tell your coding agent which pillars to prioritize when aiming for GOLD under token and time budgets, and how to relax that goal when GOLD isn't reachable. Details: docs.krv.ai/topos/preferences · docs.krv.ai/topos/measures · docs.krv.ai/topos/concepts.
Topos is used internally at Krv Labs to manage AI agent code output. We welcome bugs, ideas, and contributions.
- Bug? Open an Issue
- Idea? Start a Discussion or open a PR
- Collaborate? team@krv.ai
Full Documentation · Measures & Metrics · Category Theory Concepts · Engineering notes
Built with ❤️ by Krv Labs