# repowise documentation

> repowise is an open-source (AGPL-3.0) codebase intelligence platform that indexes any repository once and serves both AI coding agents and the humans accountable for the code. For agents, it provides queryable architecture documentation, a dependency graph, git intelligence, architectural decisions, and ten MCP tools for Claude Code, Cursor, Cline, and Codex. For teams, it provides a defect-validated code-health score (cross-project ROC AUC 0.74 across 21 repos and 9 languages), change-risk analysis, dead code detection, and agent provenance tracking. The core engine is free, self-hosted, and requires no cloud account.

Setting up Repowise for a user? Follow https://docs.repowise.dev/setup.md, a step-by-step runbook written for coding agents.

Every page below is also served as Markdown: append `.md` to its URL (https://docs.repowise.dev/index.md for the docs home), or request the page URL with `Accept: text/markdown`.

- [Welcome to repowise](https://docs.repowise.dev): Repowise indexes your repository into five intelligence layers and serves them to your AI coding agent through its MCP tools, so the agent reads an answer instead of re-reading your codebase. Self-hosted or hosted, same engine.
- Getting Started
  - [What is repowise](https://docs.repowise.dev/getting-started/what-is-repowise): Repowise indexes your codebase into five intelligence layers (graph, git, wiki, decisions, code health) and exposes them to AI agents through task-shaped MCP tools. The why your AI agent has been missing.
  - [Agent setup runbook](https://docs.repowise.dev/getting-started/setup): Step-by-step instructions a coding agent follows to install Repowise, index the current repository, connect the MCP tools, and report back. Written for the agent, readable by anyone.
  - [How it works](https://docs.repowise.dev/getting-started/how-it-works): The five intelligence layers Repowise computes and how they fit together.
  - [Quickstart](https://docs.repowise.dev/getting-started/quickstart): Install repowise, index your repo, and connect Claude Code in under a minute. Two paths, self-hosted (pip) or hosted (repowise.dev).
  - [Set up with your agent](https://docs.repowise.dev/getting-started/for-agents): Paste one line into Claude Code, Codex, Cursor, or any coding agent and it installs Repowise, indexes the repo, connects the MCP tools, and asks you one question. Also covers the Claude Code plugin, per-host setup, and the Markdown endpoints agents read.
  - [Agent plugins](https://docs.repowise.dev/getting-started/plugins): The Claude Code and Codex plugins bundle the MCP server, lifecycle hooks, skills, and slash commands into one install. What each plugin ships, how to install it, and what activates when.
  - [VS Code extension](https://docs.repowise.dev/getting-started/vscode): The Repowise extension brings the local index into VS Code (editor-native health signals, refactoring CodeLens, branch risk, in-editor dashboards) and registers the Repowise MCP server so the same index serves both you and your AI agent.

- [Auto-sync](https://docs.repowise.dev/auto-sync): Five ways to keep your repowise wiki current as code changes: post-commit hook, file watcher, GitHub webhook, GitLab webhook, and a polling safety net.
- [Git worktrees](https://docs.repowise.dev/worktrees): Index a linked git worktree without re-indexing from scratch, by seeding from the base checkout and catching up incrementally.
- [Gates in CI](https://docs.repowise.dev/ci): Fail a pull request on low patch coverage, new documentation drift, new security findings or unusual change risk, and run only the tests it needs. No index and no API key.

- Intelligence layers
  - [Dependency graph](https://docs.repowise.dev/intelligence/dependency-graph): A two-tier graph of files and symbols where every call edge is stamped with the strategy that resolved it, built with no model calls and no network.
  - [Git history & co-changes](https://docs.repowise.dev/intelligence/git-history): Hotspots, ownership, bus factor, and co-change pairs, the signals repowise mines from your last 500 commits that no AST analysis can produce.
  - [Bug-fix history](https://docs.repowise.dev/intelligence/bug-history): Which files and functions have actually been bug-fixed, how often, and how recently, computed from git alone with a fix-shape classifier validated at 98.3% on 240 hand-labelled commits.
  - [Change risk](https://docs.repowise.dev/intelligence/change-risk): Scores a commit or a base..head range for defect risk from the shape of its diff, not the health of any file. A just-in-time, pre-merge signal, calibrated offline and zero-LLM at runtime.
  - [Change review API](https://docs.repowise.dev/intelligence/change-review): The Python API that composes one change review out of the existing primitives. Runs without a git checkout, reports five evidence states per lane, and serializes to a versioned dict for bots and CI.
  - [Auto-generated wiki](https://docs.repowise.dev/intelligence/auto-wiki): How repowise writes a documentation page for every module and notable file: incrementally, with citations, with confidence scoring, and refreshed in under 30 seconds per commit.
  - [Deterministic wiki](https://docs.repowise.dev/intelligence/deterministic-wiki): The wiki repowise renders entirely from your code's structure, with no API key and no spend. Every page except the subsystem concept tree is structural either way; a model only adds prose on top.
  - [Package pages and Public API](https://docs.repowise.dev/intelligence/package-pages): In a monorepo, a package that spans several subsystems gets one documentation page for the whole package, and the page is written from the package's computed Public API, the names a consumer can import, read off manifests and re-exports.
  - [Architecture diagrams](https://docs.repowise.dev/intelligence/architecture-diagrams): The architecture map in your documentation, the C4 system context, container and component views built from the index, and the Structurizr DSL export. All built from the dependency graph and manifests, with no model.
  - [Architectural decisions](https://docs.repowise.dev/intelligence/decisions): First-class decision records linked to the files they govern: captured by hand, mined from git history, or extracted from inline markers. Surfaced to AI agents via get_why so the why survives the team.
  - [Code health](https://docs.repowise.dev/intelligence/code-health): A 1 to 10 health score for every file from deterministic markers across three signals: defect risk, maintainability, and performance. Zero LLM calls, defect-calibrated weights, validated to out-rank the leading commercial code-health tool at predicting real bugs.
  - [Documentation drift](https://docs.repowise.dev/intelligence/doc-drift): repowise checks the paths, links, headings, commands and symbol names your markdown mentions against the real tree, and reports the ones that no longer exist. No model, refreshed on every update.
  - [Test intelligence](https://docs.repowise.dev/intelligence/test-intelligence): Ingest a coverage report and repowise answers two questions your CI cannot: which files are risky and untested, and which tests a given diff actually exercises.
  - [Dead code](https://docs.repowise.dev/intelligence/dead-code): Files nothing imports, exports nothing uses, and packages nothing depends on, each with a confidence score and the evidence behind it.
  - [Security signals](https://docs.repowise.dev/intelligence/security-signals): A deterministic pattern registry in OSS core that flags dangerous calls and committed credentials, with a history mode, line verification, and a stated list of what it cannot see.
  - [Findings and triage](https://docs.repowise.dev/intelligence/findings): What a finding is, the finding families repowise produces, the registry that decides which finding types each surface shows, and how a status you set on a finding persists across re-analysis.
  - [Refactoring intelligence](https://docs.repowise.dev/intelligence/refactoring): A health score tells you a file is in trouble; refactoring intelligence names the specific fix. Six deterministic detectors (Extract Class, Extract Helper, Move Method, Break Cycle, Split File, Extract Method) emit one structured, graph-aware plan per opportunity, ranked by impact and effort. No LLM in the hot path; code generation runs only on demand, on by default and opt-out.
  - [Proactive agent hooks](https://docs.repowise.dev/intelligence/hooks): Lightweight editor hooks that push graph, git, health, and decision context into Claude Code and Codex at the moment the agent needs it: no LLM, no network, fail-silent. This is also how repowise learns from how you actually use it.
- Multi-repo
  - [Workspace setup](https://docs.repowise.dev/multi-repo/workspace-setup): Index multiple related git repos as a single repowise workspace. Get cross-repo co-changes, API contract matching, and MCP queries that federate across member repos on the tools that support it, on top of per-repo intelligence.
  - [Cross-repo intelligence](https://docs.repowise.dev/multi-repo/cross-repo): What repowise learns from analyzing several repos together. Co-change pairs, API contracts (HTTP / gRPC / topics), and package dependency mapping. Hidden coupling that single-repo tools can't find.
  - [System graph & map](https://docs.repowise.dev/multi-repo/system-map): The service-granular system graph repowise folds every cross-repo signal into, the System Map that renders it, and the extraction diagnostics that explain why a contract link did or didn't form.
  - [Cross-repo blast radius](https://docs.repowise.dev/multi-repo/blast-radius): If you change this service, what downstream services and repos break? Blast radius walks the system graph against its edges and returns every reachable service ranked by impact.
  - [Breaking-change guard](https://docs.repowise.dev/multi-repo/breaking-changes): Did a provider change in a way that actually breaks its consumers? On every workspace update, freshly-extracted contracts are diffed against the previous index and each incompatible change is reported with the exact consumer files it endangers.
  - [Architecture conformance](https://docs.repowise.dev/multi-repo/conformance): Declare which services may depend on which others, then continuously check the live system graph against those rules. Your team's architecture lint, plus automatic dependency-cycle detection.
  - [Architecture metrics](https://docs.repowise.dev/multi-repo/architecture-metrics): The one evaluative read of the whole system, propagation cost, the cyclic core, per-service roles, and a deterministic 1-10 architecture score. Standard architecture-complexity metrics computed over the system graph, no LLM.
  - [Workspace MCP mode](https://docs.repowise.dev/multi-repo/workspace-mcp): Self-hosted workspace mode. Pass repo="backend" to target one workspace repo, or repo="all" on the four tools that federate, plus three workspace-only tools for cross-repo blast radius, conformance, and architecture.

- CLI reference
  - [CLI overview](https://docs.repowise.dev/cli/overview): All `repowise` commands at a glance.
  - [Indexing: init, update, reindex](https://docs.repowise.dev/cli/indexing): The three commands that build and maintain repowise's intelligence layers. init parses everything from scratch, update is incremental on each commit, reindex rebuilds the vector store without re-running the LLM.
  - [Server & watch: serve, watch, mcp](https://docs.repowise.dev/cli/server): Run the repowise API and dashboard, auto-update on file save, or expose the MCP server directly to an editor.
  - [Query: search, ask, context, symbol, why, status](https://docs.repowise.dev/cli/query): Search, ask questions, read symbols, and check sync state from the terminal without involving an editor.
  - [Distill: compact command output](https://docs.repowise.dev/cli/distill): Run noisy commands through repowise distill for an errors-first, fully reversible rendering that cuts 60 to 90% of the tokens on tests, builds, git, and searches, with zero error-line loss.
  - [Code health: health, risk](https://docs.repowise.dev/cli/health): repowise health scores every file from deterministic markers across three signals (defect risk, maintainability, performance); repowise risk scores the defect risk of a commit or diff range. Both are zero-LLM and run in seconds.
  - [Coverage and CI gates: coverage, impacted-tests, doc-drift, security check](https://docs.repowise.dev/cli/gates): Flags for ingesting coverage, gating a change on patch coverage, selecting the tests a change needs, and the doc-drift and security gates.
  - [Workspace: multi-repo commands](https://docs.repowise.dev/cli/workspace): Manage repos in a repowise workspace: list, add, remove, scan, and pick the default.
  - [Decisions: capture, review, govern](https://docs.repowise.dev/cli/decision): Record architectural decisions so the why survives the team. Review what capture proposed, accept the ones that should govern, keep the manifest in git, and control which sources run.
  - [Hooks: auto-sync on commit](https://docs.repowise.dev/cli/hook): Install, check, and remove the post-commit git hook that keeps the repowise wiki current after every commit.
  - [Agents: add, remove, refresh](https://docs.repowise.dev/cli/agents): Wire repowise into Claude Code, Codex, Cursor, VS Code, OpenCode, or Hermes, or drop the config snippet for anything else.
  - [Uninstall: remove repowise](https://docs.repowise.dev/cli/uninstall): Remove repowise from this repo, and optionally from this machine, with a full inventory of every path it ever wrote.
  - [Other commands](https://docs.repowise.dev/cli/other): One-shot utilities: costs, next, overlap, dead-code, security scan, doctor, export, generate-claude-md, telemetry, config hints, login/logout/whoami, publish, augment, delete.
- MCP tools: The small, curated set of MCP tools repowise exposes to AI agents.
  - [MCP tools: overview](https://docs.repowise.dev/mcp/overview): The small, curated set of MCP tools repowise exposes to Claude Code and any MCP-compatible AI agent. Task-shaped, batched, and built to collapse long tool-call chains into one round-trip.
  - [get_overview](https://docs.repowise.dev/mcp/get-overview): Architecture summary, module map, entry points and git health for an entire repository: the first call your agent should make on any unfamiliar codebase. Onboarding, ownership and graph blocks are opt-in.
  - [get_answer](https://docs.repowise.dev/mcp/get-answer): One-call RAG synthesis over the wiki: it retrieves, gates on confidence, and returns a cited answer with fallback file targets. The first tool to call on any code question.
  - [get_context](https://docs.repowise.dev/mcp/get-context): The workhorse tool. Compact, batched context for any set of files, modules, or symbols: docs, ownership, freshness, and optional callers/callees/metrics/community in one call.
  - [get_symbol](https://docs.repowise.dev/mcp/get-symbol): Raw source bytes for one indexed symbol with exact line bounds, cheaper and safer than reading the whole file and counting offsets. The only MCP tool that returns actual source code.
  - [search_codebase](https://docs.repowise.dev/mcp/search-codebase): Hybrid code search over repowise's indexes: symbols, file paths, or the wiki, depending on the shape of the query. One tool instead of a fallback to Grep for identifiers.
  - [get_risk](https://docs.repowise.dev/mcp/get-risk): Modification-risk assessment for files before editing, covering hotspot scores, dependents, co-change partners, blast radius, recommended reviewers, test gaps, and security signals.
  - [get_change_risk](https://docs.repowise.dev/mcp/get-change-risk): Review a commit, a base..head range, or uncommitted work: what the change newly made worse, the tests that cover the changed lines, the fix history of the files it touches, and how its shape ranks against the repo's own commits.
  - [get_why](https://docs.repowise.dev/mcp/get-why): Architectural-decision archaeology. Search decisions in natural language, anchor them to a file path, resolve an emitted evidence id, or pull the decision-health dashboard. Falls back to git archaeology when nothing is recorded.
  - [get_dead_code](https://docs.repowise.dev/mcp/get-dead-code): Tiered refactor plan for unused code. High/medium/low confidence findings with per-directory rollups, ownership hotspots, and safe-to-delete impact estimates. Pure graph + SQL, no LLM calls.
  - [get_health](https://docs.repowise.dev/mcp/get-health): Code-health scores and marker findings per file across three signals (defect risk, maintainability, performance), exposed to your agent so it can self-check a change before opening a PR.
  - [list_repos](https://docs.repowise.dev/mcp/list-repos): Lists the repos this MCP server can reach, and their aliases. On by default in both single-repo and workspace mode; one of the tools that takes no parameters.

  - [generate_refactoring_code](https://docs.repowise.dev/mcp/generate-refactoring-code): Turns one structured refactoring plan from get_health(include=["refactoring"]) into generated code and a unified diff, grounded on the plan plus the real source it references.
  - [get_dependency_path](https://docs.repowise.dev/mcp/get-dependency-path): Shortest dependency path between two files or modules, plus visual context (common ancestors, shared neighbors, bridge suggestions) when no direct path exists. Opt-in, off by default.
  - [get_execution_flows](https://docs.repowise.dev/mcp/get-execution-flows): Top entry points and their call traces, showing how the codebase actually executes end to end. Opt-in, off by default.
  - [set_finding_status](https://docs.repowise.dev/mcp/set-finding-status): Record a durable disposition on one refactoring plan, so a finding you have already judged is never re-proposed at you. The write half of findings triage. Opt-in, off by default.
- Glossary & Benchmarks
  - [Computed glossary](https://docs.repowise.dev/reference/glossary): Every term repowise computes across traversal, graph, git, analysis, generation, workspace, persistence, and MCP. The vocabulary map for wiki pages, graph records, risk signals, contracts, and tool responses.
  - [Benchmarks](https://docs.repowise.dev/reference/benchmarks): Where the measured numbers live, what they cover, and why this page is a pointer rather than a copy of them.

- Installation
  - [Requirements](https://docs.repowise.dev/installation/requirements): System and toolchain requirements for self-hosted repowise, covering Python, Git, disk, and an LLM provider key.
  - [Install repowise](https://docs.repowise.dev/installation/install): Install the repowise CLI on macOS, Linux, or Windows via pip or uv. Verify, upgrade, switch versions, or uninstall. Every step.
  - [Configuration: config.yaml & ignore files](https://docs.repowise.dev/installation/configuration): The .repowise/ directory, the config.yaml file repowise generates on first init, and how to control which files get indexed with .gitignore, nested .gitignore, .repowiseIgnore, and --exclude.
  - [Environment variables](https://docs.repowise.dev/installation/env-vars): Provider API keys, embedder overrides, and runtime knobs that configure repowise's behavior at install and index time.
  - [Language support](https://docs.repowise.dev/installation/languages): 26 languages parsed to a full AST and 40 on the five-rung ladder, with per-language framework awareness for Django, FastAPI, Spring Boot, Rails, Laravel, Godot and more.
  - [Troubleshooting](https://docs.repowise.dev/installation/troubleshooting): Diagnose a broken index with repowise doctor, plus the most common install and indexing problems with their fixes.
- [Local dashboard](https://docs.repowise.dev/dashboard): The self-hosted web dashboard that reads your .repowise index and answers architecture, health, ownership and history questions without sending anything off your machine.
- [Upgrading](https://docs.repowise.dev/upgrading): Upgrade the repowise package, run repowise update, and your existing index keeps working. No reindex in the normal case; a full reindex is only ever recommended, never forced.

- Hosted platform
  - [Hosted platform](https://docs.repowise.dev/hosted/overview): Everything the managed platform adds on top of the OSS engine: zero-ops indexing, push-sync, AI docs and chat, the security suite, team portfolio intelligence, and alerting, with a plan ladder from free to enterprise.
  - [Hosted vs self-hosted](https://docs.repowise.dev/hosted/vs-self-hosted): Both modes ship the same intelligence layers, the same MCP tools, and the same dashboard. The differences are about ops, billing, and team features, not about what the agent can do.
  - [Dashboard tour](https://docs.repowise.dev/hosted/dashboard): What lives behind sign-in at repowise.dev/dashboard: the hosted control plane for your indexed repos, workspaces, MCP keys, billing, and team.
  - [PR review bot](https://docs.repowise.dev/hosted/bot): A GitHub App that posts one useful comment per pull request: a before-you-merge checklist, a change-map diagram, code-health deltas, hotspots, hidden coupling, dead code, change risk, and an optional merge gate. Signals mode uses no model and is free for OSS; AI review is part of Pro.
  - [Connecting your IDE](https://docs.repowise.dev/hosted/connecting-ide): Mint an API key on the hosted dashboard and paste a snippet. One URL per indexed repo, plus one per workspace that answers across its member repos. Claude Code, Claude Web/Desktop, Cursor, VS Code, and Windsurf supported.
  - [Security suite](https://docs.repowise.dev/hosted/security): CVE-aware dependency scanning with usage and reachability triage, secret detection across full git history, SBOM/VEX export, a nightly CVE refresh, compliance reports, and an insert-only audit trail.
  - [Security and data handling](https://docs.repowise.dev/hosted/data-handling): For a security reviewer evaluating Hosted at repowise.dev. What happens to your source code, what is kept after indexing, when a model sees your code, who can read it, and how data is deleted.
  - [Teams & portfolio intelligence](https://docs.repowise.dev/hosted/teams): Seats with pooled repos and credits, shared workspaces, portfolio health and ownership rollups, and an engineering-leader dashboard fed by nightly drift detection.
  - [Alerts & notifications](https://docs.repowise.dev/hosted/alerts): HMAC-signed Slack-compatible webhooks, the in-product notification bell, and per-kind email preferences, for security events and engineering signals, designed to never spam.
  - [Jira and Confluence](https://docs.repowise.dev/hosted/integrations): Connect an Atlassian site to link architectural decisions to the Jira tickets that motivated them, and publish your generated wiki to Confluence on a weekly schedule, updated in place and never duplicated.
- [Enterprise](https://docs.repowise.dev/enterprise): For companies that need Repowise on their own infrastructure or under commercial terms. What the commercial licence adds, what is available today, and how on-premise deployment works.
- [Security & data handling](https://docs.repowise.dev/security): What Repowise processes, what it persists, what leaves your machine under each deployment mode, and how to reduce that to zero.
- [Licensing](https://docs.repowise.dev/licensing): Repowise is AGPL-3.0. What that allows, when a company needs a commercial licence, what the commercial licence covers, and what the hosted service runs under.
- [Roadmap](https://docs.repowise.dev/roadmap): What we are building next, what we have decided not to build, and why there are no dates on this page.

- [Contributing](https://docs.repowise.dev/contributing): How to build and test the open-source Repowise repository, find something to work on, claim an issue, and open a pull request.

## Optional

- [Full docs content dump](https://docs.repowise.dev/llms-full.txt)
- [Site-wide index](https://repowise.dev/llms.txt): Features, comparisons, guides, and blog