repowise

Your AI agent burns most of its budget rediscovering your codebase. Index it once, and it never has to again.

up to −96% tokens to load context  ·  −89% file reads  ·  −70% tool calls

Paired runs, same model, same harness, with and without repowise (the numbers, and what they do not show →). Free and self-hosted, runs on your machine, and the first index needs no API key.

Every question your agent asks about your repo has an answer that could have been computed ahead of time. Who calls this function? What breaks if I change it? Why is it written this way? Which of these files is actually dangerous? Instead, agents rediscover it from scratch on every task: grep, read, re-read, forget.

repowise computes those answers once and keeps them current on every commit. Your agent reads the answer instead of the codebase, and the same index gives your team a defect-validated health score, change-risk scoring on every PR, and a local dashboard for all of it. One pip install, no cloud, your code never leaves your machine.

Your agent stops guessing

repowise exposes ten task-shaped MCP tools to Claude Code, Codex, Cursor, VS Code and anything else that speaks MCP. Most tools are built around data entities (one file, one symbol), which forces agents into long chains of sequential calls. These are built around tasks: pass several targets in one call, get complete context back.

The same index those tools read from, browsable at localhost:3000. Recorded on this repository, no API key and nothing uploaded.

Because the exploration work is already done, that phase mostly disappears. Loading one commit's context through get_context costs 2,391 tokens instead of 64,039 raw. On a long multi-step investigation that compounds to −41% of the context re-read across the whole session.

And it arrives without being asked. Optional hooks push context into the session at the moment it matters: the governing architectural decision when your agent edits a file that decision covers, a warning when it touches a file with a run of recent bug fixes, a compact briefing at session start. repowise also generates your CLAUDE.md and AGENTS.md from the real index, so even an agent with no MCP support starts informed.

It learns from how you actually work. repowise reads your own agent transcripts for the corrections you keep making ("use the shared HTTP client, not raw requests") and turns the durable ones into tracked decisions it delivers back later. The wiki generation budget tilts toward the modules you and your agent ask about most. All local, all deterministic, no extra LLM calls.

Related MCP server: CodeGraph

What one index actually builds

Five layers, built in a single pass and kept in sync on every commit. Each one is queryable from the CLI, the MCP tools, and the local dashboard.

The whole wiki is generated with no LLM, then upgraded to model-written prose on demand. repowise init --no-prose builds the graph, git, decision and health layers and renders every wiki page from your code's structure, with no API key and no spend. Convert any part of it to LLM-written prose whenever you want, one page, one directory, or a ranked coverage slice at a time, and pay only for what you pick, from the CLI or right in the dashboard with the cost shown before you confirm. (Seven of the eight decision sources are deterministic too; only the one harvested during doc generation needs a provider.)

Full detail on every layer: docs/layers/INTELLIGENCE_LAYERS.md →

Stop paying for output nobody reads

Most of what an agent reads back from a shell command is noise: 300 lines of passing tests wrapped around 4 failures, full commit bodies when it asked "what changed recently". repowise distill <cmd> compresses command output before the agent reads it, errors first, exit code preserved.

repowise distill pytest          # 61% fewer tokens, all 11 failure lines kept
repowise distill git log -50     # 89% fewer tokens
repowise saved                   # what distillation saved you, in tokens and dollars

