Topos

Structural code quality metrics for agent-written programs.
Docs · Quick Start · MCP Server · Issues

Topos is an operating layer for AI agents that provides structural (geometric & topological) metrics computed over program graphs, surfacing deep architectural debt that conventional linters can't compute. It delivers complexity, coupling, and security metrics for your agents to wield as tools, establishing a precise, medal-scored (SLOP → GOLD) feedback loop to autonomously write clean, highly composable code.

Quick Start

curl -fsSL https://docs.krv.ai/topos/install.sh | sh
topos evaluate src/ -r

evaluate -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.

What you get

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)

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 .gitnexus

Other 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.

MCP server (for agents)

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 mcp

Setup for Cursor, VS Code, Gemini CLI, Codex, and Windsurf, plus troubleshooting and the full MCP tool list: docs.krv.ai/topos/agents.

How it works

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.

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.

Contributing

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? [email protected]

Full Documentation · Measures & Metrics · Category Theory Concepts · Engineering notes

Built with ❤️ by Krv Labs