# What is repowise

repowise indexes your codebase into five intelligence layers (graph, git, wiki, decisions, code health) and serves them to AI agents through MCP tools.

Repowise is a codebase intelligence engine. Point it at a git
repository and it produces a single artifact, a SQLite + vector
store under `.repowise/`, that AI agents and humans can both query.

The artifact captures five layers of context that no static analyzer
or LLM-only tool gives you on its own.

> **Note**
>
> **You do not need an API key to try it.** `repowise init --yes` builds all
> five layers and renders a complete wiki from your code's structure, with
> no model, no key, and no network. Adding a provider later upgrades the
> wiki to model-written prose in place. See
> [Deterministic wiki](https://docs.repowise.dev/intelligence/deterministic-wiki).

## The five intelligence layers

### 1. Static structure

Every file, symbol, and import edge, parsed by language-aware
resolvers across 28 languages (42 on the
[support ladder](https://docs.repowise.dev/installation/languages)): Python, TypeScript,
JavaScript, Svelte, Vue, Astro, Java, Kotlin, Go, Rust, C++, C#, Scala,
Ruby, Apex (Salesforce) at the **Full** tier; C, Swift, PHP, Dart, Object Pascal, COBOL,
GDScript, VB.NET, Elixir, F#, Objective-C at **Good**; SQL via a
dedicated sqlglot handler; plus config and data formats (OpenAPI,
Protobuf, GraphQL, Dockerfile, Terraform, etc.).

The dependency graph has two tiers (file nodes + symbol nodes) and
stamps every call edge with a resolution origin from a closed
39-value vocabulary, each pinned to one confidence, to handle
import aliases, barrel re-exports, namespace imports, and framework
conventions (Django, FastAPI, Spring, Express, NestJS, Rails, Laravel,
Axum, Actix). Plus heritage extraction (extends, implements, trait
impls, derive macros, mixins, extension conformance) and Leiden
community detection that finds logical modules even when your
directory structure doesn't reflect them.

### 2. Git history

The newest 5,000 commits of history (configurable up to 10,000) turned
into behavioural signals static analysis can't produce:

- **Hotspot files.** High churn × high complexity, where bugs live.
- **Ownership.** `git blame` aggregated into per-engineer percentages.
- **Bus factor.** How many people could leave before a file becomes
  unowned.
- **Co-change pairs.** Files that change together without an import
  edge between them. Hidden coupling that AST analysis cannot detect.
- **Significant commits.** Meaningful messages (filtered of merges,
  dependency bumps, lint runs) that explain *why* code evolved.

### 3. Auto-generated wiki

A Markdown page for every module and every notable file. The pages cite
source ranges, get a confidence score, are incrementally regenerated on
every commit (typical update: 3 to 10 pages in under 30 seconds), and feed
semantic search through a LanceDB vector store.

Repowise builds this two ways. **Model-written** pages are the richer
version: the prompt the LLM sees isn't only source, it includes parsed
structure, top callers/callees, the most significant commit messages,
ownership, and trend signals. That's the recipe for docs that explain
*why*, not just *what*.

**Deterministic** pages are rendered from the AST, the graph, and git with
no model at all. That is what you get with no API key configured, and it
covers the same page set: file, symbol, layer, cycle, overview,
architecture, API, infra, and onboarding. It cannot tell you why retries
were made idempotent, which is precisely what the model pass adds. See
[Deterministic wiki](https://docs.repowise.dev/intelligence/deterministic-wiki).

### 4. Architectural decisions

The layer nobody else has. Repowise treats decisions as first-class
data: captured by hand (`repowise decision add`), mined from git
history (auto-proposed), or extracted from inline markers in source:

```python
# WHY: JWT chosen over sessions; API must be stateless for k8s scaling
# DECISION: All external API calls wrapped in CircuitBreaker after Q3 outages
# TRADEOFF: Accepted eventual consistency in preferences for write throughput
```

Decisions are linked to the graph nodes they govern, tracked for
staleness as code evolves, and surfaced via
[`get_why`](https://docs.repowise.dev/mcp/get-why) the moment your agent touches a
governed file.

### 5. Code health

A 1 to 10 score for every file from **deterministic markers across three
signals** (defect risk, maintainability, and performance) covering
complexity, cohesion (LCOM4), duplication, untested hotspots,
git-behavioural risk (ownership, churn, co-change scatter), and static
performance risk (N+1 / I/O-in-loop shapes). Linters check patterns. This
score predicts which files are likely to harbor the next bug: the
defect-risk weights are **calibrated against a real defect corpus**, and the
score is validated to out-rank the leading commercial code-health tool at
predicting which files get bug-fixes. Zero LLM calls, under 30 seconds on a
3,000-file repo. See [Code health](https://docs.repowise.dev/intelligence/code-health).

### Change evidence

On top of the five layers, every merged change is read back from git as a
**Change Record** with an evidence checklist: components touched, declared
owners, reaching tests, contracts, decisions crossed, AI provenance with
coverage, and later outcomes such as reverts. `repowise check` evaluates a
local change policy against a change, `repowise report` writes assessment,
change evidence and inventory packs, and `repowise suspects` ranks recent
changes against a symptom. See
[Change evidence](https://docs.repowise.dev/cli/changes) and
[Components](https://docs.repowise.dev/cli/components).

## The agent surface

Your editor's AI agent talks to all of this through
[MCP tools](https://docs.repowise.dev/mcp/overview). They're **task-shaped**, not
entity-shaped: pass multiple targets in one call, get complete
context back in one round-trip.

| Tool | What it answers |
|---|---|
| [`get_overview`](https://docs.repowise.dev/mcp/get-overview) | Summary, key modules, entry points, layers, code health, top actions |
| [`get_answer`](https://docs.repowise.dev/mcp/get-answer) | One-call RAG: cited 2 to 5 sentence answers |
| [`get_context`](https://docs.repowise.dev/mcp/get-context) | Docs, ownership, callers/callees, metrics for any targets |
| [`get_symbol`](https://docs.repowise.dev/mcp/get-symbol) | Raw source bytes for one symbol with exact line bounds |
| [`search_codebase`](https://docs.repowise.dev/mcp/search-codebase) | Semantic search over the wiki |
| [`get_risk`](https://docs.repowise.dev/mcp/get-risk) | Hotspot, dependents, co-changes, blast radius |
| [`get_change_risk`](https://docs.repowise.dev/mcp/get-change-risk) | Size percentile, bug-fix record and evidence for a commit or diff range |
| [`get_why`](https://docs.repowise.dev/mcp/get-why) | Architectural decisions with archaeology fallback |
| [`get_dead_code`](https://docs.repowise.dev/mcp/get-dead-code) | Tiered cleanup plan with confidence scoring |
| [`get_health`](https://docs.repowise.dev/mcp/get-health) | Three-signal health scores: KPIs + worst files, self-check before a PR |

A few calls replace a long run of reads and greps. Measured across 43
questions on `django/django`, an agent with these tools writes **31.6% fewer
output tokens** and gets there in **3.8 tool calls against a bare agent's 7.2**
(*p < 0.0001*). Method and raw cells:
[repowise.dev/benchmarks](https://repowise.dev/benchmarks).

No dollar figure is quoted here, deliberately. Cost per run is dominated by
prompt-cache state, which depends on the order the arms ran in rather than on
the tools, so output tokens are what we publish.

## Why your agent needs this

LLMs are good at reading the file in front of them and bad at
reasoning across the rest of the codebase. They:

- Guess at module boundaries.
- Miss callers and dependents.
- Hallucinate function signatures from neighbouring repos.
- Have no idea why the previous engineer chose the design they did.

Without context, the agent does what a junior engineer does on day
one: reads files, asks lots of questions, and ships changes that
break unrelated parts of the system.

Repowise gives the agent the institutional knowledge a senior
engineer would have. Hotspot warnings before edits. Co-change
partners surfaced automatically. Architectural decisions linked to
governed files. Ownership and bus-factor visible in every response.

The agent stops guessing.

## Who it's for

- **AI-first engineering teams** who use Claude Code, Cursor, or
  Windsurf as their primary IDE.
- **Teams onboarding into unfamiliar codebases.** A new hire's
  first two weeks become two days when their agent already knows the
  hotspots, owners, and decisions.
- **Open-source maintainers** who want their contributors' agents to
  have full context without writing it all into `CONTRIBUTING.md`.
- **Anyone tired of watching their agent `cat` the same file four
  times.**

Evaluating repowise for a company? Change Records, policy checks and
evidence reports run on the same local index; see
[Enterprise](https://docs.repowise.dev/enterprise) for on-premise deployment and commercial
terms.

## Self-hosted or hosted

Both modes ship the same intelligence: same parsers, same git
analysis, same wiki generation, same MCP tools. Pick whichever fits.

| | Self-hosted | Hosted ([repowise.dev](https://repowise.dev)) |
|---|---|---|
| Install | `pip install repowise` | None, just sign in with GitHub |
| Storage | Local `.repowise/` (SQLite + LanceDB) | Managed by Repowise |
| Auto-sync | Hooks, watch, your own webhook server | GitHub App push-sync (automatic) |
| MCP server | Local stdio process | Hosted HTTP endpoint |
| Multi-repo workspaces | Yes | Yes |
| Cross-repo intelligence | Yes (per workspace, over MCP and the dashboard) | Yes (per workspace, in the dashboard's federated chat) |
| Web UI | `repowise serve` -> `localhost:3000` | [repowise.dev/dashboard](https://repowise.dev/dashboard) |
| Privacy | Code never leaves your machine | Encrypted; LLM calls run on the platform, paid from credits |
| Cost | Free, AGPL-3.0 | Free tier + Pro |

See [Hosted vs self-hosted](https://docs.repowise.dev/hosted/vs-self-hosted) for the full
side-by-side. Or just jump to [Quickstart](https://docs.repowise.dev/getting-started/quickstart)
and try one; switching later is painless because both speak the same
MCP protocol.

> **Note**
>
> **Hybrid is fine.** Run self-hosted on a laptop for one private repo
> and hosted for everything else. Your agent talks to either through
> the same protocol; it doesn't care which server answers.

## What's next

- [**Quickstart**](https://docs.repowise.dev/getting-started/quickstart): install + index
  + connect Claude Code in under a minute.
- [**How it works**](https://docs.repowise.dev/getting-started/how-it-works): the
  end-to-end flow from `repowise init` to a connected agent.
- [**MCP tools overview**](https://docs.repowise.dev/mcp/overview): what your agent can
  actually ask for.