Nothing is lost. Every omission leaves an inline [repowise#<ref>] marker that repowise expand <ref> reverses in full, so the agent can always pull the detail back without re-running the command. Small outputs pass through untouched. An opt-in hook rewrites noisy commands automatically, shown to you for approval first.

Full guide: docs/agent/DISTILL.md →

Know what's dangerous before you merge

Three deterministic signals, all computed from the graph and git history, no LLM:

• Change risk. Score any commit or base..HEAD range 0-10 from the shape of the diff, ranked against your repo's own recent commits. PR mode returns directives rather than vibes: will_break, missing_cochanges, missing_tests, tests_to_run. One command: repowise risk main..HEAD. (reference →)

• Bug history. Which files and symbols actually get bug-fixed, and how recently. Doc, test and config commits are filtered out so the count means what it says, and a file with a run of recent fixes gets flagged as a bug magnet while you edit it. (reference →)

• Test intelligence. Ingest coverage, find untested hotspots, and run only the tests a diff actually exercises with repowise impacted-tests HEAD~1. (reference →)

Plus the free Repowise PR Bot, which puts all of it on every pull request. Zero LLM calls.

The PR bot

Install the GitHub App and the index shows up where the decision actually gets made. One comment per pull request, edited in place on every push rather than reposted, and a green PR gets no comment at all.

See a real comment on a real PR, not a mockup: repowise-dev/repowise#1204.

What decides a review is inline. What is context sits behind one fold, so the comment stays about seventeen rows whatever it finds.

• Blast radius, at symbol level. The contracts this PR changed and every caller of them in a file the PR does not touch. Importing a module says nothing about whether the function you changed is the one being called, so file-level impact is the wrong altitude for the question a reviewer actually has.

• Before you merge. The tests that import your changed files, and the files that changed alongside them in past commits but are missing here.

• A Check Run that can gate the merge, with annotations on the specific lines the PR added. Advisory by default.

• Change risk, scored against the repository's own commit distribution rather than an absolute scale, so it stays meaningful on a repo whose typical commit is large.

• AI vs human authorship of the changed files, with the average health of each.

• Then hotspots, hidden coupling, declining health, dead code and the change map, one fold down.

And a page the comment links to

Markdown runs out. The comment shows three callers and says "+6 more"; the page shows all nine. Public, no sign-in, on a repository the reader has never seen.

Every file in the repo, grouped by directory and sized by lines. The frame below zooms to where the change landed. See it live →

Install the PR bot → · how it works →

★ Know exactly what to fix

A score that says "this file is risky" is where most tools stop. repowise scores every file, locates where the risk concentrates, and then names the specific fix.

Every file is scored 1-10 from 25 deterministic markers (McCabe complexity, brain methods, LCOM4 cohesion, god classes, native Rabin-Karp clone detection, untested hotspots, change entropy, prior-defect history and more), split into three lenses: defect risk, maintainability, and performance (static N+1 and I/O-in-loop risk traced across files through the call graph, where file-local linters found 0 of the cross-function cases repowise surfaced 557 of).

Zero LLM calls, zero cloud, zero new runtime dependencies. Pure Python over tree-sitter and git data, under 30 seconds on a 3,000-file repo, with marker weights calibrated against a real defect corpus, not hand-tuned.

It proves itself on your repo, not just on a benchmark. After every index, repowise checks its own flags against your git history and reports what it found: "17 of the 20 lowest-health files had a bug fix in the last 6 months, 3.6x the 23% baseline." If that number is bad on your codebase, you will see it.

Then it names the fix. Not "this class is too big", but Extract Class, Extract Helper, Move Method, Break Cycle, Split File, or Extract Method, with the exact methods, edges and symbols that move, the blast radius of callers and co-changing files that have to move with them, and a graph-aware ranking so a fix on a central hub outranks the same fix on a leaf. Extract Method goes down to an intra-procedural dataflow pass that lifts the exact span and infers a behavior-preserving signature.

repowise health                        # KPIs and lowest-scoring files
repowise health --refactoring-targets  # ranked, concrete plans
repowise health --trend                # snapshots plus declining-health alerts

The dashboard renders each plan as a card with a copy-to-agent button. An optional LLM step, never in the indexing path and only on request, expands any plan into generated code and a unified diff.

Validated on 21 open-source repos across 9 languages (2,826 files, scored at a fixed point and checked against the following 6 months of bug fixes, keyword-labelled): ROC AUC 0.737 [0.683, 0.787]. The signal is correlated with file size and weakens sharply within a fixed size band, which we report rather than bury. Independently recomputed from the raw data.

Against CodeScene, the leading commercial code-health tool, on the same 2,770 files and the same defect labels, ranking by repowise health surfaces 2.3x the defects under a fixed review budget (paired, p = 0.003). Full head-to-head, methodology and limitations →

Guides: code health · refactoring

See all of it

repowise serve starts the full web dashboard next to the MCP server. No separate setup, all local.

Also in there: Chat (ask the codebase in natural language) · Docs (the generated wiki, with Mermaid and a graph sidebar) · Architecture and C4 (Context → Containers → Components) · Knowledge Graph plus a zoomable canvas map · Risk, Hotspots, Coupling and Blast radius · Contributors · Decisions (evidence drawer and evolution timeline) · Symbols · Security · Dead code · Stats · Costs · Workspace.

Every view and what each one answers: docs/start/DASHBOARD.md →

Past one repo

Real systems are not one repository, and the interesting failures live in the gaps between them.

• Workspaces. Index many repos as one unit and get what only a cross-repo view can show: contracts matched between a producer and its consumers, so a breaking API change is caught before it ships, plus cross-repo co-change pairs, federated MCP that answers across the whole estate, and conformance checks. (docs/scale/WORKSPACES.md →)

• Worktrees just work. Run repowise init or repowise update inside a linked git worktree and it detects the base checkout, seeds that worktree's index from it, and catches up incrementally. No flags, no second full index. (docs/scale/WORKTREES.md →)

• Auto-sync. Keep the index current with a post-commit hook, a file watcher (repowise watch), a webhook, or polling. An incremental update takes seconds. (docs/scale/AUTO_SYNC.md →)

In your editor

The Repowise VS Code extension puts the index where code actually gets written: know what your change breaks before you push (riskiest files ranked, what is downstream, forgotten companion files, missing tests, suggested reviewers), health in the gutter and status bar, callers and ownership on hover, refactoring plans as CodeLens, and the full dashboards inside the editor. One install also registers the MCP server with VS Code, so the same local index serves both you and your agent, and exposes six tools to GitHub Copilot. Quiet by default, everything toggleable, nothing leaves your machine.

Install from the Marketplace (search Repowise) or Open VSX, then run Repowise: Set Up This Repository. Guide: docs/agent/VSCODE.md →

Supported languages

16 languages parsed to AST · 11 at the Full tier · framework-aware across all of them.

SQL and dbt projects get real ref() / source() lineage, shell scripts get function-level symbols, and OpenAPI, Protobuf, GraphQL, Dockerfile, Terraform and friends get dedicated handlers. Anything else is still tracked through git history: blame, hotspots, co-change.

Adding a language takes one .scm query file and one config entry, with no changes to the parser core. Full matrix and the contributor recipe: docs/layers/LANGUAGE_SUPPORT.md →

Quickstart (under 5 minutes, no API key)

1. Install

pip install repowise          # Windows: python -m pip install repowise
repowise --version

2. Index your repo

cd /path/to/your/repo
repowise init

Bare init asks. It scans the repo first, then offers three ways to index it: everything (the wiki written by a model), no prose (the same wiki rendered from your code's structure, no key and no spend), or advanced, which walks through the indexing and generation knobs. Nothing is spent before you see an estimate and confirm it.

If you would rather not answer questions, or you are scripting this, name the mode and add -y:

repowise init --no-prose -y    # free, no key, no questions
repowise init --prose -y       # model-written subsystem pages, cost pre-approved

Either way you get the dependency graph, git history, code-health scores and dead-code findings in seconds, plus a complete wiki: file, module, layer and cycle pages, the architecture diagram, the repo overview, API and infra pages, and the onboarding collection. On the keyless path every page carries a footer saying it was derived from structure, and the repo overview describes composition, entry points, clusters and dependencies rather than what the project does end to end, because no template can derive that. Full-text search works on this index; semantic search needs an embedder configured (Ollama is the keyless option).

Went keyless and want the wiki written by a model later? You do not have to decide now. Upgrade it whenever you like with repowise generate, a page, a directory, or the whole thing at a time, each behind a cost estimate:

export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY / GEMINI_API_KEY
repowise generate                       # write the unwritten subsystem pages, behind one cost estimate
repowise generate --path src/api        # or just one area first
repowise generate --all                 # or rewrite the prose on every subsystem page

Bare repowise generate prints the wiki's state and writes the unwritten subsystem (concept) pages behind a single cost estimate. Every other page was already rendered from structure at index time.

Or pick the provider for the first index directly with repowise init --provider gemini|anthropic|openai.

3. Connect your agent. The MCP server is repowise mcp, served from the repo directory.

# Plugin (adds the tools, slash commands and skills):
/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowise

# ...or wire the MCP server directly:
claude mcp add repowise -- repowise mcp

Or commit a project .mcp.json:

{ "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp"] } } }

