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
feat(agents): add the Basic tier and an Indexing column (#3169)
Raghav Chamadiya03e00bb0e09e
diff --git a/README.md b/README.mdindex 9bddf58b7..d078e193b 100644--- a/README.md+++ b/README.md@@ -537,16 +537,19 @@ paste away.**</p><p><strong>Good tier </strong>- <img src="https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code" /><img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=cursor&logoColor=white" alt="Cursor" /><img src="https://img.shields.io/badge/OpenCode-000000?style=flat-square&logo=opencode&logoColor=white" alt="OpenCode" /><img src="https://img.shields.io/badge/Hermes-000000?style=flat-square&logoColor=white" alt="Hermes" /></p>+<p>+ <strong>Basic tier </strong>+ <img src="https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code" />+</p>**Full** is every surface Repowise has: MCP tools, skills, slash commands, a managedinstructions file, hook-level interception of tool calls, and transcript mining after-the session. **Good** is MCP tools and the config to reach them, without hooks or-transcript mining. Anything else that speaks MCP is one snippet away:+the session. **Good** is MCP tools plus an instructions file or skills, without hooks+or transcript mining. **Basic** is the MCP config alone. Anything else that speaks MCP is one snippet away:`repowise agents print-config claude-code` prints a server entry for Cline, Windsurf,Zed, Gemini CLI or any host that reads `mcpServers`.[Integration matrix →](docs/agent/INTEGRATIONS.md)diff --git a/docs/agent/INTEGRATIONS.md b/docs/agent/INTEGRATIONS.mdindex 4ccf56061..f5be9b10f 100644--- a/docs/agent/INTEGRATIONS.md+++ b/docs/agent/INTEGRATIONS.md@@ -10,33 +10,37 @@ every breadth claim in this space gets wrong.## TiersThe tier is **derived from the code, never declared**. A descriptor reaches-Full only by naming both a hook adapter and a transcript adapter, so no-document can claim a depth the integration does not have.+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.- **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.** MCP tools, and a managed instructions file or skills where the host reads them. **No hook-level interception and no transcript mining.** The agent can ask repowise questions; repowise cannot see or annotate what the agent does in between.+- **Good.** MCP tools plus a managed instructions file or skills, so the agent is told when to reach for them. **No hook-level interception and no transcript mining.** The agent can ask repowise questions; repowise cannot see or annotate what the agent does in between.+- **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.** `repowise agents print-config <id>` emits the MCP server snippet and we write nothing. Zero code and zero maintenance per host.## The matrix`Yes` means repowise wires it. `Plugin` means the host's own plugin shipsit and repowise does not write it. `No` means the surface does not exist-for that agent.--| Agent | Tier | MCP | Hooks | Skills | Commands | Instructions | Transcripts |-|---|---|---|---|---|---|---|---|-| [Claude Code](https://docs.claude.com/en/docs/claude-code) | Full | Yes | Yes | Plugin | Plugin | Yes | Yes |-| [Codex CLI](https://developers.openai.com/codex/cli) | Full | Yes | Yes | Plugin | Yes | Yes | Yes |-| [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Good | Yes | No | No | No | No | No |-| [Cursor](https://cursor.com/docs/context/mcp) | Good | Yes | No | No | No | Yes | No |-| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Good | Yes | No | No | No | Yes | No |-| [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Good | Yes | No | No | No | Yes | No |+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.++| Agent | Tier | MCP | Hooks | Skills | Commands | Instructions | Transcripts | Indexing |+|---|---|---|---|---|---|---|---|---|+| [Claude Code](https://docs.claude.com/en/docs/claude-code) | Full | Yes | Yes | Plugin | Plugin | Yes | Yes | Yes |+| [Codex CLI](https://developers.openai.com/codex/cli) | Full | Yes | Yes | Plugin | Yes | Yes | Yes | Yes |+| [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Basic | Yes | No | No | No | No | No | No |+| [Cursor](https://cursor.com/docs/context/mcp) | Good | Yes | No | No | No | Yes | No | No |+| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Good | Yes | No | No | No | Yes | No | Yes |+| [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Good | Yes | No | No | No | Yes | No | No |Target ids for `--target=`: `claude-code`, `codex`, `vscode`, `cursor`, `opencode`, `hermes`.### What Good tier does not include-VS Code, Cursor, OpenCode and Hermes sit at Good, and the honest version of that is worth stating+Cursor, OpenCode and Hermes sit at Good, and the honest version of that is worth statingplainly. These agents get the MCP tools and the config repowise writes.They do **not** get hook-level interception: repowise never sees a toolcall before it runs, never rewrites a noisy command, and never annotates@@ -47,6 +51,12 @@ That is a real integration and it is most of the value. It is not thesame product Full-tier agents get, and breadth that overclaims depth isworse than narrower breadth.+### Basic tier++VS Code sits 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.+## Paste-configEvery other MCP host is served without writing a descriptor for it. Print@@ -83,20 +93,33 @@ Per-tool detail: [MCP_TOOLS.md](MCP_TOOLS.md).## Adding an agent-**Adding an agent takes one descriptor file and one registry line.**+**Adding an agent takes one identity record, one descriptor file and one+registry line.**-1. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`+1. Add an `AgentIdentity` to+ [`identity.py`](../../packages/core/src/repowise/core/agents/identity.py):+ its slug, display name, `executable` and, if its CLI can index,+ `indexing_provider`.+2. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`exporting a `TARGET` that satisfies the `AgentTarget` protocol in[`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py).`vscode.py` is the smallest working example, at one install method andone config file.-2. Add one line to `_TARGET_MODULES` in+3. Add one line to `_TARGET_MODULES` in[`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py).Order there is the order agents appear in prompts, in `--target=all` andin listings, so keep it stable.-3. Run `python scripts/gen_agent_matrix.py` to add the row here.+4. Run `python scripts/gen_agent_matrix.py` to add the row here.++An indexing backend adds three more pieces: a `ProviderSpec` in+[`specs.py`](../../packages/core/src/repowise/core/providers/llm/specs.py),+an `AgentCliProvider` subclass in+[`agent_cli.py`](../../packages/core/src/repowise/core/providers/llm/agent_cli.py),+and one `Backend` entry in+`tests/unit/test_providers/test_agent_cli_contract.py`, which runs the shared+provider contract against it.-There is no third file for anything derived. The tier, this matrix and the+There is no further file for anything derived. The tier, this matrix and the`repowise agents` listing all read the descriptor, and the contract tests in`tests/unit/cli/test_agent_targets.py` are parameterized over the registry,so a new target inherits them.diff --git a/docs/agent/VSCODE.md b/docs/agent/VSCODE.mdindex 0a281c64f..ca8682932 100644--- a/docs/agent/VSCODE.md+++ b/docs/agent/VSCODE.md@@ -106,9 +106,10 @@ assistants query the index through purpose-built tools instead of guessing fromopen files. For editors that read a config file, run **Repowise: Configure MCPfor this Workspace** to write `.vscode/mcp.json`.-VS Code sits at the **Good** support tier, and the honest version of that is+VS Code sits at the **Basic** support tier, and the honest version of that isworth knowing before you compare it to the Claude Code or Codex setup. You get-the MCP tools and the config to reach them. You do not get hook-level+the MCP tools and the config to reach them, but no managed instructions file or+skills telling the agent when to use them. You do not get hook-levelinterception: repowise never sees a tool call before it runs, never rewrites anoisy command, and never annotates a result afterwards, and there is notranscript mining after the session. What the extension itself surfaces in thediff --git a/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py b/packages/cli/src/repowise/cli/agent_targets/targets/vscode.pyindex 190d1b6f7..48197c8d3 100644--- a/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py+++ b/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py@@ -1,10 +1,10 @@"""VS Code as an agent target.-Good tier, and the descriptor makes that structural rather than editorial: it-names neither a hook adapter nor a transcript adapter, so :func:`derive_tier`-cannot place it at Full however many files it writes. VS Code gets the MCP-server and an extension recommendation; it has no hook protocol for repowise to-intercept tool calls through, and no transcript format to mine.+Basic tier, and the descriptor makes that structural rather than editorial: it+names neither a hook adapter nor a transcript adapter, and wires MCP without+instructions or skills, so :func:`derive_tier` places it at Basic. VS Code gets+the MCP server and an extension recommendation; it has no hook protocol for+repowise to intercept tool calls through, and no transcript format to mine.The distinguishing quirk is that both files it writes may legally containcomments — VS Code accepts JSONC throughout ``.vscode/``. So this target is thediff --git a/packages/cli/src/repowise/cli/agent_targets/types.py b/packages/cli/src/repowise/cli/agent_targets/types.pyindex 0c12303da..b4f3f97b1 100644--- a/packages/cli/src/repowise/cli/agent_targets/types.py+++ b/packages/cli/src/repowise/cli/agent_targets/types.py@@ -108,6 +108,7 @@ class Tier(StrEnum):FULL = "full"GOOD = "good"+ BASIC = "basic"PASTE_CONFIG = "paste-config"@@ -459,8 +460,10 @@ def derive_tier(target: AgentTarget) -> Tier:faked by writing a config file. Requiring both is what makes itstructurally impossible for the docs to claim Full while the sessionadapter is missing.- * Everything else is **Good**: a real integration, MCP and instructions and- possibly skills, but no hook-level interception.+ * A target that wires MCP plus managed instructions or skills is **Good**:+ the agent is told repowise exists, but nothing intercepts its tool calls.+ * Everything else is **Basic**: repowise writes the MCP config and nothing+ that tells the agent when to use it.Deliberately strict about Full. Breadth that overclaims depth is worse thannarrower breadth, and the tier is the thing the README badges repeat.@@ -469,4 +472,7 @@ def derive_tier(target: AgentTarget) -> Tier:return Tier.PASTE_CONFIGif target.hook_adapter and target.session_adapter:return Tier.FULL- return Tier.GOOD+ caps = capabilities_of(target)+ if Capability.MCP in caps and caps & {Capability.INSTRUCTIONS, Capability.SKILLS}:+ return Tier.GOOD+ return Tier.BASICdiff --git a/scripts/gen_agent_matrix.py b/scripts/gen_agent_matrix.pyindex 7c27cfad1..5e3ab86a9 100644--- a/scripts/gen_agent_matrix.py+++ b/scripts/gen_agent_matrix.py@@ -73,10 +73,15 @@ TIER_BLURBS: dict[str, tuple[str, str]] = {),"good": ("Good",- "MCP tools, and a managed instructions file or skills where the host "- "reads them. **No hook-level interception and no transcript mining.** "- "The agent can ask repowise questions; repowise cannot see or annotate "- "what the agent does in between.",+ "MCP tools plus a managed instructions file or skills, so the agent is "+ "told when to reach for them. **No hook-level interception and no "+ "transcript mining.** The agent can ask repowise questions; repowise "+ "cannot see or annotate what the agent 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",@@ -102,6 +107,7 @@ def agent_rows() -> list[dict]:"""from repowise.cli.agent_targets import registryfrom repowise.cli.agent_targets.types import Capability, derive_tier+ from repowise.core.agents.identity import identity_for_target_idrows: list[dict] = []for target in registry.all_targets():@@ -113,6 +119,7 @@ def agent_rows() -> list[dict]: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,@@ -123,6 +130,7 @@ def agent_rows() -> list[dict]:"host": by_manager["host"],"hook_adapter": target.hook_adapter,"session_adapter": target.session_adapter,+ "indexing_provider": identity.indexing_provider if identity else None,})return rows@@ -219,21 +227,23 @@ def spell(count: int) -> str:# Render# ----------------------------------------------------------------------------#: Column caption, and the capability it reads. ``None`` means the column is-#: derived from an adapter name rather than from a declared capability.-_COLUMNS: tuple[tuple[str, str | None], ...] = (+#: 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", None),+ ("Transcripts", "session_adapter"),+ ("Indexing", "indexing_provider"),)-def _cell(row: dict, capability: str | None) -> str:- if capability is None:- return "Yes" if row["session_adapter"] else "No"+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 Capabilitywanted = Capability(capability)@@ -282,6 +292,7 @@ def render() -> str:counts = tool_counts()ids = ", ".join(f"`{row['id']}`" for row in rows)good = [row["display_name"] for row in rows if row["tier"] == "good"]+ basic = [row["display_name"] for row in rows if row["tier"] == "basic"]parts = ["# Agent integrations",@@ -296,8 +307,9 @@ def render() -> str:"## 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, so no",- "document can claim a depth the integration does not have.",+ "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(),"",@@ -305,7 +317,9 @@ def render() -> str:"","`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.",+ "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.","",_matrix_table(rows),"",@@ -331,6 +345,16 @@ def render() -> str:"",]+ 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","",@@ -375,20 +399,33 @@ def render() -> str:"","## Adding an agent","",- "**Adding an agent takes one descriptor file and one registry line.**",+ "**Adding an agent takes one identity record, one descriptor file and one",+ "registry line.**","",- "1. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`",+ "1. Add an `AgentIdentity` to",+ " [`identity.py`](../../packages/core/src/repowise/core/agents/identity.py):",+ " its slug, display name, `executable` and, if its CLI can index,",+ " `indexing_provider`.",+ "2. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`"," exporting a `TARGET` that satisfies the `AgentTarget` protocol in"," [`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py)."," `vscode.py` is the smallest working example, at one install method and"," one config file.",- "2. Add one line to `_TARGET_MODULES` in",+ "3. Add one line to `_TARGET_MODULES` in"," [`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py)."," Order there is the order agents appear in prompts, in `--target=all` and"," in listings, so keep it stable.",- "3. Run `python scripts/gen_agent_matrix.py` to add the row here.",+ "4. Run `python scripts/gen_agent_matrix.py` to add the row here.",+ "",+ "An indexing backend adds three more pieces: a `ProviderSpec` in",+ "[`specs.py`](../../packages/core/src/repowise/core/providers/llm/specs.py),",+ "an `AgentCliProvider` subclass in",+ "[`agent_cli.py`](../../packages/core/src/repowise/core/providers/llm/agent_cli.py),",+ "and one `Backend` entry in",+ "`tests/unit/test_providers/test_agent_cli_contract.py`, which runs the shared",+ "provider contract against it.","",- "There is no third file for anything derived. The tier, this matrix and the",+ "There is no further file for anything derived. The tier, this matrix and the","`repowise agents` listing all read the descriptor, and the contract tests in","`tests/unit/cli/test_agent_targets.py` are parameterized over the registry,","so a new target inherits them.",diff --git a/tests/unit/cli/test_agent_identity.py b/tests/unit/cli/test_agent_identity.pyindex 3a4afa7c7..8f7b8019a 100644--- a/tests/unit/cli/test_agent_identity.py+++ b/tests/unit/cli/test_agent_identity.py@@ -5,8 +5,8 @@ same reason ``test_agent_targets.py`` is: the property under test is that theseam holds for *every* registered target, and a per-agent test file wouldquietly not have that property for the next one added.-``INTEGRATIONS.md`` promises adding an agent costs one descriptor file and one-registry line. The tests at the bottom are what stops savings attribution from+``INTEGRATIONS.md`` promises adding an agent costs one identity record, one+descriptor file and one registry line. The tests at the bottom are what stops savings attribution fromsilently not being included in that promise."""diff --git a/tests/unit/cli/test_agent_matrix.py b/tests/unit/cli/test_agent_matrix.pyindex edbf30da0..ea696d2a7 100644--- a/tests/unit/cli/test_agent_matrix.py+++ b/tests/unit/cli/test_agent_matrix.py@@ -190,6 +190,16 @@ def test_the_readme_agent_headline_counts_the_registry() -> None:)+def test_the_indexing_column_matches_the_identities() -> None:+ """Indexing is derived from ``indexing_provider``, never declared per row."""+ from repowise.core.agents.identity import identity_for_target_id++ for row in GEN.agent_rows():+ identity = identity_for_target_id(row["id"])+ expected = "Yes" if identity and identity.indexing_provider else "No"+ assert GEN._cell(row, "indexing_provider") == expected, row["id"]++def test_the_hooks_column_cannot_lie() -> None:"""A target's declared HOOKS capability agrees with its hook adapter.diff --git a/tests/unit/cli/test_agent_targets.py b/tests/unit/cli/test_agent_targets.pyindex 905a24867..38713272d 100644--- a/tests/unit/cli/test_agent_targets.py+++ b/tests/unit/cli/test_agent_targets.py@@ -122,7 +122,7 @@ def test_tiers_are_derived_from_the_adapters_a_target_names() -> None:"""Full requires both deep surfaces; VS Code has neither, so it cannot claim it."""assert tier_of("claude-code") is Tier.FULLassert tier_of("codex") is Tier.FULL- assert tier_of("vscode") is Tier.GOOD+ assert tier_of("vscode") is Tier.BASICassert tier_of("cursor") is Tier.GOODassert tier_of("opencode") is Tier.GOODassert tier_of("hermes") is Tier.GOOD@@ -147,6 +147,35 @@ def test_a_target_cannot_reach_full_without_a_session_adapter() -> None:assert derive_tier(_HooksOnly()) is Tier.GOOD+ ("provides", "tier"),+ [+ ({"mcp"}, Tier.BASIC),+ ({"mcp", "instructions"}, Tier.GOOD),+ ({"mcp", "skills"}, Tier.GOOD),+ ],+)+def test_good_needs_instructions_or_skills_beside_mcp(provides: set[str], tier: Tier) -> None:+ """MCP alone is Basic; the capability set decides, not having methods at all."""+ from repowise.cli.agent_targets.types import Capability, InstallMethod++ class _Wired:+ id = "wired"+ display_name = "Wired"+ docs_url = None+ hook_adapter = None+ session_adapter = None+ methods = (+ InstallMethod(+ id="direct",+ provides=frozenset(Capability(c) for c in provides),+ managed_by="repowise",+ ),+ )++ assert derive_tier(_Wired()) is tier++def test_a_target_that_writes_nothing_is_paste_config() -> None:class _Snippet:id = "snippet"diff --git a/tests/unit/cli/test_agents_cmd.py b/tests/unit/cli/test_agents_cmd.pyindex 1a02b033d..879142c3c 100644--- a/tests/unit/cli/test_agents_cmd.py+++ b/tests/unit/cli/test_agents_cmd.py@@ -82,7 +82,7 @@ def test_bare_agents_lists_every_registered_target_as_json(repo: Path) -> None:# The keys the table renders, so a dropped one is a broken table.assert set(row) >= {"id", "tier", "present", "registrations", "method"}assert payload["agents"][0]["tier"] == "full"- assert payload["agents"][2]["tier"] == "good"+ assert payload["agents"][2]["tier"] == "basic"def test_list_reports_registrations_as_a_list_not_a_boolean(repo: Path) -> None: