repowise-dev/repowise

Repowise – Evidence‑backed code‑base intelligence

What it is – Repowise is a Python‑based tool that builds a local, continuously‑updated index of a repository. The index combines a language‑agnostic call‑graph, git history, test‑coverage information, documentation, and recorded architectural decisions. From this single source of truth it serves deterministic (no LLM calls) answers to questions that developers or AI‑powered coding agents normally have to discover by grepping, reading code, or running expensive model prompts.

Why it matters – Modern AI coding assistants spend a lot of time “rediscovering” the structure of a codebase on every request, which inflates token usage, slows down the agent, and can lead to missed context. Repowise does the heavy lifting once, then supplies cited, graph‑aware results in far fewer tool calls and with dramatically smaller payloads (e.g., 393 tokens vs 13 984 tokens for a typical commit context). The project also provides concrete, actionable refactoring suggestions and a health score for each file, all computed locally and open‑source.

---

Core capabilities

Area	What Repowise provides
Code graph	AST‑parsed dependencies for 25 languages, confidence‑stamped call resolution, community detection, centrality metrics, and execution‑flow traces.
Git signals	Hot‑spot detection, ownership, co‑change statistics, bus‑factor, and bug‑fix history – all derived from the repository’s own commit log.
Documentation wiki	Auto‑generated, incremental wiki pages for every module/file; optional LLM‑written prose can be added per‑page.
Architectural decisions	Deterministic extraction from five sources (e.g., commit messages, code comments) plus manual capture; each decision is linked to evidence.
Code‑health analysis	49 deterministic detectors (complexity, cohesion, clone detection, untested hotspots, change entropy, etc.) produce a 1‑10 health score per file and concrete refactoring plans (extract class/method, move method, split file, etc.).
Test intelligence	Finds which tests reach a file via the call graph (fallback when coverage reports are missing) and can list the minimal test set exercised by a diff.
Change risk	Scores a diff or PR on a 0‑10 scale using graph and git signals; returns actionable directives like may_break or missing_tests.
MCP tools	Ten task‑shaped “Model‑Control‑Protocol” endpoints (graph, git, docs, decisions, health, risk, impacted‑tests, distill, etc.) that any MCP‑compatible agent (Claude Code, Codex, Cursor, VS Code, etc.) can call.
Distillation	Compresses noisy command output (e.g., long pytest logs) before it reaches the agent, preserving errors and exit codes while cutting token usage by 60‑90 %.
PR bot	GitHub App that posts a single, constantly‑updated comment on each PR with blast‑radius, test impact, risk score, health alerts, and a link to a detailed analysis page.

---

Typical workflow

1. Install – pip install repowise.
2. Initialize – repowise init --no-prose -y inside the target repository. This parses the code, builds the graph, extracts git signals, creates the wiki, and runs the health detectors.
3. Serve – repowise serve starts a local HTTP endpoint exposing the MCP tools.
4. Connect – Point your coding agent (Claude Code, Codex, Cursor, etc.) to the endpoint, or open the built‑in dashboard to explore health scores, change risk, and refactoring suggestions.
5. Iterate – As the repo changes, Repowise incrementally updates the index, keeping all answers fresh without re‑running the whole analysis.

---

Who should use it

Use case	How Repowise helps
AI‑assisted development	Agents receive pre‑computed, cited context (e.g., “who calls auth.validate?”) in a single call, reducing token consumption and latency.
Safe pull‑request reviews	Automatic risk scoring, test‑impact lists, and blast‑radius maps appear directly in the PR comment, letting reviewers focus on real breakage risk.
Continuous code‑health improvement	Health scores surface defect‑prone files; concrete refactoring plans can be fed to an agent or applied manually.
Large multi‑repo workspaces	A single MCP endpoint can serve many repositories, enabling cross‑service contract checks and architecture enforcement.
Enterprise rollout	The core analysis runs entirely on‑premises, no API keys required, with an AGPL‑3.0 license and optional commercial support for security controls and SLA guarantees.

---

Installation & quick start

pip install repowise               # get the CLI and library
cd /path/to/your/repo
repowise init --no-prose -y        # build the index (no LLM needed)
repowise serve                     # start the local MCP server
# Example queries
repowise risk main..HEAD           # change‑risk score for the current PR
repowise health --refactoring-targets  # list low‑health files with concrete fixes
repowise impacted-tests main..HEAD   # minimal test set for the diff

Full instructions are in docs/start/QUICKSTART.md.

---

Evidence & benchmarks

• Agent efficiency – In a study on 43 questions over the django/django repo, Repowise reduced agent output by 31.6 % and cut the number of tool calls from 7.2 → 3.8 (p < 0.0001).
• Payload reduction – A typical commit context shrank from 13 984 → 393 tokens (97.2 % less).
• Defect prediction – The health engine’s 49 detectors were calibrated on a real defect corpus; on‑repo validation shows a 3.3× enrichment of recent bugs among the lowest‑health files.
• Graph accuracy – Benchmarked against 5 other tools on 37 853 oracle edges; Repowise achieved the highest precision across all 7 compiler‑graded cells.
• All benchmark data, methods, and limitations are published in docs/BENCHMARKS.md.

---

Licensing & availability

• Open‑source – AGPL‑3.0 (source on GitHub, PyPI package repowise).
• Self‑hosted – The core analysis runs locally; no external API keys or cloud services are required.
• Commercial options – Optional paid support, security extensions, and SLA guarantees for enterprises.

---

Where to learn more

• Live demo – https://repowise.dev (no sign‑in required).
• Documentation – https://docs.repowise.dev
• GitHub repository – https://github.com/repowise-dev/repowise
• PR bot installation – https://github.com/apps/repowise-bot

---

Bottom line – Repowise turns a repository into a deterministic knowledge base that AI agents and developers can query instantly, cutting token costs, improving safety, and delivering concrete, actionable fixes without ever sending your code to a remote LLM.