Add to ~/.codex/config.toml:

[mcp_servers.repowise]
command = "repowise"
args = ["mcp"]

Or: codex mcp add repowise -- repowise mcp

4. First real call. Ask your agent: "Use repowise get_overview to summarize this repo", or "get_context for src/auth.py". You get graph-grounded architecture and per-file triage instead of a flurry of greps.

get_overview and get_context work in index-only mode with no key, synthesized from the graph, git and health layers. search_codebase and get_answer read the wiki, which index-only mode does build, but they answer from pages rendered from structure rather than model-written prose, and search_codebase is full-text only until you configure an embedder.

Full walkthrough: docs/start/QUICKSTART.md →

The ten MCP tools

Every response carries an _meta envelope with index_age_days, indexed_commit, and a stale_warning that fires only when the indexed HEAD diverges from live .git/HEAD, so your agent always knows how much to trust what it just read.

Ten is a deliberate ceiling rather than a limit we ran into: a small, task-shaped surface is easier for an agent to choose from than a large one. Worked example ("add rate limiting to all API endpoints" in 5 calls instead of ~30 greps and reads), the opt-in tools, and the full reference: docs/agent/MCP_TOOLS.md →

How it compares

The PR bot, against the LLM review bots

The axis where this is not close is the first two rows. An LLM reviewer is a different product with a different failure mode: it can read intent, and it can also be wrong in a new way on every run. This one does set arithmetic over a call graph and a git history, so there is nothing to hallucinate and nothing to prompt-inject, and pushing the same diff twice produces the same review twice.

