Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Agent platform internals
How repowise describes the coding agents it works with, and the recipes for adding one. The public view of the same thing is agent/INTEGRATIONS.md, which is generated from the registries described here.
An agent can touch repowise in two independent ways:
- Integration: repowise wires the agent up as an MCP host: it writes the server config, and depending on the agent, an instructions block, skills, hooks and a transcript reader.
- Indexing backend: the agent's own CLI runs as the LLM that writes the wiki, using the user's existing login, with no API key.
An agent can have either, both or neither. GitHub Copilot CLI is both an integration target and an indexing backend through its authenticated local CLI.
Contents
- How it fits
- Recipe A: adding an indexing backend
- Recipe B: adding an integration target
- Recipe C: hook and transcript adapters
- Guards you will hit
How it fits
AgentIdentity (core/agents/identity.py)
slug, display name, executable, install and login hints,
hook_adapter, session_adapter, indexing_provider
| | |
| indexing_provider | cli_target_id | hook_adapter / session_adapter
v v v
ProviderSpec AgentTarget AgentAdapter (cli/agent_adapters)
(providers/llm/specs.py) (cli/agent_targets/ HarnessAdapter (core/sessions/adapters)
| targets/<id>.py)
| impl |
v v
AgentCliProvider subclass derive_tier -> Full / Good / Basic / Paste-config
(providers/llm/<name>.py)
All paths below are under packages/core/src/repowise/core/ or
packages/cli/src/repowise/cli/ unless written in full.
| Piece | File | Holds |
|---|---|---|
AgentIdentity |
core/agents/identity.py |
One record per agent: slug, display name, executable, login_check, install_hint, login_hint, the adapter names, and indexing_provider. Every other namespace derives its spelling of the agent from here. |
ProviderSpec |
core/providers/llm/specs.py |
One record per LLM provider. KEYLESS_PROVIDERS, REPO_PATH_PROVIDERS, PROVIDER_DEFAULTS, ZERO_COST_MODEL_PREFIXES, the server catalog and the init picker rows are all computed from PROVIDER_SPECS. |
AgentCliProvider |
core/providers/llm/agent_cli.py |
The shared subprocess base for agent CLI backends: executable lookup, stdin prompt, timeout and kill, cancellation, a per-loop concurrency semaphore, error tails, model labels, cost booking. |
| Integration targets | cli/agent_targets/ |
types.py (the AgentTarget protocol and derive_tier), registry.py (_TARGET_MODULES), targets/<id>.py (one descriptor per agent), instructions.py (the shared managed block), formats/ (JSON, TOML, YAML and marker-block writers). |
| Hook adapters | cli/agent_adapters/ |
AgentAdapter in base.py, registered in _REGISTRY in __init__.py. |
| Transcript adapters | core/sessions/adapters/ |
HarnessAdapter in base.py, registered with @register_adapter and imported in __init__.py. |
The two registries meet in exactly one place: ProviderSpec.agent names the
agent slug, and AgentIdentity.indexing_provider names the spec back. A test
holds the two links to each other.
The tier is never declared. derive_tier in agent_targets/types.py reads the
descriptor:
- no install methods: Paste-config
- names both a hook adapter and a session adapter: Full
- wires MCP plus instructions or skills: Good
- anything else: Basic
The server exposes the provider specs at /api/providers
(packages/server/src/repowise/server/provider_config.py), and the web UI reads
its provider list, models and setup hints from there. No UI file names a
provider.
Recipe A: adding an indexing backend
The worked reference is core/providers/llm/opencode.py. The steps below use
copilot_cli as the example name. Name the module after the provider: the
provider-name guard (see Guards) lets a provider's own
module spell its name, matched by file stem.
Step 1: the provider module
Create packages/core/src/repowise/core/providers/llm/copilot_cli.py
with a subclass of AgentCliProvider.
from repowise.core.providers.llm.agent_cli import AgentCliProvider, iter_jsonl, tail
from repowise.core.providers.llm.base import GeneratedResponse, ProviderError
from repowise.core.reasoning import ReasoningMode
class CopilotCliProvider(AgentCliProvider):
provider_name = "copilot_cli"
agent_slug = "copilot" # the AgentIdentity slug
command_label = "copilot" # how errors name the invocation
concurrency_env = "REPOWISE_COPILOT_CLI_CONCURRENCY"
def build_command(self, system_prompt: str, reasoning: ReasoningMode) -> list[str]:
cmd = [self._executable, ...] # non-interactive, read-only flags
if self._model:
cmd += ["--model", self._model]
return cmd
def parse_output(self, stdout: str, stderr: str) -> GeneratedResponse:
... # text plus token counts
The base derives executable_name and the not-found message from the identity
named by agent_slug, so the class fails at import if that identity has no
executable. Never shell out yourself or use shell=True: the base spawns the
process without a shell, passes the prompt on stdin and validates model names.
Required:
build_command(system_prompt, reasoning)returns argv for one call. Pass the model as--model <slug>whenself._modelis set; the contract test reads it from there. Use the CLI's read-only or no-tools mode: indexing must never edit the repo.parse_output(stdout, stderr)builds theGeneratedResponsefrom a successful run. RaiseProviderErrorwhen the output carries no text.
Optional hooks on AgentCliProvider, override only what the CLI needs:
| Hook | Default | Override when |
|---|---|---|
build_stdin(system_prompt, user_prompt) |
the user prompt alone | the CLI has no system-prompt flag and the two must be combined (opencode, codex) |
working_dir() |
no cwd change | the CLI should run somewhere neutral, such as a scratch dir (claude_cli) |
subprocess_env() |
inherit the parent env | the CLI needs env vars, such as a locked-down config (opencode) |
exec_timeout_seconds() |
EXEC_TIMEOUT_SECONDS (600) |
the CLI needs a different ceiling |
exit_error(returncode, stdout, stderr) |
ProviderError with the stderr tail |
a non-zero exit needs a clearer message, such as "not logged in" (claude_cli) |
stdout_error(stdout) |
None |
the CLI reports failures as structured events on stdout (opencode) |
Class attributes with defaults: default_model (None lets the CLI's own
config choose), validates_model_name (True; codex turns it off and lets its
model catalog decide), records_cost (False; only claude_cli
books llm_costs rows), error_tail_chars.
From BaseProvider, override available_model_options() when the CLI can list
its models (opencode runs opencode models, cached with lru_cache, with
stdin=subprocess.DEVNULL), and supported_reasoning_modes() when the CLI
takes a reasoning flag. The defaults offer one option, the configured model,
with reasoning auto.
self._repo_path holds the repo the CLI should read. Pass it with the CLI's
directory flag (codex uses --cd) or, when the CLI has none, as the
subprocess working directory (opencode); claude_cli ignores it.
Step 2: the ProviderSpec
Add a record to _SPECS in core/providers/llm/specs.py. Declaration order is
the server catalog's order.
ProviderSpec(
name="copilot_cli",
picker_rank=9,
impl=f"{_LLM}.copilot_cli:CopilotCliProvider",
label="GitHub Copilot (Local CLI)",
default_model="copilot_cli/default",
models=("copilot_cli/default",),
keyless=True,
needs_repo_cwd=True,
local=True,
zero_cost=True,
agent="copilot",
note="uses your Copilot CLI login",
),
| Field | What reads it |
|---|---|
name, impl |
get_provider imports impl lazily; _BUILTIN_PROVIDERS is derived from it |
label |
the server catalog's display name, shown in the web UI settings |
default_model, models |
the init picker's model list and the server catalog; agent CLI models are prefixed <name>/ |
keyless |
KEYLESS_PROVIDERS: resolution never rejects the provider for a missing key |
needs_repo_cwd |
REPO_PATH_PROVIDERS: provider_kwargs passes repo_path, and a workspace init rebinds the provider to each repo. Leave it off if the CLI runs in a scratch dir |
local |
init warns that concurrency above 4 may time out; the server prices unknown local models at zero |
zero_cost |
ZERO_COST_MODEL_PREFIXES: the cost estimator and cost tracker price <name>/... models at zero |
agent |
the agent slug; links the spec to the identity and supplies setup_hint from its install and login hints |
picker_rank |
the row in the repowise init picker and inclusion in /api/providers; None makes it flag-only |
note |
the dim note beside the row in the picker, and the reason line when the picker defaults to it |
Agent CLIs keep rate_limit=None, api_key_envs=() and autodetect_rank=None.
Ranks must stay unique. Today opencode is 8, ollama 9, openrouter 10 and
litellm 11. Giving copilot_cli rank 9 puts it right after opencode, so
change ollama to 10, openrouter to 11 and litellm to 12.
Step 3: link the identity
COPILOT already exists in core/agents/identity.py with executable,
install_hint and login_hint. The only edit is indexing_provider="copilot_cli"
on that record. Add login_check only if the CLI has a status command, verified
against its docs, that exits 0 only when signed in; the init picker uses it to
decide whether the backend is ready.
For an agent with no identity yet, add one as in
Recipe B step 1, with executable, install_hint and
login_hint set: the CLI prints them when the executable is missing.
Step 4: the contract test
Add one Backend to BACKENDS in
tests/unit/test_providers/test_agent_cli_contract.py, and import the class at
the top of the file:
@dataclass(frozen=True)
class Backend:
cls: type[AgentCliProvider]
model: str # a native slug the CLI receives after ``--model``
success_stdout: Callable[[str], str] # CLI output whose answer is the argument
tokens: tuple[int, int, int] # parsed (input, output, cached)
books_cost: bool
repo_flag: str | None # flag that points the CLI at the repo; None = scratch cwd
env: dict[str, str] | None # entries the subprocess env must carry
success_stdout is a function that returns real CLI output with the answer
swapped in. Build it from a real run: run the CLI once in the mode
build_command uses, keep the events parse_output reads (the text and the
usage), and write them as a builder next to _opencode_stdout. Provider output
samples live inline in the tests, not in tests/fixtures/. Do not invent
fields the CLI does not emit.
The contract then checks names, the missing-executable error, argv and stdin,
the repo flag or scratch dir, the env, cost booking, the non-zero exit, timeout
and cancellation kills, and the concurrency semaphore. CLI-specific parsing
(noise lines, error events, missing usage, the model catalog) goes in a
tests/unit/test_providers/test_copilot_cli_provider.py
modelled on test_opencode_provider.py.
Step 5: update the frozen lists
Two tests in tests/unit/cli/test_init_ux.py freeze the picker on purpose, so
a new row is a deliberate edit:
test_picker_rows_keep_their_order: put"copilot_cli"after"opencode"in the expected_PROVIDER_CHOICEStuple.test_the_keyless_providers_get_setup_help_instead_of_a_key_prompt: add"copilot_cli"to the expected set of_LOCAL_PROVIDER_SETUPkeys.
Provider-name literals are fine in tests: the provider-name guard scans
packages/*/src only.
Then regenerate the matrix, whose Indexing column now reads Yes for the
agent:
python scripts/gen_agent_matrix.py
Step 6: user docs (optional)
A user page at docs/agent/<NAME>.md is optional. If you add one, follow
docs/agent/OPENCODE.md, and put paths to files in a user's repo behind
<!-- repowise-drift-ignore -->.
What you get without further edits
- A row in the
repowise initpicker with install and login help when the CLI is missing. When the agent is set up as a target in the repo and its CLI is ready, the picker defaults to it (agent_providers_set_upincli/ui/provider_selection.py). repowise init --provider copilot_cliand keyless resolution in the CLI and the MCP server.- An entry in
/api/providerswith its setup hint, and so in the web UI. - Zero-cost pricing for its models, no client-side rate limiter, and the local-concurrency warning.
- Per-repo binding in a workspace init when
needs_repo_cwdis set. - The shared contract tests and the registry link tests.
Verify
pytest tests/unit/test_providers/ tests/providers/ -q
pytest tests/unit/cli/test_init_ux.py tests/unit/cli/test_init_agent_backend.py \
tests/unit/cli/test_agent_identity.py tests/unit/cli/test_agent_matrix.py \
tests/unit/server/test_provider_config.py -q
ruff check .
Then by hand, with the CLI installed and logged in, on a small repo:
repowise init --provider copilot_cli --yes
repowise init # interactive: check the row, the note and the default
Recipe B: adding an integration target
Before writing anything, check every host fact (config file paths, the MCP
entry shape, which instruction files the host reads, how to tell it is
installed) against the host's own docs, and cite the source in the module
docstring. targets/copilot.py shows the shape. Where a fact is assumed and
not documented, say so there.
Step 1: the identity
Add an AgentIdentity constant (for example MYAGENT) in
core/agents/identity.py and append it to the for _shipped in (...) tuple at
the bottom of the file. The --target id is
derived: kiro for slug kiro, claude-code for claude_code. Leave
hook_adapter and session_adapter unset until Recipe C.
Step 2: the target module
Write packages/cli/src/repowise/cli/agent_targets/targets/<id>.py exporting
TARGET, an object that satisfies the AgentTarget protocol in types.py.
targets/vscode.py is the smallest complete example. The usual top of the
module, where MYAGENT is the identity constant you added in step 1:
from repowise.core.agents import identity
from ..types import (
Capability,
DoctorReport,
DoctorStatus,
FileAction,
FileWrite,
InstallMethod,
Registration,
Scope,
WriteResult,
)
IDENTITY = identity.MYAGENT
ID = IDENTITY.cli_target_id
DISPLAY_NAME = IDENTITY.display_name
DOCS_URL = "https://..."
PROJECT_FILE_ID = "myagent_mcp" # key under editor_files in .repowise/config.yaml
METHODS = (
InstallMethod(
id="direct",
provides=frozenset({Capability.MCP, Capability.INSTRUCTIONS}),
managed_by="repowise",
preferred=True,
),
)
The class carries the attributes AgentTarget requires: id = ID,
display_name = DISPLAY_NAME, docs_url = DOCS_URL, methods = METHODS,
project_file_id = PROJECT_FILE_ID, hook_adapter = IDENTITY.hook_adapter and
session_adapter = IDENTITY.session_adapter. The module ends with
TARGET = MyAgentTarget().
Every protocol method must be safe when nothing was ever installed:
supports_scope, is_present (a PATH or directory probe, never a
subprocess), detect (a list of Registrations, never raises), install,
uninstall (removes only what install wrote), print_config (no filesystem
access), describe_paths and doctor. Use the writers in formats/ for
JSON, TOML, YAML and marker blocks; do not hand-roll a merge.
For the instructions block, write the shared text from instructions.py
(DISTILL_SECTION between DISTILL_MARKER_START and DISTILL_MARKER_END)
with formats.marker_block.upsert. Text outside the markers belongs to the
user and must round-trip byte for byte.
If two targets write the same file, one owns the block and the other shares
it. copilot reuses vscode.write_instructions for
.github/copilot-instructions.md, and vscode.remove_instructions asks
registry.other_managers_of before stripping the block, so removing one agent
leaves the block in place while the other still reads it.
Step 3: register it
Append one line to _TARGET_MODULES in agent_targets/registry.py. Order is
the order agents appear in prompts, in --target=all and in listings, so new
ids go at the end. Append the same id to the frozen list in
test_registry_exposes_the_shipped_targets in
tests/unit/cli/test_agent_targets.py.
The repowise init checklist only offers targets that have an
InstallLifecycle writer in get_default_editor_integrations
(cli/editor_integrations/defaults.py): Claude Code, Codex and VS Code. Any
other target is wired with repowise agents add --target=<id>, so add a row to
the host table in docs/start/QUICKSTART.md.
Step 4: the README badge and the matrix
Add a badge to the ## Supported agents and editors section of README.md,
under the row for the tier derive_tier gives it, and update the count in the
sentence above the badges. Then:
python scripts/gen_agent_matrix.py
Step 5: verify
pytest tests/unit/cli/test_agent_targets.py tests/unit/cli/test_agent_identity.py \
tests/unit/cli/test_agent_matrix.py tests/unit/agents/ -q
repowise agents add --target=<id> --scope=project --yes
repowise agents
repowise agents remove --target=<id> --scope=project
The protocol, idempotency, print_config and describe_paths tests in
test_agent_targets.py are parameterized over the registry, so the new target
is covered without new test code.
Recipe C: hook and transcript adapters
A target reaches Full only when its identity names both adapters. Declare only what is implemented and verified against the host's docs or real data. A name on the identity is a public claim: it moves the agent to the Full row of the README and the matrix.
Hook adapter
Subclass AgentAdapter in cli/agent_adapters/base.py and add it to
_REGISTRY in cli/agent_adapters/__init__.py, keyed by the name its hook
config passes as --client. Abstract methods: detect,
parse_hook_payload, render_response, install_rewrite_hook,
uninstall_rewrite_hook, rewrite_hook_installed.
The class variables answer what the host's hook protocol can do:
rewrite_permissions, replaces_tool_output, shell_tool_names,
read_tool_names, edit_tool_names, search_tool_names, savings_source.
Leave a default in place until the host's docs or a captured payload show
otherwise. A wrong replaces_tool_output=True records savings the agent never
saw.
Module scope stays stdlib-only: this runs on the PreToolUse hot path.
agent_adapters must never import agent_targets.
Set hook_adapter="<registry key>" on the identity, and add
Capability.HOOKS to the target's install method.
Transcript adapter
Subclass HarnessAdapter in core/sessions/adapters/base.py, decorate it
with @register_adapter, and import it in core/sessions/adapters/__init__.py.
Implement discover(repo_root, *, projects_root=None) and
normalize(raw_line); declare edit_tool_names and shell_tool_names in the
host's own vocabulary. Test it against a real transcript, trimmed and
anonymized, as tests/unit/sessions/test_claude_code_adapter.py does.
Set session_adapter="<adapter name>" on the identity, and add
Capability.TRANSCRIPTS to the target's install method.
Guards you will hit
tests/unit/test_providers/test_provider_specs.py:
test_no_module_branches_on_a_provider_nameparses every Python source underpackages/*/srcand fails when a provider name is used in a comparison, amatchcase, a collection, a dict key or a.get()key outside the registries. Read aProviderSpecfield (spec.agent,spec.needs_repo_cwd,spec.local) or callidentity_for_providerinstead of spelling the name. A provider's own module may spell its own name.test_no_ui_source_spells_a_provider_namescanspackages/ui,packages/webandpackages/api-clientfor quoted provider or embedder names. The UI reads them from/api/providers.- The link tests fail when
indexing_providerandProviderSpec.agentdo not name each other, when the identity lacksexecutable,install_hintorlogin_hint, or when an agent spec gets a rate limiter.
tests/unit/cli/test_agent_matrix.py:
docs/agent/INTEGRATIONS.mdmust matchpython scripts/gen_agent_matrix.pyoutput. Run the script; never edit the file.--checkreports drift without writing.- The README badge rows must match the derived tiers, and the headline count must match the registry.
- A target's
Capability.HOOKSmust agree with itshook_adapter.
tests/unit/cli/test_agent_identity.py fails when an identity names a hook or
session adapter that is not registered.
CI also runs repowise doc-drift --check, which flags a doc that names a file,
symbol or command that does not exist. A path to a file in a user's repo, or a
file you are about to create, needs <!-- repowise-drift-ignore --> on its
line.