Topos

構造的なコード品質のためのエージェントハーネス

Topos は複雑さ、結合度、リスクの高いデータフロー、エージェントの認知負荷を測定し、SLOP から PLATINUM まで、エージェントに具体的な目標を与えます。

インストール · チェック内容 · 内部の仕組み · ドキュメント · Issues

---

Topos を使う理由

コーディングエージェントは動作するコードを素早く生成します。より難しいのは、その結果が依然として理解しやすく、安全に変更でき、リポジトリの他の部分とうまく調和しているかどうかです。品質が新たな通貨です。

Topos はそのシグナルを、LLM によるレビューやスタイルの意見からではなく、プログラム構造から計算し、具体的な問題箇所と次のアクションを返します。エージェントループの中に収まるほど高速です。測定し、編集し、検証し、繰り返します。

テストは振る舞いを検証します。Topos はその実装が変更し続けられるように作られているかを検証します。

圏論に基づき、Rust で書かれています。

インストールとクイックスタート

単一のバイナリ。サポートされるすべてのエージェントハーネス。きれいに元に戻せる方法。

1. CLI をインストールする

検証済みのリリースインストーラーを使用します:

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

または Homebrew でインストールします:

brew install krv-labs/tap/topos

Homebrew 6 以降では、この完全修飾のワンライナーがこの formula のみを自動で tap して信頼します。先に brew tap krv-labs/tap を実行する場合は、brew install topos の前に brew trust --formula krv-labs/tap/topos を実行してください。

ヒント

エディタで管理するインストールを好みますか? VS Code または Cursor で、Extensions ビューで @mcp topos を検索するか、MCP サーバーをインストールを選択します。これは topos install の代替です。エディタが Topos MCP サーバーをインストールして管理します。

2. コーディングエージェントを接続する

topos install はサポートされているすべての MCP ハーネスを検出し、1 つの対話型チェックリストから任意のもの、またはすべてを設定できます。

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)
│   ○ pi                   (detected)
│   ○ OpenCode             (detected)
└

設定したエージェントを再起動してから、次のように依頼してください。

「Topos を使って、このリポジトリの最も深刻な構造上の問題を見つけ、的を絞った改善を 1 つ行い、その結果を検証してください。」

重要

多くのツールは、MCP サーバーをエージェントの JSON ファイルにまき散らし、マシンのあちこちにシンボリックリンクを散乱させたうえで、混乱を解きほぐすために Claude のセッションを半分も費やさせたり、自分で頭を抱えさせたりします。Topos はそのようなことはしません。ハーネスのインストール状態について、痕跡を残さない方針を採用しています。topos status ですべての登録を確認でき、topos uninstall は同じセレクターを開き、変更内容を正確にプレビューして、ハーネスの設定に追加したすべての項目を削除します。 共有キャッシュの管理情報とリポジトリ単位のキャッシュリースはインストール状態ではないため、アンインストール時にもそのまま残り、保持される共有管理情報があれば報告します。生成された PR キャッシュは、明示的に topos cache clean または topos cache prune を実行した場合にのみ削除されます。Topos で簡単に実行できることなら、同じように簡単に元に戻せるべきです。

topos status
topos uninstall

権限、手動設定、トラブルシューティングについては、エージェント設定ガイドをご覧ください。

3. ターミナルから評価する

topos evaluate . -r

Topos は Python、Rust、JavaScript、TypeScript、C++、Go を自動的に検出します。実行対象を絞り込みたい場合にのみ --language を指定してください。

プルリクエストをレビューする場合は、topos pr-recap 5 を実行すると、その PR で変更されたファイルについて、構造の変更前後を示すカードと負債台帳が得られます。LLM は不要で、完全に再現可能です。1,609 件のオープンソースのプルリクエストをもとに調整されたプリセットを使用します（PR Recap のキャリブレーション・ラボノート）。

プラットフォームのサポート状況と別のインストール方法については、インストールをご覧ください。

Topos がチェックする内容