repowise is the intersection: an agent-native context layer and behavioral git intelligence and a defect-validated health score with the fix attached, all out of one index, self-hostable and open source. Full side-by-side comparisons: repowise.dev/compare →

Who it's for

For teams & enterprises

repowise.dev is the same engine, fully managed, at feature parity with self-hosted: every CLI command, every MCP tool, the whole dashboard. We run it on our own codebase in the open: live snapshot → · explore public repos →.

On top of self-hosting: managed deploys and webhooks with auto re-index on every commit, a hosted MCP endpoint so any client can point at one URL with no local server, a CVE-aware security layer, cross-repo intelligence at scale, and integrations (Slack, Jira/Linear, Confluence/Notion, PagerDuty) (rolling out).

What is GA versus in development, on-prem topology, SSO/SCIM/RBAC and pricing: docs/business/COMMERCIAL.md · Get in touch →

Privacy

• Self-hosted: your code never leaves your infrastructure, so no code, file paths or repo names are ever sent. The CLI does report anonymous, opt-out usage telemetry (command names and coarse environment only) to help us prioritize; turn it off with repowise telemetry disable, DO_NOT_TRACK=1, or by running fully offline. What's collected →

• Bring your own key: we never see your LLM calls. Zero data retention via Anthropic's API policy.

• What's stored: the graph, embeddings (non-reversible vectors), generated wiki pages, git metadata. Raw source is processed transiently and never persisted.

• Fully offline: Ollama plus a local embedding model means zero external calls.

Doing a security review? docs/business/SECURITY_COMPLIANCE.md →

CLI

repowise init [PATH]      # index a codebase (one-time; asks, or --no-prose -y needs no LLM)
repowise generate [PATH]  # write wiki pages with a model, on demand (upgrade a keyless wiki)
repowise serve [PATH]     # MCP server + local dashboard
repowise update [PATH]    # incremental update (seconds; --workspace for every repo)
repowise watch            # auto-sync daemon, re-index on file change
repowise search "<q>"     # search the wiki (fulltext / semantic / symbol)
repowise health           # code-health KPIs and lowest-scoring files
repowise risk main..HEAD  # score a branch or PR range for defect risk
repowise impacted-tests   # only the tests a diff actually exercises
repowise dead-code        # unreachable-code report
repowise decision list    # architectural decisions
repowise export --format structurizr  # the architecture as Structurizr DSL, no LLM
repowise distill pytest   # compact, errors-first, reversible command output
repowise saved            # tokens and dollars saved by distillation
repowise workspace add    # multi-repo workspace management
repowise doctor           # check setup, API keys, index drift

Every command and flag: docs/reference/CLI_REFERENCE.md · config: docs/reference/CONFIG.md · examples: examples/

Contributing

git clone https://github.com/repowise-dev/repowise
cd repowise
uv sync --all-packages
uv run repowise --version
uv run pytest tests/unit/

New here? You do not have to read 3,000 files to start. We keep a public index of this repo built by repowise itself, re-indexed on every push: explore repowise with repowise → (architecture, hotspots, ownership, decisions, and a ranked refactoring backlog you are welcome to pick from).

Full guide, including how to add languages and LLM providers: CONTRIBUTING.md · architecture: docs/architecture/

License

AGPL-3.0. Free for individuals, teams and companies using repowise internally.

For commercial licensing (the enterprise security and compliance layer, SSO/SCIM, RBAC, workflow integrations, priority support and SLA, or embedding repowise in a product without AGPL obligations), see docs/business/COMMERCIAL.md or contact hello@repowise.dev.

Built for engineers who got tired of watching their AI agent cat the same file for the fourth time.