Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs: lead with the numbers, restore the five-layer table, fix serve ports (#961)
Raghav Chamadiyab5658f7de124
diff --git a/README.md b/README.mdindex fcbc936ad..471e4a381 100644--- a/README.md+++ b/README.md@@ -26,12 +26,13 @@<p align="center"><sub><a href="#your-agent-stops-guessing">For your agent</a> ·+ <a href="#what-one-index-actually-builds">The five layers</a> ·<a href="#stop-paying-for-output-nobody-reads">Distill</a> ·<a href="#know-whats-dangerous-before-you-merge">Change risk</a> ·<a href="#-know-exactly-what-to-fix">Code health</a> ·<a href="#see-all-of-it">Dashboard</a> ·<a href="#past-one-repo">Workspaces</a> ·- <a href="#quickstart">Quickstart</a> ·+ <a href="#quickstart-under-5-minutes-no-api-key">Quickstart</a> ·<a href="#the-ten-mcp-tools">MCP tools</a> ·<a href="#how-it-compares">Comparison</a> ·<a href="#for-teams--enterprises">Teams</a>@@ -41,7 +42,10 @@### Your AI agent burns most of its budget rediscovering your codebase. Index it once, and it never has to again.-<sub>Free and self-hosted, runs on your machine, and the first index needs no API key.</sub>+### up to −96% tokens to load context · −89% file reads · −70% tool calls++<sub>Paired runs, same model, same harness, with and without repowise ([the numbers, and what they do not show →](docs/BENCHMARKS.md)).<br />+Free and self-hosted, runs on your machine, and the first index needs no API key.</sub><picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/one-index-dark.svg" />@@ -73,18 +77,10 @@ built around **tasks**: pass several targets in one call, get complete context b<img src=".github/assets/demo.gif" alt="Claude Code querying the codebase through repowise's MCP tools" width="100%" />-Because the exploration work is already done, that phase mostly disappears:--<div align="center">--**up to −96% tokens to load context · −89% file reads · −70% tool calls**--</div>--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**. Paired runs, same model, same harness,-with and without repowise ([the numbers, and what they do not show →](docs/BENCHMARKS.md)).+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](docs/agent/HOOKS.md) pushcontext into the session at the moment it matters: the governing architectural@@ -101,6 +97,28 @@ local, all deterministic, no extra LLM calls.---+## 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.++| Layer | What it gives you | Edge |+|---|---|---|+| **◈ Graph** | Dependency graph across 16 languages · file + symbol nodes · 3-tier call resolution · Leiden communities · PageRank and execution flows · framework-aware route→handler edges | A real graph most tools never build |+| **◈ Git** | Hotspots (churn × complexity) · ownership % · co-change pairs (hidden coupling) · bus factor · which files actually get bug-fixed, and how recently | Behavioural signals static analysis cannot see |+| **◈ Docs** | A generated wiki page per module and file · rebuilt incrementally every commit · freshness and confidence scoring · hybrid search (full-text + vector) · selectable style and output language | Stays current instead of rotting |+| **◈ Decisions** | Architectural decisions mined from eight sources, evidence-backed, linked to the graph nodes they govern, connected by supersedes / refines / conflicts_with, tracked for staleness | **★ Captured nowhere else** |+| **★ Code health** | **25 deterministic markers**, 1 to 10 per file · three signals: defect risk · maintainability · performance · coverage ingestion · concrete refactoring plans (Extract Class / Helper, Move Method, Break Cycle, Split File) · **zero LLM, under 30s** | **★ Defect-validated, with the fix attached** |++Only the Docs layer needs an LLM. `repowise init --index-only` builds the graph,+git, decision, and health layers with no API key and no spend (seven of the eight+decision sources are deterministic; only the one harvested during doc generation+needs a provider).++Full detail on every layer: **[docs/layers/INTELLIGENCE_LAYERS.md →](docs/layers/INTELLIGENCE_LAYERS.md)**++---+## Stop paying for output nobody readsMost of what an agent reads back from a shell command is noise: 300 lines of passingdiff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.mdindex eef695706..92fa8b35d 100644--- a/docs/BENCHMARKS.md+++ b/docs/BENCHMARKS.md@@ -163,8 +163,9 @@ correlated with strictly no leakage: nothing after T0 feeds the score.### Cross-project validation-Across **21 open-source repositories spanning all 9 Full-tier languages** and-2,826 files:+Across **21 open-source repositories spanning 9 languages** and 2,826 files+(the study predates the promotion of Scala and Ruby to the Full tier, so it+covers 9 of today's 11):- **Mean ROC AUC 0.74** (95% CI 0.68 to 0.79) at identifying the files that goon to receive bug fixes, reaching **0.90** on individual repos. ROC AUC is thediff --git a/docs/start/DASHBOARD.md b/docs/start/DASHBOARD.mdindex 91d0b550e..05dbeba1f 100644--- a/docs/start/DASHBOARD.md+++ b/docs/start/DASHBOARD.md@@ -1,15 +1,20 @@# The dashboard-`repowise serve` starts a local web app on `http://localhost:7777` that reads-the same `.repowise/wiki.db` the CLI and MCP server read. Nothing leaves your-machine, and no view calls an LLM unless you click something that says it will-(Chat, refactoring code generation, doc regeneration).+`repowise serve` starts the API on `http://localhost:7337` and the local web+dashboard on `http://localhost:3000`. Both read the same `.repowise/wiki.db`+the CLI and MCP server read. Nothing leaves your machine, and no view calls an+LLM unless you click something that says it will (Chat, refactoring code+generation, doc regeneration).```bash-repowise serve # http://localhost:7777-repowise serve --port 8080+repowise serve # API on :7337, dashboard on :3000+repowise serve --port 8080 # move the API+repowise serve --ui-port 3001 # move the dashboard+repowise serve --no-ui # API only```+The dashboard needs Node >= 20. Without it, `serve` falls back to API-only.+The URL shape is `/repos/<repo-id>/<view>`. Every view is directly linkable,including tab state, so a link you paste in a PR lands on exactly what you werelooking at.