各ファイルについて、独立した4つの判定を行います。

• SIMPLE — AST のエントロピーと制御フローの複雑度を用いて、不必要な複雑さを避けます。
• COMPOSABLE — ファイルが外部に及ぼす依存の負担を抑えます。より広範な結合度や安定性の指標も、診断用に利用できます。
• SECURE — コードプロパティグラフにおける危険な API への到達可能性や汚染経路を避けます。
• NAVIGABLE — AST のスコープツリーに対する深さ加重のネスト乖離を用いて、エージェントが一度の作業で読み取り、変更できるほど浅い状態を保ちます。

これらの判定は、どの柱で不合格だったかを隠すことなく、覚えやすい品質メダルにまとめられます。

メダル	基準
🏆 PLATINUM	4つすべてに合格
🥇 GOLD	4つのうち3つに合格
🥈 SILVER	4つのうち2つに合格
🥉 BRONZE	4つのうち1つに合格
❌ SLOP	0個合格、または解析に失敗

指標の完全なリファレンスをご覧ください。リファクタリングのガイダンスでは、制御フローのサイクル、重要な依存関係のエッジ、プロセスのボトルネックも明らかになります。

メダルシステムの導出方法

4つの柱はペアごとに比較不能で、16要素の評価束（4次元立方体）を形成します。PLATINUM はそれらすべての共通部分です。以下のラベルでは、各柱を Simple、Composable、Sc = Secure、Navigable と略記しています。

指標 · 圏論の基礎

内部の仕組み

Topos は、自己完結型の Rust CLI および MCP サーバーです。解析はローカルで実行され、ソースコードが外部モデルやホスト型の解析サービスに送信されることはありません。

コンポーネント	役割
tree-sitter	6つの言語を解析し、ネイティブの AST、CFG、CPG、PDG、UAST 表現を提供します。
GitNexus	COMPOSABLE のスコア算出に使われるリポジトリ依存関係グラフを提供します（topos depgraph generate）。npm install -g [email protected] が必要です。
Sighthound	補足的なセキュリティ上の検出結果を得るため、MCP サーバーに組み込まれています。ネイティブの CPG プローブが引き続き SECURE のスコア算出元です。

その結果、複数の構造的な観点を通じて、エージェント向けの単一の契約を実現します。最適化すべきスコアは1つ、各不合格の根拠は明示され、検証ループによって実質的な改善と見た目だけの変更を見分けられます。

Topos のその他の使い方

• OpenClaw / ClawHub: openclaw skills install @Krv-Labs/topos
• Hermes: hermes skills tap add Krv-Labs/topos を実行してから、hermes skills install Krv-Labs/topos/topos を実行します。
• エージェントプラグイン: 互換性のあるクライアントを agent-plugin/ に指定します（仕様）
• MCP Registry 名: io.github.Krv-Labs/topos
• CLI リファレンス: docs.krv.ai/topos/cli

配布

Topos は 4 つの方法で提供されています。

• GitHub Releases — install.sh またはリリースからの直接ダウンロードで入手できる、topos CLI バイナリ（macOS/Linux）。
• PyPI — MCP サーバーのバイナリを同梱した薄型の bin ホイールである topos-mcp（pip install topos-mcp / uvx topos-mcp）。Python ランタイムは不要です。
• VS Code Marketplace — プラットフォーム用バイナリを同梱した Topos 拡張機能。
• Docker — Glama などの MCP レジストリでのホスティング向けコンテナーイメージ。

クレートの構成とアダプターの詳細：docs.krv.ai/topos/architecture。

コントリビューション

Topos は Krv Labs で AI エージェントのコード出力を管理するために社内利用されています。バグ報告、アイデア、コントリビューションを歓迎します。

• バグですか？ issue を作成してください
• アイデアがありますか？ ディスカッションを始めるか、PR を作成してください
• 協力したいですか？ [email protected]

---

ドキュメント全文 · 測定方法とメトリクス · エンジニアリングノート