Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""Render the agent support matrix at ``docs/agent/INTEGRATIONS.md`` from the code.
Two numbers in this repo have a long history of being wrong in public: which
agents we support at what depth, and how many MCP tools we expose. Both were
hand-written in a dozen places, so both drifted the moment a target or a tool
landed. Six artifacts said "ten MCP tools" against a live surface of eleven, and
the README contradicted itself two hundred lines apart.
So neither is written by hand here. The tiers come from
:func:`repowise.cli.agent_targets.types.derive_tier`, the capability columns come
from each descriptor's declared install methods, and the tool counts come from
the live MCP registry. A new agent or a new tool changes this document by being
registered, and :mod:`tests.unit.cli.test_agent_matrix` fails when the file on
disk disagrees.
Render discipline, the same as ``scripts/gen_plugin_content.py`` and for the same
reason: fixed section order, sorted iteration where the order is not already
declared, LF newlines, and never a timestamp, a version or a generator banner in
the output. A file that changes when nothing changed cannot be a golden.
Run ``python scripts/gen_agent_matrix.py`` to write, ``--check`` to report drift
without writing.
"""
from __future__ import annotations
import argparse
import sys
import textwrap
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
OUTPUT = ROOT / "docs" / "agent" / "INTEGRATIONS.md"
#: Prose width. Only paragraphs whose text is computed are wrapped here; the
#: hand-authored lines are wrapped as written, because reflowing them through
#: ``textwrap`` would rewrite the file every time a sentence changed length.
_WRAP = 84
# The script runs standalone as well as under pytest, so make the workspace
# packages importable either way. Harmless when they are already installed.
for _pkg in ("cli", "core", "server"):
_src = ROOT / "packages" / _pkg / "src"
if _src.is_dir() and str(_src) not in sys.path:
sys.path.insert(0, str(_src))
# ---------------------------------------------------------------------------
# Hand-authored copy
# ---------------------------------------------------------------------------
#: Hosts served by the Paste-config tier: we write nothing and maintain nothing,
#: ``repowise agents print-config`` emits a snippet they can paste. There is no
#: descriptor to derive this from, by definition. The golden test does check
#: that nothing here collides with a registered target, so promoting one of
#: these to a real integration and forgetting to delete the line is caught.
PASTE_CONFIG_HOSTS: tuple[str, ...] = (
"Cline",
"Windsurf",
"Zed",
"Continue",
"Gemini CLI",
"JetBrains AI Assistant",
"Amp",
)
TIER_BLURBS: dict[str, tuple[str, str]] = {
"full": (
"Full",
"MCP tools, a managed instructions file, skills, slash commands, "
"hook-level interception of tool calls, and transcript mining after "
"the fact. Every surface repowise has.",
),
"good": (
"Good",
"MCP tools plus a managed instructions file or skills, so the agent is "
"told when to reach for them. **No transcript mining, and hooks only "
"where the matrix says so.** The agent can ask repowise questions; "
"repowise sees little or nothing of what it does in between.",
),
"basic": (
"Basic",
"repowise writes the MCP server config and nothing else. The tools are "
"there; no instructions file or skill tells the agent when to use them.",
),
"paste-config": (
"Paste-config",
"`repowise agents print-config <id>` emits the MCP server snippet and "
"we write nothing. Zero code and zero maintenance per host.",
),
}
# ---------------------------------------------------------------------------
# Derived data
# ---------------------------------------------------------------------------
def agent_rows() -> list[dict]:
"""One row per registered target, in registry order.
Only the static fields. ``registry.describe_agents`` is the projection the
CLI reads, and it deliberately reports ``present`` / ``method`` /
``registrations``, which describe the machine the command ran on. A checked
in document rendered from those would differ per developer and fail its own
``--check`` on the next machine.
"""
from repowise.cli.agent_targets import registry
from repowise.cli.agent_targets.types import Capability, derive_tier
from repowise.core.agents.identity import identity_for_target_id
rows: list[dict] = []
for target in registry.all_targets():
# Split by who manages the method rather than unioning every
# capability, because "Claude Code has slash commands" and "repowise
# installs Claude Code's slash commands" are different claims and only
# the first is true. The host plugin ships those.
by_manager: dict[str, set[Capability]] = {"repowise": set(), "host": set()}
for method in target.methods:
key = "host" if method.managed_by == "host" else "repowise"
by_manager[key] |= set(method.provides)
identity = identity_for_target_id(target.id)
rows.append(
{
"id": target.id,
"display_name": target.display_name,
"docs_url": target.docs_url,
"tier": derive_tier(target).value,
"direct": by_manager["repowise"],
"host": by_manager["host"],
"hook_adapter": target.hook_adapter,
"session_adapter": target.session_adapter,
"capture_adapter": target.capture_adapter,
"indexing_provider": identity.indexing_provider if identity else None,
}
)
return rows
def tool_counts() -> dict[str, int]:
"""The live MCP tool surface, straight from the registry.
``ensure_full_surface`` is what makes the count honest: tool modules import
lazily, so a registry read without it reports however many tools happened to
be imported already.
"""
from repowise.core.registry import mcp_tool_registry
from repowise.core.registry.tool_selection import LEAN, resolve_enabled_tools
from repowise.server.mcp_server import ensure_full_surface
ensure_full_surface()
entries = mcp_tool_registry.entries()
default_names = resolve_enabled_tools(entries, is_workspace=False)
# Every count goes through the resolver the server itself uses, including
# the lean ones. Counting ``LEAN_TOOLS`` directly looks equivalent and is
# not: the resolver drops a lean name the registry no longer carries, so a
# renamed tool would leave the published "six tools" claiming a surface the
# server had quietly trimmed to five.
single_repo = len(default_names)
workspace = len(resolve_enabled_tools(entries, is_workspace=True))
return {
"total": len(entries),
"single_repo": single_repo,
# The README and the hero image count the *flagship* tools, which is a
# narrower and deliberate claim: the task-shaped ones the pitch is
# about. It is the default surface minus the discovery utilities, and
# it is derived here rather than typed, so a twelfth default tool moves
# the README too. Docs keep the precise surface numbers.
"flagship": len([entry for entry in entries if entry.tier == "canonical"]),
"workspace": workspace,
# The delta is published in its own right ("adds two more"), so it is
# derived rather than written as a literal next to a derived total.
"workspace_extra": workspace - single_repo,
"opt_in": len([entry for entry in entries if not entry.default]),
"lean": len(resolve_enabled_tools(entries, is_workspace=False, override=LEAN)),
"lean_workspace": len(resolve_enabled_tools(entries, is_workspace=True, override=LEAN)),
}
#: Complete through twenty, not just the values in use today. A partial map is
#: a landmine: the counts here feed a module-scope constant and a parametrize
#: argument in the golden test, so a missing entry is a *collection* error that
#: takes down the very drift guards that exist to say which files to edit. The
#: first tool to push a count to twelve, or the renamed lean tool this file
#: warns about elsewhere, would have hit exactly that.
_WORDS = {
0: "zero",
1: "one",
2: "two",
3: "three",
4: "four",
5: "five",
6: "six",
7: "seven",
8: "eight",
9: "nine",
10: "ten",
11: "eleven",
12: "twelve",
13: "thirteen",
14: "fourteen",
15: "fifteen",
16: "sixteen",
17: "seventeen",
18: "eighteen",
19: "nineteen",
20: "twenty",
}
def spell(count: int) -> str:
"""*count* as an English word, for prose that spells small numbers out.
Raises past twenty rather than falling back to the digits: the artifacts
this guards say "eleven MCP tools", and a silent switch to "21 MCP tools"
mid-sentence is the kind of drift that goes unnoticed for twenty-four
releases. Past twenty the prose wants rewriting by a person anyway.
"""
if count not in _WORDS:
raise ValueError(
f"no spelled form for {count}. Prose that spells a number this large reads "
"badly; rewrite the sentence, or extend _WORDS in scripts/gen_agent_matrix.py."
)
return _WORDS[count]
# ---------------------------------------------------------------------------
# Render
# ---------------------------------------------------------------------------
#: Column caption, and the capability it reads. A row key instead means the
#: column is derived from that field (an adapter or provider name), not from a
#: declared capability.
_COLUMNS: tuple[tuple[str, str], ...] = (
("MCP", "mcp"),
("Hooks", "hooks"),
("Skills", "skills"),
("Commands", "commands"),
("Instructions", "instructions"),
("Transcripts", "session_adapter"),
("Indexing", "indexing_provider"),
("Attribution", "capture_adapter"),
)
def _cell(row: dict, capability: str) -> str:
if capability in row:
return "Yes" if row[capability] else "No"
from repowise.cli.agent_targets.types import Capability
wanted = Capability(capability)
if wanted in row["direct"]:
return "Yes"
if wanted in row["host"]:
return "Plugin"
return "No"
def _matrix_table(rows: list[dict]) -> str:
header = "| Agent | Tier | " + " | ".join(name for name, _ in _COLUMNS) + " |"
rule = "|---|---|" + "---|" * len(_COLUMNS)
lines = [header, rule]
for row in rows:
name = row["display_name"]
if row["docs_url"]:
name = f"[{name}]({row['docs_url']})"
cells = [_cell(row, capability) for _, capability in _COLUMNS]
tier = TIER_BLURBS[row["tier"]][0]
lines.append(f"| {name} | {tier} | " + " | ".join(cells) + " |")
return "\n".join(lines)
def _join_names(names: list[str]) -> str:
"""``A``, ``A and B``, ``A, B and C`` — a real list, at any length.
The first version of this handled one name and read as a grammar error at
two ("VS Code and Cursor sits at Good"), which is the shape of drift a
generated document is supposed to make impossible. Verb agreement is the
caller's, because only it knows whether the sentence needs one.
"""
if len(names) < 3:
return " and ".join(names)
return ", ".join(names[:-1]) + f" and {names[-1]}"
def _tier_list() -> str:
return "\n".join(
f"- **{title}.** {body}" for title, body in (TIER_BLURBS[key] for key in TIER_BLURBS)
)
def render() -> str:
rows = agent_rows()
counts = tool_counts()
ids = ", ".join(f"`{row['id']}`" for row in rows)
good = [row["display_name"] for row in rows if row["tier"] == "good"]
hooked = [row["display_name"] for row in rows if row["tier"] == "good" and row["hook_adapter"]]
basic = [row["display_name"] for row in rows if row["tier"] == "basic"]
parts = [
"# Agent integrations",
"",
"<!-- Generated by scripts/gen_agent_matrix.py. Do not edit by hand: run",
" `python scripts/gen_agent_matrix.py` after changing a descriptor. -->",
"",
"Anything that speaks MCP can read a repowise index. This page is about how",
"*deeply* each agent is wired, which is a different question, and the one",
"every breadth claim in this space gets wrong.",
"",
"## Tiers",
"",
"The tier is **derived from the code, never declared**. A descriptor reaches",
"Full only by naming both a hook adapter and a transcript adapter, and Good",
"only by wiring instructions or skills beside MCP, so no document can claim",
"a depth the integration does not have.",
"",
_tier_list(),
"",
"## The matrix",
"",
"`Yes` means repowise wires it. `Plugin` means the host's own plugin ships",
"it and repowise does not write it. `No` means the surface does not exist",
"for that agent. `Indexing` is `Yes` when the agent's own CLI can run as the",
"LLM that writes the index, selected by its provider id (`claude_cli`, for",
"example). It is separate from the tier: it says nothing about the session.",
"`init` offers a logged-in agent CLI but uses it only when you pick it or pass",
"`--provider`. An agent CLI has no embedder, so semantic search needs an",
"embedder key of its own: see",
"[Embeddings](../reference/CONFIG.md#embeddings-for-semantic-search).",
"",
"`Attribution` is `Yes` when repowise can record the agent's edits as they",
"happen, an opt-in set by `attribution.capture` and `attribution.agents`. Every",
"agent's own git-ai notes, Agent Trace files and commit trailers are read",
"either way.",
"",
_matrix_table(rows),
"",
f"Target ids for `--target=`: {ids}.",
"",
]
if good:
parts += [
"### What Good tier does not include",
"",
f"{_join_names(good)} {'sits' if len(good) == 1 else 'sit'} at Good, and the "
"honest version of that is worth stating",
"plainly. These agents get the MCP tools and the config repowise writes.",
"They do **not** get hook-level interception: repowise never sees a tool",
"call before it runs, never rewrites a noisy command, and never annotates",
"a result afterwards. Nor is there transcript mining, so nothing learns",
"from the session after it ends.",
"",
]
if hooked:
parts += [
f"The one exception is hooks: {_join_names(hooked)} "
f"{'runs' if len(hooked) == 1 else 'run'} the distill command-rewrite hook,",
"so noisy commands are rewritten there. Transcript mining is still absent.",
"",
]
parts += [
"That is a real integration and it is most of the value. It is not the",
"same product Full-tier agents get, and breadth that overclaims depth is",
"worse than narrower breadth.",
"",
]
if basic:
parts += [
"### Basic tier",
"",
f"{_join_names(basic)} {'sits' if len(basic) == 1 else 'sit'} at Basic. repowise writes",
"no instructions file or skills there, so the MCP tools are reachable but",
"nothing tells the agent when to use them.",
"",
]
parts += [
"## Paste-config",
"",
"Every other MCP host is served without writing a descriptor for it. Print",
"the server entry and paste it into whatever config that host reads:",
"",
"```bash",
"repowise agents print-config claude-code # prints, writes nothing",
"```",
"",
"Ask for the target id whose host is closest to yours instead of editing a",
"snippet by hand. The shapes genuinely differ, and not only in their wrapper:",
"hosts disagree about the top-level key, about whether each entry carries a",
"`type` field, about whether the invocation is one array or a command plus a",
"separate argument list, and about the file format itself, so `codex` prints",
"TOML and `hermes` prints YAML where the others print JSON. `claude-code` is",
"the plain `mcpServers` JSON most hosts read and is the right default when",
"yours is not listed below.",
"Hosts people ask about most, none of which repowise writes config for today:",
"",
", ".join(PASTE_CONFIG_HOSTS) + ".",
"",
"`print-config` takes one of the target ids above; there is no descriptor to",
"name for a host at this tier, which is the point of the tier.",
"",
"## The MCP surface",
"",
textwrap.fill(
f"repowise registers **{spell(counts['total'])} MCP tools**. A single-repo "
f"server advertises **{spell(counts['single_repo'])}** of them by default, "
f"and workspace mode adds {spell(counts['workspace_extra'])} more "
f"automatically for **{spell(counts['workspace'])}**. A further "
f"**{spell(counts['opt_in'])}** are off by default, enabled through the "
"`mcp.tools` config block or `--tools +name`. The `lean` profile trims the "
f"default surface to **{spell(counts['lean'])}** tools "
f"({spell(counts['lean_workspace'])} in workspace mode) for agents on a "
"tight context budget.",
width=_WRAP,
),
"",
"Per-tool detail: [MCP_TOOLS.md](MCP_TOOLS.md).",
"",
"## Adding an agent",
"",
"The step-by-step recipes, including indexing backends and hook and",
"transcript adapters, are in",
"[docs/architecture/agent-platform.md](../architecture/agent-platform.md).",
"In short, an integration target is:",
"",
"1. An `AgentIdentity` in",
" [`identity.py`](../../packages/core/src/repowise/core/agents/identity.py).",
"2. A descriptor module in `packages/cli/src/repowise/cli/agent_targets/targets/`",
" exporting a `TARGET` that satisfies the `AgentTarget` protocol in",
" [`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py).",
"3. One line in `_TARGET_MODULES` in",
" [`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py).",
"4. A README badge under the tier `derive_tier` gives it, checked by",
" `tests/unit/cli/test_agent_matrix.py`.",
"5. `python scripts/gen_agent_matrix.py` to add the row here.",
"",
"An indexing backend is its own module in",
"`packages/core/src/repowise/core/providers/llm/` subclassing `AgentCliProvider`,",
"a `ProviderSpec` in",
"[`specs.py`](../../packages/core/src/repowise/core/providers/llm/specs.py),",
"and one `Backend` entry in",
"`tests/unit/test_providers/test_agent_cli_contract.py`.",
"",
"Declare only what the agent genuinely has. `derive_tier` reads the adapter",
"names, so a descriptor that names a hook adapter it has not implemented",
"publishes a Full-tier claim on this page.",
"",
]
return "\n".join(parts).rstrip("\n") + "\n"
def rendered_files() -> dict[Path, str]:
"""Every generated file, mapped to the text it should hold."""
return {OUTPUT: render()}
# ---------------------------------------------------------------------------
# Write
# ---------------------------------------------------------------------------
def write_if_changed(path: Path, text: str) -> bool:
"""Write *text* as LF, and report whether it moved the file.
Normalises the file's line endings before comparing, because this repo is
checked out with ``core.autocrlf`` on Windows and an untouched generated
file reads back as CRLF. Git stores LF either way.
"""
if path.exists() and path.read_text(encoding="utf-8").replace("\r\n", "\n") == text:
return False
path.parent.mkdir(parents=True, exist_ok=True)
with open(path, "w", encoding="utf-8", newline="\n") as handle:
handle.write(text)
return True
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument(
"--check",
action="store_true",
help="report drift and exit non-zero instead of writing",
)
args = parser.parse_args(argv)
files = rendered_files()
drifted: list[Path] = []
for path in sorted(files):
text = files[path]
if args.check:
current = (
path.read_text(encoding="utf-8").replace("\r\n", "\n") if path.exists() else None
)
if current != text:
drifted.append(path)
elif write_if_changed(path, text):
drifted.append(path)
verb = "stale" if args.check else "wrote"
for path in drifted:
print(f"{verb}: {path.relative_to(ROOT).as_posix()}")
if args.check and drifted:
print(
f"\n{len(drifted)} generated file(s) disagree with the agent registry. "
"Run: python scripts/gen_agent_matrix.py",
file=sys.stderr,
)
return 1
if not drifted:
print("up to date" if args.check else "no changes")
return 0
if __name__ == "__main__":
raise SystemExit(main())