{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-logo-dark.svg\">\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-logo.svg\">\n    <img src=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-logo.svg\" alt=\"Topos\" width=\"400\">\n  </picture>\n</p>\n\n<h3 align=\"center\">the agent harness for structural code quality</h3>\n\n<p align=\"center\">\n Topos measures complexity, coupling, risky data flows, and agent cognitive load, then gives your agent a concrete target&mdash;from SLOP to PLATINUM.\n</p>\n\n<p align=\"center\">\n  <a href=\"#what-topos-checks\"><img src=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-lattice-badge.svg\" alt=\"Topos self-evaluation: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE results for the core crates\"></a>\n  <a href=\"https://github.com/mcp/Krv-Labs/topos\"><img src=\"https://img.shields.io/badge/VS_Code-Install_MCP-007ACC?logo=visualstudiocode&logoColor=white\" alt=\"Install Topos MCP in VS Code\"></a>\n  <a href=\"https://pypi.org/project/topos-mcp/\"><img src=\"https://img.shields.io/pypi/v/topos-mcp?color=3776AB&logo=python&logoColor=ffd43b\" alt=\"PyPI\"></a>\n  <a href=\"https://github.com/Krv-Labs/topos/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/Krv-Labs/topos\" alt=\"License\"></a>\n  <a href=\"https://glama.ai/mcp/servers/Krv-Labs/topos\"><img src=\"https://glama.ai/mcp/servers/Krv-Labs/topos/badges/score.svg\" alt=\"Topos MCP server\"></a>\n  <a href=\"https://clawhub.ai/krv-labs/skills/topos\"><img src=\"https://img.shields.io/badge/%F0%9F%A6%9E_ClawHub-topos-F97316\" alt=\"ClawHub\"></a>\n</p>\n<!-- mcp-name: io.github.Krv-Labs/topos -->\n\n<p align=\"center\">\n  <a href=\"#install-and-quick-start\">Install</a> ·\n  <a href=\"#what-topos-checks\">What it checks</a> ·\n  <a href=\"#under-the-hood\">Under the hood</a> ·\n  <a href=\"https://docs.krv.ai/topos/\">Docs</a> ·\n  <a href=\"https://github.com/Krv-Labs/topos/issues\">Issues</a>\n</p>\n\n---\n\n<!--\nDEMO STUB — replace this comment only after recording the real release flow.\n\nShow, in under 20 seconds:\n1. an agent evaluates a repository;\n2. Topos identifies the exact failing pillar and source hotspot;\n3. the agent makes one focused refactor;\n4. Topos verifies the medal improvement while the project tests stay green.\n\nPrefer a checked-in, captioned GIF or SVG terminal recording with a stable\nrepository-relative URL. Do not publish a synthetic or hand-written result.\n-->\n\n<!--\nSTUDY STUB — keep hidden until the study, raw results, pinned repository SHAs,\nand reproduction method are public.\n\nCandidate headline:\n\"We evaluated <N> public repositories at pinned commits. <result>.\"\n\nRequired link target: a durable methodology/results page containing the corpus\nselection rule, Topos version and configuration, machine details, raw JSON,\nknown limitations, and a reproduction command. Avoid labeling repositories as\n\"AI-generated\" unless that provenance is explicit and independently verifiable.\n-->\n\n## Why Topos\n\nCoding 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.](https://krv.ai/field-notes/evaluating-code-generation)**\n\nTopos 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.\n\n**Tests check behavior. Topos checks whether the implementation is built to keep changing.**\n\n> Grounded in category theory, written in Rust.\n\n## Install and Quick Start\n\nOne binary. Every supported agent harness. A clean way back out.\n\n### 1. Install the CLI\n\nUse the verified release installer:\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\n```\n\nOr install with Homebrew:\n\n```bash\nbrew install krv-labs/tap/topos\n```\n\nOn Homebrew 6+, that fully qualified one-liner auto-taps and trusts only this formula. If you `brew tap krv-labs/tap` first, run `brew trust --formula krv-labs/tap/topos` before `brew install topos`.\n\n> [!TIP]\n> **Prefer an editor-managed install?** In VS Code or Cursor, search `@mcp topos` in the Extensions view or choose [Install MCP server](https://github.com/mcp/Krv-Labs/topos). This is an alternative to `topos install`: your editor installs and manages the Topos MCP server for you.\n\n### 2. Connect your coding agents\n\n`topos install` detects every supported MCP harness and lets you configure any—or all—of them from one interactive checklist:\n\n```bash\ntopos install\n```\n\n```text\n┌  Which agent integrations do you want to configure?\n│\n│  ↑↓ move · space toggle · a all · enter confirm · esc cancel\n│\n│ ❯ ○ Claude Code          (detected)\n│   ○ Claude Desktop       (detected)\n│   ● Codex CLI            (✓ active)\n│   ● Gemini CLI           (✓ active)\n│   ○ GitHub Copilot CLI   (detected)\n│   ○ Cursor               (detected)\n│   ○ VS Code              (detected)\n│   ○ Google Antigravity   (detected)\n└\n```\n\nRestart the agents you configured, then ask:\n\n> *\"Use Topos to find this repository's worst structural problem, make one focused improvement, and verify the result.\"*\n\n\n> [!IMPORTANT]\n> 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.\n>\n> ```bash\n> topos status\n> topos uninstall\n> ```\n\n\nSee the [agent setup guide](https://docs.krv.ai/topos/agents.html) for permissions, manual configuration, and troubleshooting.\n\n### 3. Evaluate from the terminal\n\n```bash\ntopos evaluate . -r\n```\n\nTopos discovers Python, Rust, JavaScript, TypeScript, C++, and Go automatically. Pass `--language` only when you want to narrow the run.\n\nSee [Installation](https://docs.krv.ai/topos/installation.html) for platform support and alternative install paths.\n\n\n## What Topos checks\n\nEvery file gets four independent verdicts:\n\n- **SIMPLE** — avoids unnecessary complexity using AST entropy and control-flow complexity.\n- **COMPOSABLE** — limits a file's outward dependency burden; broader coupling and stability metrics remain available for diagnosis.\n- **SECURE** — avoids dangerous API reachability and taint paths in the code property graph.\n- **NAVIGABLE** — stays shallow enough for an agent to read and change in one pass, using depth-weighted nesting divergence over the AST scope tree.\n\nThose verdicts roll up into one memorable quality medal without hiding which pillar failed:\n\n| Medal | Criteria |\n| :--- | :--- |\n| 🏆 **PLATINUM** | Passes all 4 |\n| 🥇 **GOLD** | Passes 3 of 4 |\n| 🥈 **SILVER** | Passes 2 of 4 |\n| 🥉 **BRONZE** | Passes 1 of 4 |\n| ❌ **SLOP** | Passes 0, or fails to parse |\n\n\nSee the [full metrics reference](topos/mcp/docs/content/metrics.md). Refactor guidance also surfaces control-flow cycles, load-bearing dependency edges, and process bottlenecks.\n\n<details>\n<summary>How the medal system is derived</summary>\n\nThe four pillars are pairwise incomparable and form a sixteen-element evaluation lattice (a 4-cube); PLATINUM is their intersection. Labels below abbreviate the pillars as **S**imple, **C**omposable, **Sc** = Secure, **N**avigable.\n\n<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/figures/topos-lattice-dark.svg\">\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/figures/topos-lattice.svg\">\n    <img src=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/figures/topos-lattice.svg\" alt=\"The full evaluation lattice — SLOP at the bottom, four single-pillar BRONZE states, six two-pillar SILVER states, four three-pillar GOLD states, and IDEAL (PLATINUM) at the top.\" width=\"900\">\n  </picture>\n</p>\n\n[Measures](https://docs.krv.ai/topos/measures.html) · [Category-theory foundations](https://docs.krv.ai/topos/concepts.html)\n\n</details>\n\n\n\n\n## Under the hood\n\nTopos 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.\n\n| Component | Role |\n| :--- | :--- |\n| [tree-sitter](https://tree-sitter.github.io/tree-sitter/) | Parses six languages and powers the native AST, CFG, CPG, PDG, and UAST representations. |\n| [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | Supplies the repository dependency graph scored by COMPOSABLE (`topos depgraph generate`). Requires `npm install -g gitnexus@1.6.8`. |\n| [Sighthound](https://github.com/Corgea/Sighthound) | Embedded in the MCP server for supplementary security findings; native CPG probes remain the SECURE scoring source. |\n\nThe 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.\n\n\n## More ways to use Topos\n\n- **OpenClaw / ClawHub:** [`openclaw skills install @Krv-Labs/topos`](https://clawhub.ai/krv-labs/skills/topos)\n- **Hermes:** `hermes skills tap add Krv-Labs/topos` then `hermes skills install Krv-Labs/topos/topos`\n- **Agent Plugins:** point a [compatible client](https://agent-plugins.org/compatible-clients) at [`agent-plugin/`](agent-plugin/) ([spec](https://agent-plugins.org/))\n- **MCP Registry name:** `io.github.Krv-Labs/topos`\n- **CLI reference:** [docs.krv.ai/topos/cli](https://docs.krv.ai/topos/cli.html)\n\n\n## Distribution\n\nTopos ships four ways:\n\n- **GitHub Releases** — the `topos` CLI binary (macOS/Linux), via `install.sh` or a direct release download.\n- **PyPI** — `topos-mcp`, a thin `bin`-wheel bundling the MCP server binary (`pip install topos-mcp` / `uvx topos-mcp`), zero Python runtime.\n- **VS Code Marketplace** — the Topos extension, bundling platform binaries.\n- **Docker** — a container image for Glama and other MCP-registry hosting.\n\nCrate layout and adapter details: **[docs.krv.ai/topos/architecture](https://docs.krv.ai/topos/architecture.html)**.\n\n## Contributing\n\nTopos is used internally at [Krv Labs](https://krv.ai) to manage AI-agent code output. We welcome bugs, ideas, and contributions.\n\n- **Bug?** Open an [issue](https://github.com/Krv-Labs/topos/issues)\n- **Idea?** Start a [discussion](https://github.com/Krv-Labs/topos/discussions) or open a PR\n- **Collaborate?** [team@krv.ai](mailto:team@krv.ai)\n\n---\n\n[Full documentation](https://docs.krv.ai/topos/) · [Measures and metrics](https://docs.krv.ai/topos/measures.html) · [Engineering notes](docs/)\n\n<p align=\"left\">\n  <a href=\"https://krv.ai\">\n    <img src=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/made-by-krv.svg\" alt=\"Made by Krv Labs\" height=\"24\">\n  </a>\n  &nbsp;\n  <a href=\"#what-topos-checks\">\n    <img src=\"https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-verdict.svg\" alt=\"Topos lattice verdict\" height=\"24\">\n  </a>\n</p>\n",
  "bytes": 11512,
  "sha": "2f11eb7b82abe180e7aebcda5fe63a8dcfb8bb0617e16dcc422843902d7f05a6",
  "repo_slug": "krv-labs/topos",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_krv_labs_topos_openwiki_index_md_30fb7b1d/readme"
}