# 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.

Evaluating Repowise for a company? Read https://docs.repowise.dev/security.md, https://docs.repowise.dev/hosted/data-handling.md, https://docs.repowise.dev/licensing.md, https://docs.repowise.dev/enterprise.md and https://repowise.dev/pricing.md.

Every link below is the page's Markdown. Drop the `.md` for the HTML page.

- [Welcome to repowise](https://docs.repowise.dev/index.md): repowise indexes your repository into five intelligence layers and serves them to your AI coding agent through MCP tools, so it reads answers, not code.
- Getting Started
  - [What is repowise](https://docs.repowise.dev/getting-started/what-is-repowise.md): repowise indexes your codebase into five intelligence layers (graph, git, wiki, decisions, code health) and serves them to AI agents through MCP tools.
  - [Agent setup runbook](https://docs.repowise.dev/getting-started/setup.md): The step-by-step runbook a coding agent follows to install repowise, index the current repository, connect the MCP tools and report back, readable by anyone.
  - [How it works](https://docs.repowise.dev/getting-started/how-it-works.md): How repowise builds its index in five passes (dependency graph, git history, wiki, decision records and code health) and how the MCP tools query the result.
  - [Quickstart](https://docs.repowise.dev/getting-started/quickstart.md): Install repowise, index your repo with no API key, open the dashboard and connect your agent. Self-hosted, hosted (repowise.dev), or a multi-repo workspace.
  - [Set up with your agent](https://docs.repowise.dev/getting-started/for-agents.md): 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 one question.
  - [Agent plugins](https://docs.repowise.dev/getting-started/plugins.md): The Claude Code and Codex plugins bundle the repowise MCP server, lifecycle hooks, skills and slash commands into one install. See what each ships.
  - [VS Code extension](https://docs.repowise.dev/getting-started/vscode.md): The repowise VS Code extension brings your local index into the editor with health signals, refactoring CodeLens and branch risk, and adds the MCP server.

- [Auto-sync](https://docs.repowise.dev/auto-sync.md): Six ways to keep your repowise index current: a post-commit hook, a file watcher, GitHub, GitLab and Gitea or Forgejo webhooks, and a polling safety net.
- [Git worktrees](https://docs.repowise.dev/worktrees.md): 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.md): Gate pull requests in CI on patch coverage, new doc drift, new security findings, new code-health findings and change risk, enforce a change policy, and run only the tests needed.

- Intelligence layers
  - [Dependency graph](https://docs.repowise.dev/intelligence/dependency-graph.md): 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.md): 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.md): Which files and functions have been bug-fixed, how often and how recently, from git alone, with a fix-shape classifier validated at 98.3% on 240 commits.
  - [Change risk](https://docs.repowise.dev/intelligence/change-risk.md): Change risk ranks a commit or base..head range by diff size and spread against your repo's recent commits, next to the touched files' bug-fix record.
  - [Change review API](https://docs.repowise.dev/intelligence/change-review.md): The repowise Python API that composes one change review from existing primitives, runs without a git checkout, and serializes to a dict for bots and CI.
  - [Change Records](https://docs.repowise.dev/intelligence/change-records.md): Every merged change rebuilt from git as one Change Record, with an evidence checklist, later outcomes, an in-toto export and ranked suspects for a symptom.
  - [Change policy](https://docs.repowise.dev/intelligence/change-policy.md): Rules in .repowise/policies.yaml hold critical changes to a higher bar, checked by repowise check against each change's evidence, with SARIF or JUnit output.
  - [Evidence reports](https://docs.repowise.dev/intelligence/evidence-reports.md): repowise report writes an assessment, a change evidence pack and a component inventory from the local index, with every item stating its method and basis.
  - [Components and ownership](https://docs.repowise.dev/intelligence/components.md): A Backstage-shaped component catalog that health, hotspots, bus factor and tests roll up to, with declared owners checked against recent activity.
  - [AI attribution](https://docs.repowise.dev/intelligence/ai-attribution.md): Which commits a coding agent wrote, read from markers your repository already carries, as three-state provenance with coverage and opt-in edit capture.
  - [Auto-generated wiki](https://docs.repowise.dev/intelligence/auto-wiki.md): How repowise writes a documentation page for every module: incrementally, with citations and confidence scoring, refreshed in under 30 seconds per commit.
  - [Deterministic wiki](https://docs.repowise.dev/intelligence/deterministic-wiki.md): The wiki repowise renders entirely from your code's structure, with no API key and no spend. A model only adds prose to the subsystem pages on top of it.
  - [Package pages and Public API](https://docs.repowise.dev/intelligence/package-pages.md): In a monorepo, a package spanning several subsystems gets one documentation page, written from its computed Public API, the names a consumer can import.
  - [Architecture diagrams](https://docs.repowise.dev/intelligence/architecture-diagrams.md): The architecture map, C4 context, container and component views, and a Structurizr DSL export, all built by repowise from the dependency graph, no model.
  - [Architectural decisions](https://docs.repowise.dev/intelligence/decisions.md): Architectural decision records linked to the files they govern, captured by hand, mined from git history or inline markers, and served to agents via get_why.
  - [Code health](https://docs.repowise.dev/intelligence/code-health.md): A 1 to 10 health score for every file across defect risk, maintainability and performance, from deterministic markers with defect-calibrated weights.
  - [Documentation drift](https://docs.repowise.dev/intelligence/doc-drift.md): repowise checks the paths, links, headings, commands and symbol names in your markdown against the real tree and reports any that no longer exist.
  - [Test intelligence](https://docs.repowise.dev/intelligence/test-intelligence.md): 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.md): 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.md): A deterministic pattern registry in repowise core that flags dangerous calls and committed credentials, with a history mode and line verification.
  - [Findings and triage](https://docs.repowise.dev/intelligence/findings.md): What a finding is, the finding families repowise produces, which finding types each surface shows, and how a status you set persists across re-analysis.
  - [Refactoring intelligence](https://docs.repowise.dev/intelligence/refactoring.md): Refactoring intelligence names the specific fix: six deterministic detectors emit one graph-aware plan per opportunity, ranked by impact and effort.
  - [Proactive agent hooks](https://docs.repowise.dev/intelligence/hooks.md): Proactive agent hooks push graph, git, health and decision context into Claude Code and Codex the moment the agent needs it. No LLM, no network.
- Multi-repo
  - [Workspace setup](https://docs.repowise.dev/multi-repo/workspace-setup.md): Index related git repos as one repowise workspace for cross-repo co-changes, API contract matching and federated MCP queries on top of per-repo intelligence.
  - [Cross-repo intelligence](https://docs.repowise.dev/multi-repo/cross-repo.md): What repowise learns by analyzing several repos together: co-change pairs, HTTP, gRPC and topic API contracts, and package dependencies across repos.
  - [System graph & map](https://docs.repowise.dev/multi-repo/system-map.md): The service-level system graph repowise folds cross-repo signals into, the System Map that renders it, and diagnostics explaining why a contract link formed.
  - [Cross-repo blast radius](https://docs.repowise.dev/multi-repo/blast-radius.md): Cross-repo blast radius walks the system graph against its edges to show which downstream services and repos a change can break, ranked by impact score.
  - [Breaking-change guard](https://docs.repowise.dev/multi-repo/breaking-changes.md): The breaking-change guard diffs freshly extracted contracts on every workspace update and reports each incompatible change with the consumer files it hits.
  - [Architecture conformance](https://docs.repowise.dev/multi-repo/conformance.md): Declare which services may depend on which others and check the live system graph against those rules on every update. Architecture lint with cycle detection.
  - [Architecture metrics](https://docs.repowise.dev/multi-repo/architecture-metrics.md): Propagation cost, the cyclic core, per-service roles and a deterministic 1-10 architecture score, computed over the system graph with standard metrics.
  - [Workspace MCP mode](https://docs.repowise.dev/multi-repo/workspace-mcp.md): Self-hosted workspace MCP mode routes targets to the repo that owns them, fans out across repos on four tools, and adds three workspace-only cross-repo tools.

- CLI reference
  - [CLI overview](https://docs.repowise.dev/cli/overview.md): Every repowise CLI command at a glance, from init, update and serve to search, health, risk, distill and decision, with a link to each command's full guide.
  - [Indexing: init, update, reindex](https://docs.repowise.dev/cli/indexing.md): repowise init builds the intelligence layers from scratch, update keeps them current on each commit, and reindex rebuilds the vector store with no LLM.
  - [Server & watch: serve, watch, mcp](https://docs.repowise.dev/cli/server.md): Run repowise serve for the API and local dashboard, repowise watch to auto-update on file save, or repowise mcp to expose the MCP server to your editor.
  - [Query: search, ask, context, symbol, why, status](https://docs.repowise.dev/cli/query.md): Search the docs, ask cited questions, read triage cards and symbols, trace why code exists, and check sync state from the terminal with repowise search.
  - [Distill: compact command output](https://docs.repowise.dev/cli/distill.md): repowise distill renders noisy command output errors-first and fully reversible, saving 61 to 89% of tokens in measured runs on tests, git log and git diff.
  - [Code health: health, risk](https://docs.repowise.dev/cli/health.md): repowise health scores every file on defect risk, maintainability and performance; repowise risk ranks a commit or diff range against recent commits.
  - [Coverage and CI gates: coverage, impacted-tests, doc-drift, security check, health check](https://docs.repowise.dev/cli/gates.md): Flags for ingesting coverage, gating a change on patch coverage, selecting the tests a change needs, and the doc-drift, security and health gates.
  - [Change evidence: changes, check, suspects, report, events](https://docs.repowise.dev/cli/changes.md): Change Records rebuilt from git with an evidence checklist, plus repowise check for change policy, suspects for a symptom, evidence reports and events.
  - [Components, packages and attribution](https://docs.repowise.dev/cli/components.md): Declare Backstage-shaped components with owners checked against recent activity, export package usage as CycloneDX, and read three-state AI attribution.
  - [Workspace: multi-repo commands](https://docs.repowise.dev/cli/workspace.md): Manage repos in a repowise workspace: list, add, remove, scan, set the default, explain contract links, lint architecture rules and read architecture metrics.
  - [Decisions: capture, review, govern](https://docs.repowise.dev/cli/decision.md): Record architectural decisions so the why survives the team. Review the candidates capture proposed, accept the ones that should govern, and keep them in git.
  - [Hooks: auto-sync on commit](https://docs.repowise.dev/cli/hook.md): Install, check and remove the post-commit git hook that runs repowise update after every commit, and see hook stats on what your agent hooks fired.
  - [Agents: add, remove, refresh](https://docs.repowise.dev/cli/agents.md): Wire repowise into Claude Code, Codex, Cursor, VS Code, OpenCode, Hermes, GitHub Copilot CLI or Kiro, or drop the config snippet for anything else.
  - [Uninstall: remove repowise](https://docs.repowise.dev/cli/uninstall.md): Remove repowise from this repo, and optionally from this machine, with a full inventory of every path it wrote and a report of what was removed and kept.
  - [Other commands](https://docs.repowise.dev/cli/other.md): One-shot repowise utilities including costs, next, overlap, dead-code, security scan, doctor, whats-new, export, telemetry, login, publish and delete.
- MCP tools: The small, curated set of MCP tools repowise exposes to AI agents.
  - [MCP tools: overview](https://docs.repowise.dev/mcp/overview.md): The curated set of task-shaped MCP tools repowise exposes to Claude Code and any MCP agent, batched to collapse long tool-call chains into one round-trip.
  - [get_overview](https://docs.repowise.dev/mcp/get-overview.md): get_overview orients an agent in an unfamiliar repo: summary, key modules, entry points, layers, commands, code health, the riskiest files and this week's top actions.
  - [get_answer](https://docs.repowise.dev/mcp/get-answer.md): get_answer is one-call RAG over the wiki: it retrieves, gates on confidence and returns a cited answer with fallback targets. Call it first on code questions.
  - [get_context](https://docs.repowise.dev/mcp/get-context.md): The workhorse MCP tool. get_context returns batched context for files, modules or symbols: docs, ownership, freshness, plus optional callers and metrics.
  - [get_symbol](https://docs.repowise.dev/mcp/get-symbol.md): get_symbol returns the raw source of one indexed symbol with exact line bounds, cheaper than reading the whole file. The one MCP tool that returns source.
  - [search_codebase](https://docs.repowise.dev/mcp/search-codebase.md): search_codebase is hybrid code search over repowise's indexes, routing each query to symbols, file paths or the wiki by its shape, so agents skip Grep.
  - [get_risk](https://docs.repowise.dev/mcp/get-risk.md): get_risk assesses modification risk before an edit: hotspots, dependents, co-change partners, blast radius, suggested reviewers, test gaps and security.
  - [get_change_risk](https://docs.repowise.dev/mcp/get-change-risk.md): Review a commit, range or uncommitted work with get_change_risk: what the change made worse, tests on the changed lines, and fix history of touched files.
  - [get_why](https://docs.repowise.dev/mcp/get-why.md): get_why answers why code is shaped this way. Search decisions in plain language, anchor them to a file, or read decision health, with git history as fallback.
  - [get_dead_code](https://docs.repowise.dev/mcp/get-dead-code.md): get_dead_code returns a tiered plan for unused code with high, medium and low confidence findings, directory rollups and safe-to-delete estimates. No LLM.
  - [get_health](https://docs.repowise.dev/mcp/get-health.md): get_health gives your agent per-file code-health scores and findings across defect risk, maintainability and performance, to self-check a change before a PR.
  - [list_repos](https://docs.repowise.dev/mcp/list-repos.md): 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.md): generate_refactoring_code turns one refactoring plan from get_health into generated code and a unified diff, grounded on the plan and its real source.
  - [get_dependency_path](https://docs.repowise.dev/mcp/get-dependency-path.md): get_dependency_path finds the shortest dependency path between two files or modules, with common ancestors and bridge suggestions when none exists. Opt-in.
  - [get_execution_flows](https://docs.repowise.dev/mcp/get-execution-flows.md): get_execution_flows scores the top entry points and traces each call graph breadth-first, showing how the codebase executes end to end. Opt-in tool.
  - [set_finding_status](https://docs.repowise.dev/mcp/set-finding-status.md): set_finding_status records a durable disposition on one refactoring plan, so a finding you already judged is never re-proposed. The write half of triage.
- Glossary & Benchmarks
  - [Computed glossary](https://docs.repowise.dev/reference/glossary.md): Every term repowise computes across graph, git, analysis, change evidence, generation, workspace and MCP, mapped to wiki pages, signals and tool responses.
  - [Benchmarks](https://docs.repowise.dev/reference/benchmarks.md): The headline measurements with their samples, the scale table with lines of code, the rows we lose, and where the full methodology and raw runs live.
- [Build on Repowise](https://docs.repowise.dev/build-on-repowise.md): The surfaces a tool, service or agent can build on, how each one authenticates, and which contracts are versioned and stable across releases.

- Installation
  - [Requirements](https://docs.repowise.dev/installation/requirements.md): System and toolchain requirements for self-hosted repowise, covering Python, Git, disk and memory, measured scale on large repos, and the optional LLM key.
  - [Install repowise](https://docs.repowise.dev/installation/install.md): 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.md): The .repowise/ directory, the config.yaml written on first init, the policy and component files you own, and how .gitignore and --exclude pick files.
  - [Environment variables](https://docs.repowise.dev/installation/env-vars.md): Provider API keys, the provider and base URL resolution order, embedder overrides, server authentication, plugins, and runtime knobs that configure repowise.
  - [Language support](https://docs.repowise.dev/installation/languages.md): 28 languages parsed to a full AST and 42 on the five-rung ladder, with framework awareness for Django, Spring Boot, Rails, Salesforce and more.
  - [Troubleshooting](https://docs.repowise.dev/installation/troubleshooting.md): Diagnose a broken index with repowise doctor, then fix common problems such as command not found, indexing hangs, missing MCP tools and store drift.
- [Local dashboard](https://docs.repowise.dev/dashboard.md): The self-hosted repowise dashboard reads your local index to answer architecture, health, ownership and history questions, with nothing leaving your machine.
- [Upgrading](https://docs.repowise.dev/upgrading.md): Upgrade the repowise package, run repowise update, and your existing index keeps working. No reindex in the normal case, and a full reindex is never forced.

- [Enterprise](https://docs.repowise.dev/enterprise.md): repowise for platform, AppSec and architecture leads: change and component evidence computed inside your network, and what the commercial licence adds.
- Hosted platform
  - [Hosted platform](https://docs.repowise.dev/hosted/overview.md): What the managed platform adds to the OSS engine: zero-ops indexing, push-sync, AI docs and chat, a security suite, team portfolio intelligence and alerting.
  - [Hosted vs self-hosted](https://docs.repowise.dev/hosted/vs-self-hosted.md): Hosted and self-hosted repowise ship the same intelligence layers, MCP tools and dashboard. They differ in ops, billing and team features, not agent power.
  - [Dashboard tour](https://docs.repowise.dev/hosted/dashboard.md): What lives behind sign-in at repowise.dev/dashboard: the hosted control plane for your indexed repos, workspaces, MCP keys, billing, and team.
  - [PR bot](https://docs.repowise.dev/hosted/bot.md): A GitHub App that reviews each pull request with one short comment, a Repowise review check on every push, optional pass/fail checks and threads on the lines that need them. Signals mode is free for OSS.
  - [Review preferences](https://docs.repowise.dev/hosted/review-preferences.md): Tell the PR bot how to review your repository with /repowise remember. Preferences are scoped by path, apply repo-wide once the pull request merges, never hide P1 or security findings, and expire when the code they quoted changes.
  - [Extracting decisions with your agent](https://docs.repowise.dev/hosted/agent-decisions.md): Have your coding agent mine a repository's history and docs and propose architectural decisions to hosted Repowise over MCP, each with a verbatim quote and the commit that carries it.
  - [Connecting your IDE](https://docs.repowise.dev/hosted/connecting-ide.md): Connect Claude Code, Claude Desktop, Cursor, VS Code and Windsurf to the hosted MCP server, with one URL per indexed repo and one per workspace.
  - [Security suite](https://docs.repowise.dev/hosted/security.md): The hosted security suite: CVE-aware dependency scanning, reachability triage, secret detection across full git history, SBOM/VEX export and an audit trail.
  - [Hosted security and data handling](https://docs.repowise.dev/hosted/data-handling.md): A security reviewer's guide to Hosted at repowise.dev, covering what happens to your source code, what is kept, when a model sees it, and how data is deleted.
  - [Teams & portfolio intelligence](https://docs.repowise.dev/hosted/teams.md): Team seats with pooled repos and credits, shared workspaces, portfolio health and ownership rollups, and an engineering-leader dashboard fed by drift checks.
  - [Alerts & notifications](https://docs.repowise.dev/hosted/alerts.md): HMAC-signed Slack-compatible alert webhooks, an in-product notification bell and per-kind email preferences for security and engineering signals, no spam.
  - [Jira and Confluence](https://docs.repowise.dev/hosted/integrations.md): Connect an Atlassian site to link architectural decisions to the Jira tickets behind them and publish your generated wiki to Confluence on a weekly schedule.
  - [Foresight](https://docs.repowise.dev/hosted/foresight.md): Foresight ranks the files a fix will touch, names what a change forgot and lists the tests to update, with no LLM, CPU only. Coming to hosted and enterprise.
- [Security & data handling](https://docs.repowise.dev/security.md): 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.md): repowise is AGPL-3.0. What that allows, why internal use creates no obligation to publish your code, and when a company needs a commercial licence.
- [Roadmap](https://docs.repowise.dev/roadmap.md): What we are building next across languages, source control beyond git, multi-repo, integrations and core intelligence, plus what we have decided not to build.

- [Contributing](https://docs.repowise.dev/contributing.md): 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): Pricing, features, comparisons, guides, and blog