topos

the agent harness for structural code quality

Topos measures complexity, coupling, and risky data flows, then gives your agent a concrete target—from SLOP to GOLD.

Install · What it checks · Under the hood · Docs · Issues

Why Topos

Coding agents produce working code quickly. The harder question is whether the result is still easy to understand, safe to change, and well-fitted to the rest of the repository. Quality is the new currency.

Topos computes that signal from program structure—not from an LLM review or a style opinion—and returns concrete failure locations and next actions. It is fast enough to sit inside the agent loop: measure, edit, verify, repeat.

Tests check behavior. Topos checks whether the implementation is built to keep changing.

Grounded in category theory, powered by a native-Rust engine.

Install and Quick Start

One binary. Every supported agent harness. A clean way back out.

1. Install the CLI

Use the verified release installer:

curl -fsSL https://docs.krv.ai/topos/install.sh | bash

Or install with Homebrew:

brew install krv-labs/tap/topos

[!TIP] Prefer an editor-managed install? In VS Code or Cursor, search @mcp topos in the Extensions view or choose Install MCP server. This is an alternative to topos install: your editor installs and manages the Topos MCP server for you.

2. Connect your coding agents

topos install detects every supported MCP harness and lets you configure any—or all—of them from one interactive checklist:

topos install

┌  Which agent integrations do you want to configure?
│
│  ↑↓ move · space toggle · a all · enter confirm · esc cancel
│
│ ❯ ○ Claude Code          (detected)
│   ○ Claude Desktop       (detected)
│   ● Codex CLI            (✓ active)
│   ● Gemini CLI           (✓ active)
│   ○ GitHub Copilot CLI   (detected)
│   ○ Cursor               (detected)
│   ○ VS Code              (detected)
│   ○ Google Antigravity   (detected)
└

Restart the agents you configured, then ask:

"Use Topos to find this repository's worst structural problem, make one focused improvement, and verify the result."

[!IMPORTANT] Too many tools spray MCP servers across agent JSON files, scatter symlinks around your machine, then leave you to burn half a Claude session untangling the mess—or pull your own hair out doing it. Topos does not play that game. We follow a leave-no-trace policy: topos status shows every registration, while topos uninstall opens the same selector, previews exactly what will change, and removes everything Topos installed. If Topos makes it easy to do, it should be just as easy to undo.

topos status
topos uninstall

See the agent setup guide for permissions, manual configuration, and troubleshooting.

3. Evaluate from the terminal

topos evaluate . -r

Topos discovers Python, Rust, JavaScript, TypeScript, C++, and Go automatically. Pass --language only when you want to narrow the run.

See Installation for platform support and alternative install paths.

Under the hood

Topos is a self-contained Rust CLI and MCP server. Analysis runs locally; your source code is not sent to an external model or hosted analysis service.

The result is one agent-facing contract over several structural lenses: one score to optimize, explicit evidence for each failure, and a verification loop that can tell a real improvement from cosmetic churn.

More ways to use Topos

• OpenClaw / ClawHub: openclaw skills install @Krv-Labs/topos
• Hermes: hermes skills tap add Krv-Labs/topos then hermes skills install Krv-Labs/topos/topos
• MCP Registry name: io.github.Krv-Labs/topos
• CLI reference: docs.krv.ai/topos/cli

What Topos checks

Every file gets three independent verdicts:

• SIMPLE — avoids unnecessary complexity using AST entropy and control-flow complexity.
• COMPOSABLE — stays decoupled from the repository using module-dependency structure and Martin instability.
• SECURE — avoids dangerous API reachability and taint paths in the code property graph.

Those verdicts roll up into one memorable quality medal without hiding which pillar failed:

Topos also returns ranked refactor guidance: failing metric locations, control-flow cycles, load-bearing dependency edges, process bottlenecks, and optional Graphify knowledge-graph findings. Advisory findings never silently change the scored medal.

---
config:
  layout: dagre
  theme: neutral
---
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

Distribution

Topos ships four ways:

• GitHub Releases — the topos CLI binary (macOS/Linux), via install.sh or a direct release download.
• PyPI — topos-mcp, a thin bin-wheel bundling the MCP server binary (pip install topos-mcp / uvx topos-mcp), zero Python runtime.
• VS Code Marketplace — the Topos extension, bundling platform binaries.
• Docker — a container image for Glama and other MCP-registry hosting.

Crate layout and adapter details: docs.krv.ai/topos/architecture.

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? team@krv.ai

Full documentation · Measures and metrics · Engineering notes