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: revamp README and align linked docs for accuracy (#334)
Raghav Chamadiya21dffbb47be9
diff --git a/README.md b/README.mdindex 4c89f63cd..7c90d04c6 100644--- a/README.md+++ b/README.md@@ -4,7 +4,7 @@<p align="center"><em>The codebase intelligence layer for your AI coding agent.</em></p>-<p align="center"><strong>Five intelligence layers · Nine MCP tools · Multi-repo workspaces · Auto-sync hooks · One <code>pip install</code></strong></p>+<p align="center"><strong>Five intelligence layers · Nine MCP tools · 15 languages · Multi-repo workspaces · One <code>pip install</code></strong></p><p align="center"><a href="https://www.repowise.dev"><img src="https://img.shields.io/badge/LIVE_DEMO-repowise.dev-F59520?style=for-the-badge&labelColor=0A0A0A" alt="Live demo — repowise.dev" /></a>@@ -26,14 +26,14 @@</p><p align="center"><sub>+ <a href="#the-five-layers">Layers</a> ·+ <a href="#-code-health--the-layer-nobody-else-nails">Code Health</a> ·<a href="#benchmarks">Benchmarks</a> ·- <a href="#what-repowise-builds">Intelligence layers</a> ·+ <a href="#supported-languages">Languages</a> ·<a href="#quickstart">Quickstart</a> ·<a href="#nine-mcp-tools">MCP tools</a> ·- <a href="#local-dashboard">Dashboard</a> ·<a href="#how-it-compares">Comparison</a> ·- <a href="#hosted-version--for-teams">Hosted</a> ·- <a href="#license">License</a>+ <a href="#for-teams--enterprises">Hosted</a></sub></p>---@@ -44,414 +44,262 @@</div>-Your AI coding agent reads files. It doesn't know which ones change together, which ones are dead, or why they were built the way they were. It has the source code and no memory of how the codebase got there.+Your AI coding agent reads files. It doesn't know which ones change together,+which ones are dead, or *why* they were built the way they were. It has the+source code and no memory of how the codebase got there.-repowise fixes that. It indexes your codebase into five intelligence layers — dependency graph, git history, auto-generated documentation, architectural decisions, and code health — and exposes them to Claude Code (and any MCP-compatible AI agent) through nine precisely designed tools. Multi-repo? Initialize a workspace and get cross-repo co-change detection, API contract extraction, and federated MCP queries across all your services. **The result: fewer tool calls, fewer file reads, and lower cost per query — at comparable answer quality.**--The result: your agent answers *"why does auth work this way?"* instead of *"here is what auth.ts contains."*-------## Benchmarks--Most of a coding agent's spend goes to *exploration* — greping for symbols, reading candidate files, re-reading them as context grows. repowise does that work once, offline, so the agent skips it on every query. In early paired SWE-QA runs on real repositories (same model, same harness, with and without repowise's MCP tools), that translated into up to **−70% tool calls, −89% file reads, and −36% cost per query at comparable answer quality**.--And the intelligence isn't only for agents — repowise's **code-health score predicts where bugs will land**. Validated across **13 repositories in 5 languages** (Python, TypeScript, JavaScript, Rust, Go), the score reaches **ROC AUC up to 0.90** at identifying the files that go on to receive bug-fixes over the next six months — and the handful it flags unhealthiest concentrate **up to 80% of those future fixes**. The biomarker weights are **learned from real defect history, not hand-tuned**, while the runtime stays fully deterministic and LLM-free. Full methodology and results live at **[repowise-bench →](https://github.com/repowise-dev/repowise-bench)**.+repowise fixes that. It indexes your codebase into **five intelligence layers** —+dependency graph, git history, auto-generated docs, architectural decisions, and+code health — and exposes them to Claude Code (and any MCP-compatible agent)+through **nine task-shaped tools**. The result: your agent answers *"why does+auth work this way?"* instead of *"here is what `auth.ts` contains"* — with+**fewer tool calls, fewer file reads, and lower cost per query, at comparable+answer quality** ([benchmarks ↓](#benchmarks)).----## What repowise builds+## The five layersrepowise runs once, builds everything, then keeps it in sync on every commit.+Each layer is queryable from the CLI, the MCP tools, and the local dashboard.-### ◈ Graph Intelligence-tree-sitter parses every file across 14 languages into a two-tier dependency graph — file nodes and symbol nodes (functions, classes, methods). A 3-tier call resolver with confidence scoring handles import aliases, barrel re-exports, and namespace imports. Heritage extraction covers extends, implements, trait impls, derive macros, mixins, and extension conformance. Leiden community detection finds logical modules even when your directory structure doesn't reflect them. PageRank, betweenness centrality, SCC analysis, and execution flow tracing from entry points identify your most central, most coupled, and most traversed code.--### ◈ Git Intelligence-Your git history turned into signals: hotspot files (high churn × high complexity), ownership percentages per author, co-change pairs (files that change together without an import link — hidden coupling), and significant commit messages that explain *why* code evolved. Rolled up into **contributor profiles** (per-author module rollups, top files, co-authors, silo modules, dead-code burden), **module health scorecards** (composite score over churn × ownership × docs × dead code × bus factor), and **reviewer suggestions** for any PR file list, weighted by direct authorship, co-change history, and recency.--### ◈ Documentation Intelligence-An LLM-generated wiki for every module and file, rebuilt incrementally on every commit. Coverage tracking. Freshness scoring per page. Semantic search via RAG. Confidence scores show how current each page is relative to the underlying code.+| Layer | What it gives you | Unique? |+|---|---|---|+| **◈ Graph** | tree-sitter dependency graph across 15 languages · two-tier file + symbol nodes · 3-tier call resolution · Leiden communities · PageRank / centrality / execution flows · framework-aware route→handler edges | Table stakes |+| **◈ Git** | hotspots (churn × complexity) · ownership % · co-change pairs (hidden coupling) · bus factor · contributor profiles · module health · reviewer suggestions | Rare |+| **◈ Docs** | LLM-generated wiki per module/file · incremental on every commit · freshness + confidence scoring · hybrid RAG search (FTS + vector via RRF) | Table stakes |+| **◈ Decisions** | architectural decisions mined from **8 sources**, evidence-backed (verified / fuzzy / unverified), linked to graph nodes, connected by `supersedes`/`refines`/`conflicts_with` edges, tracked for staleness | **Nobody else** |+| **★ Code Health** | **25 deterministic biomarkers**, 1–10 score per file · defect-calibrated weights · coverage ingestion · trend alerts · refactoring targets · **zero LLM, <30s** | **Our moat ↓** |-### ◈ Decision Intelligence-The layer nobody else has. Architectural decisions mined from **eight sources** — ADR files (Nygard/MADR), CHANGELOG entries, PR and squash-commit bodies, inline markers, git archaeology, README/docs, centrality-bounded code comments, and the LLM doc-generation pass itself — linked to the graph nodes they govern and tracked for staleness as code evolves.+Full deep-dive on every layer (graph, git, docs, decisions, hooks, auto-sync,+dead code, CLAUDE.md generation): **[docs/INTELLIGENCE_LAYERS.md →](docs/INTELLIGENCE_LAYERS.md)**-```python-# WHY: JWT chosen over sessions — API must be stateless for k8s horizontal scaling-# DECISION: All external API calls wrapped in CircuitBreaker after payment provider outages-# TRADEOFF: Accepted eventual consistency in preferences for write throughput-```+----Every decision is **evidence-backed**: each rationale traces to a verbatim source span (ADR quote, commit body, code comment), and an anti-hallucination substring gate stamps each as **verified / fuzzy / unverified** — corroborating sources raise confidence rather than overwrite each other. Decisions form a **graph**: typed edges (`supersedes` / `refines` / `relates_to` / `conflicts_with`) let `get_why()` answer *"why is auth structured this way?"* with a lineage chain (sessions → JWT → OAuth2), auto-detect when a new commit reverses an old decision, and flag two active decisions that contradict each other.+## ★ Code Health — the layer nobody else nails-These structured records surface everywhere your agent already looks — `get_why()` for the full archaeology, but also as governing decisions in `get_context()`, a `governance_risk` flag in `get_risk()` PR review, a Key Decisions section in `get_overview()`, and as `ungoverned_hotspot` / `stale_governance` / `contradictory_decision` findings in the code-health layer.+Graph and wiki layers now have competition. **Code health is where repowise is+unique** — and we can prove it predicts real bugs.-### ◈ Code Health Intelligence-Fifteen deterministic biomarkers compute a 1–10 health score per file — McCabe complexity, deep nesting, brain methods, native Rabin–Karp duplication detection, untested hotspots, primitive obsession, developer congestion, knowledge loss, blame-based function hotspots, code-age volatility, and more. **Zero LLM calls, zero new runtime dependencies** — pure Python over tree-sitter and git data, designed to finish in under 30 seconds on a 3 000-file repo.+repowise scores **every file 1–10** from **25 deterministic biomarkers** —+McCabe complexity, deep nesting, brain methods, class cohesion (LCOM4), god+classes, native Rabin–Karp clone detection, untested hotspots, function-level+churn, code-age volatility, ownership dispersion, change entropy, co-change+scatter, prior-defect history, test-quality smells, and more.-Ingest LCOV, Cobertura, or Clover coverage reports to light up the test-coverage biomarkers. Rolling 50-row snapshot history powers `Declining Health` and `Predicted Decline` alerts. Deterministic, rule-based refactoring suggestions surface on the dashboard and via `get_health(include=["refactoring"])`. Per-file overrides via `.repowise/health-rules.json`.+> **Zero LLM calls. Zero cloud requirement. Zero new runtime dependencies.**+> Pure Python over tree-sitter + git data — finishes in **under 30 seconds** on+> a 3,000-file repo. The biomarker weights are **calibrated against a real defect+> corpus, not hand-tuned**; only the learned constants ship and the runtime+> stays fully deterministic.```bashrepowise health # KPIs + lowest-scoring files-repowise health --coverage cov.lcov # ingest coverage, light up untested-hotspot+repowise health --coverage cov.lcov # ingest LCOV/Cobertura/Clover → untested-hotspotrepowise health --refactoring-targets # ranked by impact / effort-repowise health --trend # last 10 snapshots + alerts-repowise status # one-line summary in the status report-```--See [`docs/CODE_HEALTH.md`](docs/CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](docs/architecture/code-health.md) for the internals.-------## Quickstart--```bash-pip install repowise-```--Or install the CLI into an isolated, uv-managed environment:--```bash-uv tool install repowise+repowise health --trend # snapshots + declining / predicted-decline alerts```-### Single repo--```bash-cd your-project-repowise init # builds all five intelligence layers (one-time)-repowise serve # starts MCP server + local dashboard-```--### Multi-repo workspace--```bash-cd my-workspace/ # parent dir containing backend/, frontend/, shared-libs/-repowise init . # scans for git repos, indexes each, runs cross-repo analysis-repowise serve # workspace dashboard + per-repo pages-```+**Does the score actually find bugs? Yes — and it out-ranks the leading+commercial code-health tool.** On the **same 2,770 files across 9 languages**,+scored at the same leakage-free commit against the same defect labels:-That's it. `repowise init` automatically registers the MCP server, installs PreToolUse/PostToolUse hooks in `~/.claude/settings.json`, generates `.mcp.json` at the project root, and offers to install a post-commit git hook that keeps everything in sync after every commit. See [Auto-Sync](docs/AUTO_SYNC.md) for all sync methods (hooks, file watcher, GitHub/GitLab webhooks, polling).--To manually add the MCP server to another editor:--```json-{- "mcpServers": {- "repowise": {- "command": "repowise",- "args": ["mcp", "/path/to/your/project"]- }- }-}-```+| Axis (head-to-head, paired tests) | repowise | Leading commercial tool |+|---|---:|---:|+| **Recall @ 20%-of-lines budget** | **0.173** | 0.074 |+| **Effort-aware ranking (Popt)** | **0.607** | 0.462 |+| **Defect density, size-normalized (defects/KLOC, Alert:Healthy)** | **2.18×** | 0.56× |+| Discrimination (ROC AUC) | **0.731** | 0.705 |-> **Note on init time:** The graph, git, dead-code, and code-health layers build in minutes with **zero LLM calls** — run `repowise init --index-only` and you have a queryable index almost immediately. The one-time cost is the documentation layer: LLM-generated wiki pages, which scale with repo size and run once (and can run in the background). After that, every update following a commit takes **under 30 seconds** and only regenerates the few pages your change touched.+Ranking by repowise health surfaces **2.3× the defects under a fixed review+budget** (Popt Δ +0.144, recall Δ +0.098, density Δ p = 0.003 — all paired,+significant). [Full methodology & CIs →](https://github.com/repowise-dev/repowise-bench/blob/main/health-defect/COMPARISON_REPORT.md)-> **Full docs:** [Quickstart](docs/QUICKSTART.md) · [User Guide](docs/USER_GUIDE.md) · [CLI Reference](docs/CLI_REFERENCE.md) · [MCP Tools](docs/MCP_TOOLS.md) · [Workspaces](docs/WORKSPACES.md) · [Computed Glossary](docs/COMPUTED_GLOSSARY.md) · [Auto-Sync](docs/AUTO_SYNC.md)+User guide & per-biomarker reference: **[docs/CODE_HEALTH.md](docs/CODE_HEALTH.md)**----## Workspaces — multi-repo intelligence--Most codebases aren't one repo. repowise workspaces let you index and query multiple repositories together — with cross-repo intelligence that single-repo tools can't provide.--```bash-cd my-workspace/ # backend/, frontend/, shared-libs/ under one parent-repowise init . # scan, select repos, index each, run cross-repo analysis-```--**What you get on top of per-repo intelligence:**--| Feature | What it does |-|---|---|-| **Cross-repo co-changes** | Finds files across repos that change in the same time window — e.g., `backend/api/routes.py` and `frontend/src/api/client.ts` always move together |-| **API contract extraction** | Scans for HTTP route handlers (Express, FastAPI, Spring, Go), gRPC service defs, and message topic publishers/subscribers — then matches providers with consumers across repos |-| **Package dependency mapping** | Reads `package.json`, `pyproject.toml`, `go.mod`, `pom.xml` to detect when one repo depends on another as a package |-| **Federated MCP queries** | One MCP server serves all repos. Pass `repo="backend"` or `repo="all"` to any tool |-| **Workspace dashboard** | Aggregate stats, repo cards, contract links, co-change pairs — all in the web UI |-| **Workspace CLAUDE.md** | Auto-generated context file covering all repos, their relationships, and cross-repo signals |--**Workspace CLI:**--```bash-repowise workspace list # show all repos and their status-repowise workspace add ../new-service # add a repo (auto-indexes + docs by default)-repowise workspace remove api-gateway # remove a repo (doesn't delete files)-repowise workspace scan # re-scan for new repos-repowise update --workspace # update all stale repos + first-time index any new ones-repowise update --repo backend # scope to one repo (auto-detected from cwd too)-repowise watch --workspace # auto-update all repos on file change-repowise doctor --workspace --repair # validate every repo; sync state drift; drop dead entries-repowise hook install --workspace # install post-commit hooks for all repos-```--Most commands also accept `--no-workspace` to force single-repo mode and `--repo <alias>` to scope to one repo. See [CLI Reference](docs/CLI_REFERENCE.md#workspace-auto-detect-cross-cutting).--Full guide: [docs/WORKSPACES.md](docs/WORKSPACES.md)+## Benchmarks----+Reproducible, on public codebases — **[repowise-bench →](https://github.com/repowise-dev/repowise-bench)**-## Nine MCP tools+### 1 · Agent efficiency — repowise does the exploration once, offline-Most tools are designed around data entities — one module, one file, one symbol — which forces AI agents into long chains of sequential calls. repowise tools are designed around **tasks**. Pass multiple targets in one call. Get complete context back. 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` — silence means the index is current. Full reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)+Most of a coding agent's spend goes to *exploration* — greping for symbols,+reading candidate files, re-reading them as context grows. repowise does that+work once so the agent skips it on every query. Paired SWE-QA runs on real+repositories (same model, same harness, with vs without repowise's MCP tools):-| Tool | What only this tool answers | When Claude Code calls it |-|---|---|---|-| `get_overview()` | Architecture summary, module map, entry points, git health, community summary | First call on any unfamiliar codebase |-| `get_answer(question)` | Hybrid retrieval (FTS + vector merged via RRF) plus PageRank bias and 1-hop graph expansion, synthesised into a cited answer with a calibrated `retrieval_quality` reported separately from `confidence`. On low confidence returns a structured `best_guesses` list with one-line per-file justifications instead of an empty answer. Decision records are fused in for "why"-shaped questions. | First call on any code question — collapses search → read → reason into one round-trip |-| `get_context(targets, include?)` | Triage card for files / modules / symbols: title, summary, signatures, `hotspot` bit, `governing_decisions` (status + staleness + verified/fuzzy trust badge), and `symbol_id`s the agent pipes into `get_symbol`. NOT source bytes. `include` opens richer data: `"callers"`/`"callees"`, `"ownership"`, `"last_change"`, `"metrics"`, `"community"`, `"decisions"`, `"full_doc"`. Batch multiple targets. | Before reading or modifying code. Pass all relevant targets in one call. |-| `get_symbol("path/to/file.py::Name")` | Raw source bytes for one indexed symbol with exact line bounds — cheaper and safer than `Read` + offset math. Bounded at ~400 lines, normalises `::` / `.` / `/` separators across languages, deterministic resolution on overloads. | When you need the body of one function or class. Use the `symbol_id` returned by `get_context`. |-| `search_codebase(query, kind?)` | Semantic search over the wiki. Each result tags its `search_method` (`"embedding"` vs `"bm25"` fallback) and is filterable by `kind` (`implementation` / `test` / `config` / `doc`). Surfaces a Grep hint when the query is a bareword identifier. | When `get_answer` returned low confidence and you need to discover candidate pages by topic |-| `get_risk(targets, changed_files?)` | Hotspot scores, dependents, co-change partners, ownership, test gaps, security signals. Pass `changed_files` for PR mode → response carries a `directive` block (`will_break`, `missing_cochanges`, `missing_tests`, `governance_risk` — files governed by a stale, superseded, or contradicted decision) for one-glance review plus cross-repo blast radius. | Before modifying files — understand what could break |-| `get_why(query?, targets?)` | Architectural decision records, their status (active / proposed / deprecated / superseded), the evidence spans behind them (verified / fuzzy / unverified), and the supersession **lineage chain** for "why is X like this?" questions. Falls back to git archaeology when no ADRs exist for a file. | Before architectural changes — understand existing intent |-| `get_dead_code(min_confidence?, include_internals?)` | Unreachable code sorted by confidence tier with cleanup impact estimates. In workspace mode, cross-repo consumer detection lowers confidence on findings that other repos import. | Cleanup tasks |-| `get_health(targets?, include?)` | Fifteen deterministic biomarker scores per file. Dashboard mode returns KPIs + the lowest-scoring files + a per-module NLOC-weighted rollup; targeted mode returns per-file findings. `include` flags layer richer data: `"coverage"`, `"refactoring"` (rule-based suggestions), `"trend"` (snapshot diff + declining/predicted-decline alerts). `module:foo` targets expand to a module's file set. | Before refactoring — find the worst-scoring files and what to fix first |+<div align="center">-### Tool call comparison — a real task+**−70% tool calls · −89% file reads · −36% cost per query · answer quality at parity**-*"Add rate limiting to all API endpoints."*+</div>-| Approach | Tool calls | Time to first change | What it misses |-|---|---|---|---|-| Claude Code alone (no MCP) | grep + read ~30 files | ~8 min | Ownership, prior decisions, hidden coupling |-| **repowise (9 tools)** | **5 calls** | **~2 min** | **Nothing** |+Best case shown; across the two benchmarks the range is −49% to −70% tool calls,+−69% to −89% file reads, and −29% to −36% cost. Bonus: feeding an agent a commit+via `get_context` costs **2,391 tokens vs 64,039** for the raw changed files —+**~27× fewer**. Reports: [flask48](https://github.com/repowise-dev/repowise-bench/blob/main/BENCHMARK_REPORT_FLASK48.md) · [sklearn48](https://github.com/repowise-dev/repowise-bench/blob/main/BENCHMARK_REPORT_SKLEARN48.md)-Here are those five calls, and what each one actually returns:+### 2 · Code health predicts real defects-```-User: Implement rate limiting on all API endpoints+Health scores are collected at a historical commit (T0); bug-fixing commits are+counted over the following 6 months; the two are correlated — strictly no+leakage. Across **21 open-source repositories spanning all 9 Full-tier+languages**:-Claude Code:-→ get_overview()- "Express API. Entry points in api/routes/. Middleware in middleware/."+- **Cross-project mean ROC AUC 0.74** [95% CI 0.68–0.79] at identifying the files+ that go on to receive bug-fixes — up to **0.90** on individual repos.+- **Survives controlling for file size** (partial Spearman ρ = −0.16) — it is not+ just "flag the big files."+- **Significantly out-discriminates** recent churn (+0.10 AUC) and prior-defect+ history (+0.12 AUC), DeLong p < 1e-9.+- Holds up on an **external published dataset it has never seen** (PROMISE/jEdit+ CK-metrics: AUC 0.76–0.78, within ~0.03 of the dataset's own tuned model).-→ get_context(["middleware", "api/routes", "payments"])- middleware/: existing chain is cors → auth → routes. Owner: @alex.- api/routes/: 23 route files. No existing rate limiting.- payments/: Owner @sarah (71%). Decision: all side effects must be idempotent.+Full report: **[health-defect/BENCHMARK_REPORT.md →](https://github.com/repowise-dev/repowise-bench/blob/main/health-defect/BENCHMARK_REPORT.md)**-→ get_why("rate limiting")- "No prior decision found. No prior implementation detected."+----→ get_risk(["middleware/auth.ts"])- "47 files import this. Co-changes with all 4 service listeners.- Risk summary: any interface change here touches 47 dependents."+## Supported languages-→ search_codebase("rate limit throttle retry")- "Found: payments/retry.ts already has RetryQueue class.- Found: payments/middleware.ts has idempotency key middleware."+**15 languages parsed to AST · 9 at the Full tier · framework-aware across all of them.**++<p>+ <strong>Full tier </strong>+ <img src="https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python" />+ <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />+ <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=black" alt="JavaScript" />+ <img src="https://img.shields.io/badge/Java-ED8B00?style=flat-square&logo=openjdk&logoColor=white" alt="Java" />+ <img src="https://img.shields.io/badge/Kotlin-7F52FF?style=flat-square&logo=kotlin&logoColor=white" alt="Kotlin" />+ <img src="https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go" />+ <img src="https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white" alt="Rust" />+ <img src="https://img.shields.io/badge/C++-00599C?style=flat-square&logo=cplusplus&logoColor=white" alt="C++" />+ <img src="https://img.shields.io/badge/C%23-512BD4?style=flat-square&logo=csharp&logoColor=white" alt="C#" />+</p>+<p>+ <strong>Good tier </strong>+ <img src="https://img.shields.io/badge/C-A8B9CC?style=flat-square&logo=c&logoColor=black" alt="C" />+ <img src="https://img.shields.io/badge/Ruby-CC342D?style=flat-square&logo=ruby&logoColor=white" alt="Ruby" />+ <img src="https://img.shields.io/badge/Swift-F05138?style=flat-square&logo=swift&logoColor=white" alt="Swift" />+ <img src="https://img.shields.io/badge/Scala-DC322F?style=flat-square&logo=scala&logoColor=white" alt="Scala" />+ <img src="https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white" alt="PHP" />+ <strong>· Partial </strong>+ <img src="https://img.shields.io/badge/Luau-00A2FF?style=flat-square&logo=lua&logoColor=white" alt="Luau" />+</p>-Implementing rate-limiting middleware, inserting after cors, before auth.-Will also update tests/middleware.test.ts — detected as historical co-change partner.-Flagging payments/ for @sarah review — hotspot, high ownership concentration.-```+| Tier | Languages | What works |+|------|-----------|------------|+| **Full** | Python · TypeScript · JavaScript · Java · Kotlin · Go · Rust · C++ · C# | AST parsing, import resolution, named bindings, call resolution, heritage extraction, docstrings; multi-project workspace resolvers; framework-aware edges; per-language dynamic-hint extractors; **code-health biomarkers** |+| **Good** | C · Ruby · Swift · Scala · PHP | AST parsing, import resolution, named bindings, call resolution, heritage (mixins / derive / extensions / traits), docstrings; dedicated workspace-aware resolvers; Rails / Laravel / TYPO3 framework edges; dynamic-hint extractors |+| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · SQL · Terraform · Markdown · Shell | Included in the file tree; special handlers extract endpoints / targets where applicable |+| **Git-blame only** | Objective-C · Elixir · Erlang · Dart · Zig · Julia · Clojure · Haskell · OCaml · F# · … | Tracked in git history (blame, hotspots, co-change); no AST parsing yet |-This is what happens when an AI agent has real codebase intelligence.+Adding a language needs **one `.scm` query file and one config entry** — no+changes to the parser core. Full per-language matrix, code-health checklist, and+the contributor recipe: **[docs/LANGUAGE_SUPPORT.md →](docs/LANGUAGE_SUPPORT.md)**----## Local dashboard--`repowise serve` starts a full web UI alongside the MCP server. No separate setup — browse your codebase intelligence directly in the browser.--<img src=".github/assets/webui.gif" alt="repowise web UI" width="100%" />+## Who it's for-| View | What it shows |+| | Start here ||---|---|-| **Chat** | Ask anything about your codebase in natural language |-| **Docs** | AI-generated wiki with syntax highlighting, Mermaid diagrams, and a graph intelligence sidebar showing PageRank/betweenness percentiles, community membership, and degree |-| **Graph** | Interactive dependency graph — handles 2,000+ nodes. Community color mode with real labels, community detail panel on click, path finder |-| **C4 Architecture** | C4-model view of the codebase (Context → Containers → Components) with drill-down, URL-synced state, and a per-node detail panel that surfaces module health, top contributors, and the generated wiki page inline |-| **Search** | Full-text and semantic search with global command palette (Ctrl+K) |-| **Symbols** | Searchable index of every function, class, and method, server-ranked by importance (PageRank × visibility × complexity × kind × entry-point). Filter facets for public-only, language, kind, in-hotspot-files, and in-entry-point-files. Click any symbol for graph metrics, callers/callees, class heritage, and a git panel with governing decisions |-| **Coverage** | Doc freshness per file with one-click regeneration |-| **Risk** | One page, six tabs: Hotspots (with inline drill-down to the top importance-ranked symbols in each file), Heatmap (ownership treemap with bus-factor borders and silo overlay), Module Health, Dead Code, Impact (blast radius), and the always-visible risk strip linking to each |-| **Contributors** | Paginated contributor directory and per-author profile pages — modules they own, top files, co-authors, commit category mix, silo modules, bus-factor risk files, and dead-code burden. Click any owner anywhere in the dashboard to drill in |-| **Module Health** | Per-module rollup with a composite health score (churn / ownership / docs / dead code / bus factor), sortable list, and a per-module detail page showing owners, top hotspots, and governing decisions |-| **Hotspots** | Ranked by trend-weighted score (180-day decay) and churn. Paginated load-more; each row expands inline to the most important symbols in that file |-| **Dead Code** | Unused code with confidence scores, owner leaderboard, and bulk actions |-| **Decisions** | Architectural decisions with staleness monitoring and verified/fuzzy/unverified trust badges. Decision detail shows the **evidence drawer** (every source span behind a decision), the **evolution timeline** (supersession lineage, root → current), and a writable module-linkage editor; a **decision-graph view** renders decision→decision and decision→code edges with conflicts highlighted |-| **Costs** | LLM spend by day, model, or operation, with running session totals |-| **Blast Radius** | Paste a PR file list, see transitive impact, test gaps, and a ranked reviewer-suggestions panel weighted by direct authorship, co-change history, and recency |-| **Security** | Local regex-based scan for dangerous patterns — `eval`/`exec`/`pickle.loads`/`shell=True`/`os.system`, hardcoded secrets, f-string and concat SQL, `verify=False`, weak hashes — surfaced with severity and grouped by directory. Runs in seconds, no LLM, no network |-| **Knowledge Map** | Top owners, bus-factor silos, and onboarding targets on the dashboard |-| **Graph Intelligence** | Architecture communities with expandable detail, execution flows with call traces, community coupling analysis — all on the overview dashboard |-| **Workspace Dashboard** | Aggregate stats across repos, repo cards, cross-repo intelligence summary (workspace mode) |-| **Workspace Contracts** | Detected API contracts (HTTP, gRPC, topics) with provider/consumer matching across repos |-| **Workspace Co-Changes** | Cross-repo file pairs ranked by co-change strength |-| **System Health** | SQL/vector/graph drift status from the atomic store coordinator |+| **Individual developers** | `pip install repowise` → `repowise init` → query from Claude Code in minutes. 100% local, BYO API key, free under AGPL-3.0. |+| **Teams** | [**repowise.dev**](https://www.repowise.dev) hosted — zero ops, hosted MCP endpoint, auto re-index on every commit, plus the free [**Repowise PR Bot**](https://github.com/apps/repowise-bot) that comments on hotspots, hidden coupling, and declining health per PR. |+| **Enterprises** | On-prem topology, SSO/SCIM, RBAC, CVE-aware security layer, workflow integrations, and commercial licensing (no AGPL obligation) — see [**docs/COMMERCIAL.md**](docs/COMMERCIAL.md). |----## Proactive context enrichment — hooks--Most MCP tools are passive — the agent has to know to call them. repowise hooks are **active**. They inject graph context into every search automatically, so agents are smarter even when they don't explicitly ask for help.--### PreToolUse — every search gets graph context--When your AI agent runs `Grep` or `Glob`, repowise intercepts the call and enriches it with the top 3 related files — found via multi-signal search (symbol name match, file path match, and full-text search on wiki content), ranked by relevance then PageRank:--- **Symbols** — top functions, classes, and methods in each file-- **Imported by** — who depends on this file-- **Uses** — what this file depends on--No LLM calls. No network. Pure local SQLite queries.--```-[repowise] 3 related file(s) found:-- src/core/ingestion/graph.py- Symbols: class:GraphBuilder, method:__init__, method:build- Imported by: src/core/ingestion/__init__.py- Uses: src/core/analysis/communities.py, src/core/analysis/execution_flows.py-- src/core/ingestion/__init__.py- Imported by: src/cli/commands/update_cmd.py, src/core/pipeline/orchestrator.py- Uses: src/core/ingestion/graph.py-```--### PostToolUse — auto-detect stale wiki--After a successful `git commit`, repowise checks whether the wiki is out of date and notifies the agent:+## Quickstart+```bash+pip install repowise # or: uv tool install repowise```-[repowise] Wiki is stale — last indexed at commit a1b2c3d4, HEAD is now f9a0499b.-Run `repowise update` to refresh documentation and graph context.-```--Hooks are installed automatically during `repowise init`. No manual configuration needed. Full details: [docs/AUTO_SYNC.md](docs/AUTO_SYNC.md)-------## Auto-sync — five ways to keep your wiki current--repowise keeps your intelligence layers in sync with your code. Pick the method that fits your workflow:-| Method | Command | Best for |-|--------|---------|----------|-| **Post-commit hook** | `repowise hook install` | Set-and-forget local development |-| **File watcher** | `repowise watch` | Active development without committing |-| **GitHub webhook** | Configure in repo settings | Teams, CI/CD |-| **GitLab webhook** | Configure in project settings | Teams, CI/CD |-| **Polling fallback** | Automatic with `repowise serve` | Safety net for missed webhooks |+### Single repo```bash-# Install post-commit hook for one repo-repowise hook install--# Install for all repos in a workspace-repowise hook install --workspace--# Check hook status-repowise hook status--# Or use the file watcher-repowise watch # single repo-repowise watch --workspace # all workspace repos+cd your-project+repowise init # builds all five intelligence layers (one-time)+repowise serve # starts MCP server + local dashboard```-A typical single-commit update touches 3–10 pages and completes in under 30 seconds. Full guide: [docs/AUTO_SYNC.md](docs/AUTO_SYNC.md)-------## Auto-generated CLAUDE.md--After every `repowise init` and `repowise update`, repowise regenerates your `CLAUDE.md` from actual codebase intelligence — not a template. No LLM calls. Under 5 seconds.+### Multi-repo workspace```bash-repowise generate-claude-md+cd my-workspace/ # parent dir containing backend/, frontend/, shared-libs/+repowise init . # scans for git repos, indexes each, runs cross-repo analysis+repowise serve # workspace dashboard + per-repo pages```-The generated section includes: architecture summary, module map, hotspot warnings, ownership map, hidden coupling pairs, active architectural decisions, and dead code candidates. A user-owned section at the top is never touched.+`repowise init` automatically registers the MCP server, installs+PreToolUse/PostToolUse hooks in `~/.claude/settings.json`, generates `.mcp.json`+at the project root, and offers a post-commit hook that keeps everything in sync.-```markdown-<!-- REPOWISE:START — managed automatically, do not edit -->-## Architecture-Monorepo with 4 packages. Entry points: api/server.ts, cli/index.ts.+To add the MCP server to another editor manually:-## Hotspots — handle with care-- payments/processor.ts — 47 commits/month, high complexity, primary owner: @sarah-- shared/events/EventBus.ts — 23 dependents, co-changes with all service listeners--## Active architectural decisions-- JWT over sessions (auth/service.ts) — stateless required for k8s horizontal scaling-- CircuitBreaker on all external calls — after payment provider outages in Q3 2024--## Hidden coupling (no import link, but change together)-- auth.ts ↔ middleware/session.ts — co-changed 31 times-<!-- REPOWISE:END -->+```json+{+ "mcpServers": {+ "repowise": { "command": "repowise", "args": ["mcp", "/path/to/your/project"] }+ }+}```------## Git intelligence--repowise mines your git history (per-file, configurable depth) to produce signals no static analysis can find.--**Hotspots** — files in the top 25% of both churn and complexity. These are where bugs live. Flagged in the dashboard, in CLAUDE.md, and surfaced by `get_risk()` before Claude Code touches them.--**Ownership** — `git blame` aggregated into ownership percentages per author. Know who to ping. Know where knowledge silos exist.+> **Init time:** the graph, git, dead-code, and code-health layers build in+> minutes with **zero LLM calls** — run `repowise init --index-only` for a+> queryable index almost immediately. The one-time cost is the documentation+> layer (LLM-generated wiki pages, can run in the background). After that, every+> commit-triggered update takes **under 30 seconds** and only regenerates the+> pages your change touched.-**Co-change pairs** — files that change together in the same commit without an import link. Hidden coupling that AST parsing cannot detect. `get_context()` surfaces co-change partners alongside direct dependencies.--**Bus factor** — files owned >80% by a single author. Shown in the ownership view. Surfaced in CLAUDE.md as knowledge risk.--**Significant commits** — the last 10 meaningful commit messages per file (filtered: no merges, no dependency bumps, no lint) are included in generation prompts. The LLM explains *why* code is structured the way it is.--**Contributor profiles** — every author with commits gets a profile page: modules they own, top files, co-authors, commit category mix (feat / fix / refactor / docs / test / chore / perf), silo modules they're solely on, bus-factor risk files, and dead-code burden. Surfaced via `/repos/<id>/owners` in the dashboard and linked from every owner reference.--**Module health** — composite 0–100 score per top-level module derived from silo penalty, hotspot density, dead-code percentage, average churn, doc coverage, and median bus factor. Surfaced on the Risk page and the per-module detail page, with cross-links to owners, hotspots, and governing decisions.--**Reviewer suggestions** — paste a PR file list into Blast Radius and get a ranked list of likely reviewers, scored by direct authorship (×1.0), co-change partners (×0.5), and recency (×0.4), capped at the 5 strongest co-change signals per file.+**Docs:** [Quickstart](docs/QUICKSTART.md) · [User Guide](docs/USER_GUIDE.md) · [CLI Reference](docs/CLI_REFERENCE.md) · [MCP Tools](docs/MCP_TOOLS.md) · [Workspaces](docs/WORKSPACES.md) · [Auto-Sync](docs/AUTO_SYNC.md) · [Config](docs/CONFIG.md)----## Dead code detection--Pure graph traversal and SQL. No LLM calls. Completes in under 10 seconds for any repo size.--```-repowise dead-code-- 23 findings · 4 safe to delete+## Nine MCP tools- ✓ utils/legacy_parser.ts file 1.00 safe to delete- ✓ auth/session.ts file 0.92 safe to delete- ✓ helpers/formatDate export 0.71 safe to delete- ✓ types/OldUser export 0.68 safe to delete- ✗ analytics/v1/tracker.ts file 0.41 recent activity — review first-```+Most tools are designed around data entities — one module, one file, one symbol —+forcing agents into long chains of sequential calls. repowise tools are designed+around **tasks**: pass multiple targets in one call, get complete context back.+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`.-Conservative by design. `safe_to_delete` requires confidence ≥ 0.70 and excludes dynamically-loaded patterns (`*Plugin`, `*Handler`, `*Adapter`, `*Middleware`). Dynamic import detection (`importlib.import_module()`, `__import__()`) and framework awareness (Flask/FastAPI/Django/Rails/Laravel/TYPO3 routes and convention files) further reduce false positives. repowise surfaces candidates. Engineers decide.+| Tool | What only this tool answers |+|---|---|+| `get_overview()` | Architecture summary, module map, entry points, git health, community summary. First call on any unfamiliar codebase. |+| `get_answer(question)` | Hybrid retrieval (FTS + vector via RRF) + PageRank bias + 1-hop graph expansion → a cited answer with calibrated `retrieval_quality`. Returns structured `best_guesses` on low confidence. Collapses search → read → reason into one round-trip. |+| `get_context(targets, include?)` | Triage card for files / modules / symbols: title, summary, signatures, `hotspot` bit, `governing_decisions`, and `symbol_id`s. `include` opens callers/callees, ownership, metrics, decisions, full_doc. Batch many targets. |+| `get_symbol("file.py::Name")` | Raw source bytes for one indexed symbol with exact line bounds — cheaper and safer than `Read` + offset math. |+| `search_codebase(query, kind?)` | Semantic search over the wiki, filterable by `kind` (implementation / test / config / doc), tagging each result's `search_method`. |+| `get_risk(targets, changed_files?)` | Hotspot scores, dependents, co-change partners, ownership, test gaps, security signals. Pass `changed_files` for PR mode → a `directive` block (`will_break`, `missing_cochanges`, `missing_tests`, `governance_risk`). |+| `get_why(query?, targets?)` | Architectural decision records, status, evidence spans, and the supersession **lineage chain**. Falls back to git archaeology when no ADRs exist. |+| `get_dead_code(...)` | Unreachable code by confidence tier with cleanup-impact estimates; cross-repo consumer detection in workspace mode. |+| `get_health(targets?, include?)` | 25-biomarker scores per file. Dashboard mode → KPIs + lowest-scoring files + module rollup; targeted mode → per-file findings. `include`: coverage, refactoring, trend. |++Worked example (*"Add rate limiting to all API endpoints"* in 5 calls instead of+~30 greps+reads) and the full reference: **[docs/MCP_TOOLS.md →](docs/MCP_TOOLS.md)**----## Architectural decisions--```bash-repowise decision add # guided interactive capture (~90 seconds)-repowise decision confirm # review auto-proposed decisions from git history-repowise decision health # stale, conflicting, ungoverned hotspots-```--```-repowise decision health-- 2 stale decisions- → "JWT over sessions" — auth/service.ts rewritten 3 months ago, decision may be outdated- → "EventBus in-process only" — 8 of 14 governed files changed since recorded-- 1 conflict- → payments/: two decisions with overlapping scope and contradictory rationale+## Local dashboard- 1 ungoverned hotspot- → payments/processor.ts — 47 commits/month, no architectural decisions recorded-```+`repowise serve` starts a full web UI alongside the MCP server — no separate+setup.-Decisions are linked to graph nodes, tracked for staleness as code evolves, connected by typed `supersedes` / `refines` / `conflicts_with` edges, and surfaced by `get_why()` (with the full lineage chain) whenever Claude Code touches governed files. An incremental `repowise update` re-checks decisions against the diff: a commit that reverses one auto-records a supersession edge and re-renders the pages it governed in the same run.+<img src=".github/assets/webui.gif" alt="repowise web UI" width="100%" />-The "why" usually walks out the door — when a teammate leaves, or when you reopen your own repo six months later. Decision intelligence keeps it in the codebase.+Highlights: **Chat** (natural-language Q&A) · **Docs** (wiki with Mermaid ++graph sidebar) · **Graph** (interactive, 2,000+ nodes, community coloring, path+finder) · **C4 Architecture** (Context → Containers → Components) · **Risk**+(hotspots, ownership heatmap, module health, dead code, blast radius) ·+**Contributors** (per-author profiles) · **Decisions** (evidence drawer,+evolution timeline, decision-graph) · **Health** (biomarker scores, coverage,+trends) · **Security** (local pattern scan) · **Costs** · **Workspace**+(cross-repo contracts & co-changes). Full view-by-view list in+[docs/USER_GUIDE.md](docs/USER_GUIDE.md).---@@ -460,185 +308,77 @@ The "why" usually walks out the door — when a teammate leaves, or when you reo| | repowise | Google Code Wiki | DeepWiki | Swimm | CodeScene ||---|---|---|---|---|---|| Self-hostable, open source | ✅ AGPL-3.0 | ❌ cloud only | ❌ cloud only | ❌ Enterprise only | ✅ Docker |-| Auto-generated documentation | ✅ | ✅ Gemini | ✅ | ✅ PR2Doc | ❌ || Private repo — no cloud | ✅ | ❌ in development | ❌ OSS forks only | ✅ Enterprise tier | ✅ |-| Dead code detection | ✅ | ❌ | ❌ | ❌ | ❌ |-| Code health score (1–10) | ✅ 15 biomarkers | ❌ | ❌ | ❌ | ✅ 25–30 |-| Brain Method detection | ✅ | ❌ | ❌ | ❌ | ✅ |-| Complexity biomarkers | ✅ native tree-sitter | ❌ | ❌ | ❌ | ✅ |-| Test coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ | ❌ |-| Untested hotspot detection | ✅ coverage × hotspot | ❌ | ❌ | ❌ | ❌ |-| DRY violation detection | ✅ native (no npm) | ❌ | ❌ | ❌ | ✅ |-| Health trend tracking | ✅ rolling 50 snapshots | ❌ | ❌ | ❌ | ✅ |-| Declining health alerts | ✅ | ❌ | ❌ | ❌ | ✅ |+| Auto-generated documentation | ✅ | ✅ Gemini | ✅ | ✅ PR2Doc | ❌ |+| MCP server for AI agents | ✅ 9 tools | ❌ | ✅ 3 tools | ✅ | ✅ |+| Proactive agent hooks | ✅ Pre + PostToolUse | ❌ | ❌ | ❌ | ❌ |+| Auto-generated CLAUDE.md | ✅ | ❌ | ❌ | ❌ | ❌ |+| Code health score (1–10) | ✅ 25 biomarkers | ❌ | ❌ | ❌ | ✅ 25–30 |+| Brain Method / LCOM4 / god class | ✅ | ❌ | ❌ | ❌ | ✅ |+| Test-coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ | ❌ |+| Untested-hotspot detection | ✅ coverage × hotspot | ❌ | ❌ | ❌ | ❌ |+| Health trend + declining alerts | ✅ rolling snapshots | ❌ | ❌ | ❌ | ✅ || Refactoring recommendations | ✅ deterministic | ❌ | ❌ | ❌ | ✅ |-| Git intelligence (hotspots, ownership, co-changes) | ✅ | ❌ | ❌ | ❌ | ✅ |+| Git intelligence (hotspots, ownership, co-change) | ✅ | ❌ | ❌ | ❌ | ✅ || Bus factor analysis | ✅ | ❌ | ❌ | ❌ | ✅ |+| Dead code detection | ✅ | ❌ | ❌ | ❌ | ❌ || Architectural decision records | ✅ | ❌ | ❌ | ❌ | ❌ || Multi-repo workspace intelligence | ✅ co-changes, contracts, federated MCP | ❌ | ❌ | ❌ | ❌ |-| MCP server for AI agents | ✅ 9 tools | ❌ | ✅ 3 tools | ✅ | ✅ |-| Proactive agent hooks | ✅ PreToolUse + PostToolUse | ❌ | ❌ | ❌ | ❌ |-| Auto-generated CLAUDE.md | ✅ | ❌ | ❌ | ❌ | ❌ |-| Doc freshness scoring | ✅ | ❌ | ❌ | ⚠️ staleness only | ❌ |-| Incremental updates on commit | ✅ <30s | ✅ | ❌ | ✅ | ✅ |-| Local dashboard / frontend | ✅ | ❌ | ❌ | ❌ IDE only | ✅ |-| Free for internal use | ✅ | ✅ public repos | ✅ public repos | ❌ | ❌ |+| Local dashboard | ✅ | ❌ | ❌ | ❌ IDE only | ✅ |-**The honest summary:**--- **vs Google Code Wiki** — Google's offering (launched Nov 2025) is cloud-only with no private repo support yet. Gemini-powered docs are strong, but there's no git behavioral intelligence, no dead code detection, no MCP server, and no architectural decisions.-- **vs DeepWiki** — Cloud-only, closed source (community self-hostable forks exist). Strong docs and Q&A, with a basic 3-tool MCP server. No git analytics, no dead code, no decisions.-- **vs Swimm** — Swimm's strength is keeping manually-written docs linked to code snippets with staleness detection. No graph, no git behavioral analytics, no dead code, no MCP by default. Enterprise pricing for private hosting.-- **vs CodeScene** — CodeScene has excellent git intelligence (hotspots, co-changes, ownership, bus factor). No documentation generation, no RAG, no architectural decisions. Closed source, per-author pricing.--repowise is the intersection: CodeScene-level git intelligence + auto-generated documentation + agent-native MCP + architectural decisions + multi-repo workspace intelligence, self-hostable and open source.+**repowise is the intersection:** behavioral git intelligence + a defect-validated+code-health score + auto-generated docs + agent-native MCP + architectural+decisions + multi-repo workspace intelligence — self-hostable and open source.+Detailed breakdown: [docs/COMPETITIVE_ANALYSIS.md](docs/COMPETITIVE_ANALYSIS.md).----## Hosted version — for teams--[**repowise.dev**](https://www.repowise.dev) is the same engine, fully managed. Now at feature parity with self-hosted: every CLI command, every MCP tool, the full dashboard. Connect your IDE to the hosted MCP endpoint and skip the install entirely.--We use it on our own codebase — see the live snapshot of repowise indexing itself: [**dogfood example →**](https://www.repowise.dev/s/5a6b93fa9a69). More public repos indexed on the [**explore page →**](https://www.repowise.dev/explore).--**What you get on top of self-hosting:**-- **Zero ops** — managed deploys, managed webhooks, auto re-index on every commit, no infrastructure-- **Hosted MCP endpoint** — point Claude Code (or any MCP client) at one URL, no local server to run-- **Repowise PR Bot** — free GitHub App that posts one deterministic comment per pull request (hotspot touches, hidden coupling, declining health, dead code). Zero LLM calls — same engine, just running on your PRs. [Install →](https://github.com/apps/repowise-bot) · [Learn more →](https://www.repowise.dev/bot)-- **CVE-aware security layer** — on top of the local pattern scan, the hosted version adds CVE-aware vulnerability detection, dependency risk surfacing, and cross-repo security anti-pattern analysis-- **Cross-repo intelligence at scale** — federated hotspots, dead code, and ownership across all your repos in one dashboard-- **Integrations** *(rolling out)* — Slack alerts, Jira/Linear decision linking, Confluence/Notion doc sync, PagerDuty escalation--Full breakdown of what's GA, in development, and planned — plus on-prem topology and pricing models: **[docs/COMMERCIAL.md](docs/COMMERCIAL.md)**+## For teams & enterprises-[Get in touch →](https://www.repowise.dev/#contact) · [[email protected]](mailto:[email protected])+[**repowise.dev**](https://www.repowise.dev) is the same engine, fully managed —+at feature parity with self-hosted: every CLI command, every MCP tool, the full+dashboard. We dogfood it on our own codebase: [live snapshot →](https://www.repowise.dev/s/5a6b93fa9a69) · [explore public repos →](https://www.repowise.dev/explore).------## CLI reference+**On top of self-hosting:**+- **Zero ops** — managed deploys & webhooks, auto re-index on every commit.+- **Hosted MCP endpoint** — point any MCP client at one URL, no local server.+- **Repowise PR Bot** — free GitHub App, one deterministic comment per PR+ (hotspot touches, hidden coupling, declining health, dead code), zero LLM calls.+ [Install →](https://github.com/apps/repowise-bot) · [Learn more →](https://www.repowise.dev/bot)+- **CVE-aware security layer**, **cross-repo intelligence at scale**, and+ **integrations** (Slack, Jira/Linear, Confluence/Notion, PagerDuty) *(rolling out)*.-```bash-# Core-repowise init [PATH] # index codebase (one-time, offers hook setup)-repowise init --index-only # graph + git + dead code, no LLM, no cost-repowise init -x vendor/ -x proto/ # exclude patterns (gitignore syntax)-repowise init --include-submodules # include git submodule directories-repowise update [PATH] # incremental update (<30 seconds)-repowise update --workspace # update all stale repos in workspace-repowise update --repo backend # update a specific workspace repo-repowise serve [PATH] # MCP server + local dashboard-repowise watch [PATH] # auto-update on file save-repowise watch --workspace # auto-update all workspace repos--# Auto-sync hooks-repowise hook install # install post-commit hook (current repo)-repowise hook install --workspace # install for all workspace repos-repowise hook status # check if hooks are installed-repowise hook uninstall # remove hooks--# Query-repowise query "<question>" # ask anything from the terminal-repowise search "<query>" # semantic search over the wiki-repowise status # coverage, freshness, dead code summary--# Code health-repowise health # KPIs + lowest-scoring files-repowise health --coverage cov.lcov # ingest coverage, light up untested-hotspot-repowise health --refactoring-targets # ranked by impact / effort-repowise health --trend # last 10 snapshots + declining/predicted-decline alerts--# Change risk-repowise risk # score HEAD's defect risk (0-10)-repowise risk main..HEAD # score a branch / PR range as one change--# Dead code-repowise dead-code # full report-repowise dead-code --safe-only # only safe-to-delete findings-repowise dead-code --min-confidence 0.8 # raise the confidence threshold-repowise dead-code --include-internals # include private/underscore symbols-repowise dead-code --include-zombie-packages # include unused declared packages-repowise dead-code resolve <id> # mark resolved / false positive--# Cost tracking-repowise costs # total LLM spend to date-repowise costs --by operation # grouped by operation type-repowise costs --by model # grouped by model-repowise costs --by day # grouped by day--# Decisions-repowise decision add # record a decision (interactive)-repowise decision list # all decisions, filterable-repowise decision confirm <id> # confirm a proposed decision-repowise decision health # stale, conflicts, ungoverned hotspots--# Editor files-repowise generate-claude-md # regenerate CLAUDE.md--# Proactive hooks (auto-installed by init — not called manually)-repowise augment # enriches agent tool calls with graph context--# Utilities-repowise export [PATH] # export wiki as markdown files-repowise export --full --format json # full export with decisions, dead code, hotspots-repowise doctor # check setup, API keys, store drift-repowise doctor --repair # check and fix detected store mismatches-repowise reindex # rebuild vector store (no LLM calls)-```-------## Supported languages--| Tier | Languages | What works |-|------|-----------|------------|-| **Full** | Python · TypeScript · JavaScript · Java · Go · Rust · C++ · C# | AST parsing, import resolution, named bindings, call resolution, heritage extraction, docstrings; multi-project workspace resolvers (`.csproj`/`.sln` for C#, `Cargo.toml [workspace]` for Rust, `go.mod` multi-module, `package.json` workspaces, etc.); framework-aware edges (Django, FastAPI, Flask, ASP.NET, Spring Boot, Express/NestJS, Gin/Echo/Chi, Axum/Actix); per-language dynamic-hint extractors for runtime-resolved DI / reflection / plugins |-| **Good** | C · Kotlin · Ruby · Swift · Scala · PHP | AST parsing, import resolution, named bindings, call resolution, heritage (mixins, derive, extensions, traits), docstrings, dedicated workspace-aware resolvers (Gradle subprojects, Rails / Zeitwerk, SPM, SBT/Mill, composer PSR-4); Rails / Laravel / TYPO3 framework edges for Ruby and PHP; per-language dynamic-hint extractors |-| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · SQL · Terraform | Included in the file tree; special handlers extract endpoints/targets where applicable |--14 languages with full AST support, 8 of them at the Full tier. Adding a new language requires one `.scm` tree-sitter query file and one config entry. No changes to the parser core. See [Language Support](docs/LANGUAGE_SUPPORT.md) for details.+What's GA / in development / planned, on-prem topology, SSO/SCIM/RBAC, and+pricing: **[docs/COMMERCIAL.md](docs/COMMERCIAL.md)** · [Get in touch →](https://www.repowise.dev/#contact)---## Privacy-**Self-hosted:** Your code never leaves your infrastructure. No telemetry. No analytics. Zero.--**BYOK:** Bring your own Anthropic or OpenAI API key. We never see your LLM calls. Zero data retention via Anthropic's API policy — your code is never used to train any model.--**What is stored:** NetworkX graph (file and symbol relationships, communities, call edges with confidence), LanceDB embeddings (non-reversible vectors), generated wiki pages, git metadata. Raw source code is processed transiently and never persisted.--**Fully offline:** Ollama for LLM + local embedding models = zero external API calls.+- **Self-hosted:** your code never leaves your infrastructure. No telemetry. No analytics.+- **BYOK:** bring your own Anthropic / OpenAI key. We never see your LLM calls. Zero data retention via Anthropic's API policy.+- **What's stored:** the NetworkX graph, LanceDB embeddings (non-reversible vectors), generated wiki pages, git metadata. Raw source is processed transiently and never persisted.+- **Fully offline:** Ollama + a local embedding model = zero external API calls.----## Configuration--`repowise init` generates `.repowise/config.yaml`. Key options:--```yaml-provider: anthropic # anthropic | openai | openrouter | gemini | deepseek | ollama | litellm | mock-model: claude-sonnet-4-5-embedding_model: voyage-3-reasoning: auto # auto | off | minimal--git:- co_change_commit_limit: 500- blame_enabled: true+## CLI & configuration-dead_code:- enabled: true- safe_to_delete_threshold: 0.7--maintenance:- cascade_budget: 30 # max pages fully regenerated per commit- background_regen_schedule: "0 2 * * *"+```bash+repowise init [PATH] # index codebase (one-time; --index-only skips LLM)+repowise serve [PATH] # MCP server + local dashboard+repowise update [PATH] # incremental update (<30s; --workspace for all repos)+repowise query "<q>" # ask anything from the terminal+repowise health # code-health KPIs + lowest-scoring files+repowise risk main..HEAD # score a branch / PR range for defect risk+repowise dead-code # unreachable-code report+repowise doctor # check setup, API keys, store drift```-`reasoning` applies to documentation generation. `auto` preserves provider-defaults; explicit `off` / `minimal` modes are translated only by providers and-models that support them, otherwise repowise fails before making an API call.--Full configuration reference: [docs/CONFIG.md](docs/CONFIG.md)+`repowise init` generates `.repowise/config.yaml` (provider, model, embedder,+reasoning mode, exclude patterns, git commit depth). Full command set:+**[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)** · config reference:+**[docs/CONFIG.md](docs/CONFIG.md)**.---@@ -652,20 +392,8 @@ uv run repowise --versionuv run pytest tests/unit/```-Run commands through uv without activating the environment:--```bash-uv run repowise --help-```--Or activate the local environment created by `uv sync`:--```bash-source .venv/bin/activate-repowise --help-```--Full guide including how to add languages and LLM providers: [CONTRIBUTING.md](CONTRIBUTING.md)+Full guide, including how to add languages and LLM providers:+[CONTRIBUTING.md](CONTRIBUTING.md).---@@ -673,7 +401,10 @@ Full guide including how to add languages and LLM providers: [CONTRIBUTING.md](CAGPL-3.0. Free for individuals, teams, and companies using repowise internally.-For commercial licensing — the enterprise security & compliance layer, SSO/SCIM, RBAC, workflow integrations, priority support and SLA, or embedding repowise in a product without AGPL obligations — see **[docs/COMMERCIAL.md](docs/COMMERCIAL.md)** or contact [[email protected]](mailto:[email protected]).+For commercial licensing — the enterprise security & compliance layer, SSO/SCIM,+RBAC, workflow integrations, priority support and SLA, or embedding repowise in a+product without AGPL obligations — see **[docs/COMMERCIAL.md](docs/COMMERCIAL.md)**+or contact [[email protected]](mailto:[email protected]).---diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.mdindex 27e37ab82..451aa247f 100644--- a/docs/CLI_REFERENCE.md+++ b/docs/CLI_REFERENCE.md@@ -54,6 +54,7 @@ In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (| `--model` | Model name override (e.g., `claude-sonnet-4-6`) || `--embedder` | Embedder for semantic search: `gemini`, `openai`, `mock` || `--index-only` | Skip LLM generation. Only parse, build graph, and index git. Free. |+| `--mode` | Pipeline depth: `standard` (default) or `fast` (graph + essential-git only — no per-file blame/co-change, no LLM — for very large repos; upgrade later with `update --full`). || `--dry-run` | Show generation plan and cost estimate without running. || `--test-run` | Generate docs for only the top 10 files (by PageRank). || `--skip-tests` | Exclude test files from doc generation. |@@ -261,9 +262,34 @@ repowise dead-code resolve <id> # mark resolved / false positive---+### `repowise risk [REVSPEC]`++Just-in-time change-risk scoring for a commit or diff range. Scores the defect+risk of a change (0–10) from the same calibrated signals the code-health layer+uses — no LLM calls. `REVSPEC` defaults to `HEAD`; pass a `base..head` range to+score a whole branch / PR as one change.++**Options:**++| Flag | Description |+|------|-------------|+| `--path` | Path to the git repository (default: current directory) |+| `--ext` | Comma-separated file suffixes to count (e.g. `.py` or `.ts,.tsx`) |+| `--format` | Output format: `table` (default) or `json` |++```bash+repowise risk # score HEAD+repowise risk main..HEAD # score a branch / PR range as one change+repowise risk --ext .ts,.tsx # restrict to specific suffixes+```++See [`docs/CHANGE_RISK.md`](./CHANGE_RISK.md) for the scoring model.++---+### `repowise health [PATH]`-Compute per-file code-health scores from twelve deterministic biomarkers (CCN, nesting, brain methods, duplication, untested hotspots, organizational risk). Zero LLM calls — pure Python over tree-sitter + git data. See [`docs/CODE_HEALTH.md`](./CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](./architecture/code-health.md) for the internals.+Compute per-file code-health scores from 25 deterministic biomarkers (McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clone detection, untested hotspots, coverage gradient, function/ownership/churn/change-entropy organizational risk, test-quality smells, and more). Zero LLM calls — pure Python over tree-sitter + git data. See [`docs/CODE_HEALTH.md`](./CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](./architecture/code-health.md) for the internals.**Options:**@@ -438,7 +464,7 @@ repowise mcp --transport stdio # for Claude Code, Cursor, etc.repowise mcp --transport sse --port 7338 # for web clients```-See [MCP Tools](MCP_TOOLS.md) for all 7 exposed tools.+See [MCP Tools](MCP_TOOLS.md) for all 9 exposed tools.---@@ -503,6 +529,24 @@ repowise doctor --workspace --repair # also drop dead entries / sync drift---+### `repowise delete [REPO_ID]`++Delete a repository's index and all stored intelligence (wiki, graph, embeddings,+git metadata). Does **not** touch your source files. Prompts for confirmation+unless `--force` is passed.++| Flag | Description |+|------|-------------|+| `--force` / `-f` | Skip the confirmation prompt |+| `--path` / `-p` | Path to the repository directory |++```bash+repowise delete # delete the current repo's index (prompts)+repowise delete <repo-id> --force # delete a specific repo's index, no prompt+```++---+### `repowise augment`Hook-driven context enrichment engine. Not meant to be called manually — invoked by Claude Code hooks installed during `repowise init`.diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.mdindex 94aeb4430..a937c5948 100644--- a/docs/CODE_HEALTH.md+++ b/docs/CODE_HEALTH.md@@ -1,6 +1,6 @@# Code Health-Repowise computes a 1–10 health score for every file in your repo from twenty-four+Repowise computes a 1–10 health score for every file in your repo from twenty-fivedeterministic biomarkers — McCabe complexity, deep nesting, brain methods,class cohesion (LCOM4), god classes, clone detection, untested hotspots,function-level churn, code-age volatility,diff --git a/docs/COMMERCIAL.md b/docs/COMMERCIAL.mdindex ced2a16a5..89855f0bd 100644--- a/docs/COMMERCIAL.md+++ b/docs/COMMERCIAL.md@@ -41,13 +41,13 @@ scale, in a regulated or security-sensitive environment**:All of the following ship in `pip install repowise` today, free for internal use.-- **Five intelligence layers** — Graph (tree-sitter AST across 14 languages, two-tier+- **Five intelligence layers** — Graph (tree-sitter AST across 15 languages, two-tierdependency graph, call resolution, heritage extraction, Leiden communities,PageRank / betweenness / SCC), Git (hotspots, ownership, co-change pairs, busfactor, significant commits, contributor profiles, module health), Documentation(LLM-generated wiki, freshness scoring, RAG search), Decision (architecturaldecision records linked to graph nodes, staleness tracking), and Code Health- (fifteen deterministic biomarkers, 1–10 score per file, coverage ingestion, trend+ (25 deterministic biomarkers, 1–10 score per file, coverage ingestion, trendalerts).- **Nine task-shaped MCP tools** — `get_overview`, `get_answer`, `get_context`,`get_symbol`, `search_codebase`, `get_risk`, `get_why`, `get_dead_code`,@@ -77,11 +77,11 @@ All of the following ship in `pip install repowise` today, free for internal use## 3. First-class language coverage-Repowise treats **8 languages at Full tier** — Python, TypeScript, JavaScript, Java,-Go, Rust, C++, and **C#** — with AST parsing, import resolution, named bindings, call-resolution, heritage extraction, multi-project workspace resolvers, framework-aware-edges, and per-language dynamic-hint extractors. A further 6 languages (C, Kotlin,-Ruby, Swift, Scala, PHP) sit at Good tier.+Repowise treats **9 languages at Full tier** — Python, TypeScript, JavaScript, Java,+Kotlin, Go, Rust, C++, and **C#** — with AST parsing, import resolution, named+bindings, call resolution, heritage extraction, multi-project workspace resolvers,+framework-aware edges, and per-language dynamic-hint extractors. A further 5 languages+(C, Ruby, Swift, Scala, PHP) sit at Good tier.For estates built on a particular stack, the relevant Full-tier capabilities areworth calling out. For **.NET**, as one example:diff --git a/docs/CONFIG.md b/docs/CONFIG.mdnew file mode 100644index 000000000..a4069fd7a--- /dev/null+++ b/docs/CONFIG.md@@ -0,0 +1,227 @@+# Configuration++The `.repowise/` directory, provider setup, API keys, and what's customizable.++---++## The `.repowise/` directory++Everything repowise knows about your repository lives here. It's created at the+repo root on first `init`.++```+.repowise/+├── wiki.db # SQLite database — all pages, symbols, graph, git metadata, decisions+├── lancedb/ # Vector search index (LanceDB)+├── config.yaml # Provider, model, embedder, exclude patterns+├── state.json # Last sync commit, page counts, token usage+├── mcp.json # MCP server configuration+└── .env # API keys (gitignored automatically)+```++repowise adds `.repowise/` to your `.gitignore` automatically. The directory+should not be committed — it's a local cache, not a source of truth.++---++## `config.yaml`++The main configuration file. Created after first `init`, updated when you pass+`--commit-limit` or `--follow-renames` flags.++```yaml+provider: anthropic # LLM provider+model: claude-sonnet-4-6 # Model identifier+embedder: gemini # Embedding provider+reasoning: auto # auto | off | minimal+exclude_patterns: # Gitignore-style patterns+ - vendor/+ - "*.generated.*"+ - proto/+commit_limit: 500 # Max commits per file for git analysis+follow_renames: false # Track file renames in git history+```++You can edit this file directly. Changes take effect on the next `init`,+`update`, or `serve` run.++`reasoning` controls documentation-generation calls for reasoning-capable chat+models. `auto` preserves provider defaults. `off` disables Qwen3-style thinking+for OpenAI-compatible vLLM/SGLang endpoints (sends+`extra_body.chat_template_kwargs.enable_thinking=false`) and maps to OpenRouter's+`reasoning.effort=none` for effort-capable OpenRouter model families. `minimal`+requests OpenAI's lowest supported reasoning effort for supported OpenAI+reasoning models and maps to OpenRouter's `reasoning.effort=minimal`. Providers+or models that cannot translate an explicit mode fail before making an API call.++> **Code-health rules** are configured separately in+> `.repowise/health-rules.json` (per-file biomarker overrides) — see+> [CODE_HEALTH.md](CODE_HEALTH.md#configuration).++---++## LLM providers++### Anthropic (Claude)++```bash+export ANTHROPIC_API_KEY="sk-ant-..."+```++| Model | Notes |+|-------|-------|+| `claude-sonnet-4-6` | Default — best balance of quality and cost |+| `claude-opus-4-6` | Highest quality, higher cost |+| `claude-haiku-4-5-20251001` | Fastest, lowest cost |++```bash+repowise init --provider anthropic --model claude-haiku-4-5-20251001+```++### OpenAI (GPT)++```bash+export OPENAI_API_KEY="sk-..."+repowise init --provider openai --model gpt-4.1+```++For an OpenAI-compatible Qwen3 endpoint served by vLLM or SGLang:++```bash+export OPENAI_BASE_URL="http://localhost:8000/v1"+repowise init --provider openai --model qwen3 --reasoning off+```++For OpenRouter:++```bash+repowise init --provider openrouter --model openai/gpt-5 --reasoning minimal+repowise init --provider openrouter --model x-ai/grok-4 --reasoning off+```++### Gemini (Google)++```bash+export GEMINI_API_KEY="AI..." # or GOOGLE_API_KEY+repowise init --provider gemini+```++Gemini is also the default embedding provider when `GEMINI_API_KEY` is set.++### Ollama (local — no API key)++```bash+export OLLAMA_BASE_URL="http://localhost:11434"+repowise init --provider ollama --model llama3.2+```++### LiteLLM (100+ providers)++```bash+pip install "repowise[litellm]"+export LITELLM_API_KEY="..."+repowise init --provider litellm --model azure/gpt-4+```++### Provider auto-detection++If you don't pass `--provider`, repowise detects your provider by checking, in+order:++1. `REPOWISE_PROVIDER` environment variable+2. `provider` in `.repowise/config.yaml`+3. API key env vars: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `OLLAMA_BASE_URL` → `GEMINI_API_KEY`++---++## Embeddings (for semantic search)++The embedder is separate from the LLM provider.++| Embedder | Env var | Notes |+|----------|---------|-------|+| `gemini` | `GEMINI_API_KEY` | Default when key is present |+| `openai` | `OPENAI_API_KEY` | OpenAI `text-embedding-3-small` |+| `mock` | — | Dummy embeddings, no semantic search |++```bash+repowise init --embedder openai+repowise reindex --embedder gemini # switch embedder and rebuild index+```++---++## BYOK (Bring Your Own Key)++API keys are resolved in this order:++1. **Environment variable** — set before running repowise+2. **`.repowise/.env`** — persisted from interactive setup, loaded automatically+3. **Interactive prompt** — repowise asks during `init` if no key is found, then saves to `.repowise/.env`++The `.repowise/.env` file is gitignored automatically.++---++## Environment variables++| Variable | Description |+|----------|-------------|+| `ANTHROPIC_API_KEY` | Anthropic API key |+| `OPENAI_API_KEY` | OpenAI API key |+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Google Gemini API key |+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |+| `LITELLM_API_KEY` | LiteLLM proxy key |+| `REPOWISE_PROVIDER` | Override provider (skips auto-detection) |+| `REPOWISE_EMBEDDER` | Embedder: `gemini`, `openai`, or `mock` |+| `REPOWISE_DB_URL` | Use PostgreSQL instead of SQLite (e.g. `postgresql+asyncpg://...`) |+| `REPOWISE_HOST` | API server host (default: `127.0.0.1`) |+| `REPOWISE_PORT` | API server port (default: `7337`) |+| `REPOWISE_MCP_PORT` | MCP SSE server port (default: `7338`) |+| `REPOWISE_API_URL` | Frontend only — backend URL for the web UI (default: `http://localhost:7337`) |++---++## Exclude patterns++repowise respects your `.gitignore` automatically (same `gitwildmatch` format git+uses). On top of that, add extra patterns via `--exclude` / `-x`:++```bash+repowise init -x vendor/ -x "*.generated.ts" -x proto/ -x "**/*.pb.go"+```++Patterns are saved to `config.yaml` and applied on subsequent `update` runs. You+can also create a `.repowiseIgnore` file (same gitignore syntax) at the repo root+or in any subdirectory for more granular control.++Built-in exclusions (always applied): `.git/`, `.repowise/`, `node_modules/`,+`__pycache__/`, `*.pyc`, `.venv/`, binary files, lockfiles, and minified assets.++Use `--skip-tests` to exclude test files and `--skip-infra` to exclude+Dockerfiles, Makefiles, and shell scripts.++---++## Submodules++Git submodule directories are excluded by default. To include them:++```bash+repowise init --include-submodules+```++repowise reads `.gitmodules` to detect submodule paths.++---++## PostgreSQL++For team deployments or larger repos, use PostgreSQL instead of SQLite:++```bash+export REPOWISE_DB_URL="postgresql+asyncpg://user:pass@localhost:5432/repowise"+repowise init+```++The schema is managed with Alembic migrations.diff --git a/docs/INTELLIGENCE_LAYERS.md b/docs/INTELLIGENCE_LAYERS.mdnew file mode 100644index 000000000..cdcb08745--- /dev/null+++ b/docs/INTELLIGENCE_LAYERS.md@@ -0,0 +1,316 @@+# The Five Intelligence Layers++repowise indexes your codebase **once**, builds five intelligence layers, then+keeps them in sync on every commit. This document is the deep dive — the README+gives the one-paragraph version of each layer and links here for the detail.++1. [Graph Intelligence](#graph-intelligence)+2. [Git Intelligence](#git-intelligence)+3. [Documentation Intelligence](#documentation-intelligence)+4. [Decision Intelligence](#decision-intelligence)+5. [Code Health Intelligence](#code-health-intelligence)++Two cross-cutting capabilities sit on top of the layers:++- [Proactive context enrichment — hooks](#proactive-context-enrichment--hooks)+- [Auto-sync — five ways to stay current](#auto-sync--five-ways-to-stay-current)+- [Auto-generated CLAUDE.md](#auto-generated-claudemd)++---++## Graph Intelligence++tree-sitter parses every file across 15 languages into a **two-tier dependency+graph** — file nodes and symbol nodes (functions, classes, methods). A 3-tier+call resolver with confidence scoring handles import aliases, barrel+re-exports, and namespace imports. Heritage extraction covers `extends`,+`implements`, trait impls, derive macros, mixins, and extension conformance.++- **Leiden community detection** finds logical modules even when your directory+ structure doesn't reflect them.+- **PageRank, betweenness centrality, SCC analysis, and execution-flow tracing**+ from entry points identify your most central, most coupled, and most+ traversed code.+- **Framework-aware edges** connect routes to handlers for Django, FastAPI,+ Flask, ASP.NET, Spring Boot, Express/NestJS, Gin/Echo/Chi, Axum/Actix, Rails,+ Laravel, and more.++See [`docs/LANGUAGE_SUPPORT.md`](LANGUAGE_SUPPORT.md) for per-language coverage+and [`docs/COMPUTED_GLOSSARY.md`](COMPUTED_GLOSSARY.md) for every derived metric.++---++## Git Intelligence++repowise mines your git history (per-file, configurable depth) to produce+signals no static analysis can find.++**Hotspots** — files in the top 25% of *both* churn and complexity. These are+where bugs live. Flagged in the dashboard, in `CLAUDE.md`, and surfaced by+`get_risk()` before your agent touches them.++**Ownership** — `git blame` aggregated into ownership percentages per author.+Know who to ping. Know where knowledge silos exist.++**Co-change pairs** — files that change together in the same commit *without* an+import link. Hidden coupling that AST parsing cannot detect. `get_context()`+surfaces co-change partners alongside direct dependencies.++**Bus factor** — files owned >80% by a single author. Shown in the ownership+view, surfaced in `CLAUDE.md` as knowledge risk.++**Significant commits** — the last 10 meaningful commit messages per file+(filtered: no merges, no dependency bumps, no lint) feed generation prompts, so+the wiki explains *why* code is structured the way it is.++**Contributor profiles** — every author with commits gets a profile page:+modules they own, top files, co-authors, commit category mix+(feat / fix / refactor / docs / test / chore / perf), silo modules they're+solely on, bus-factor risk files, and dead-code burden. Surfaced via+`/repos/<id>/owners` and linked from every owner reference.++**Module health** — a composite 0–100 score per top-level module derived from+silo penalty, hotspot density, dead-code percentage, average churn, doc+coverage, and median bus factor. Surfaced on the Risk page and the per-module+detail page, with cross-links to owners, hotspots, and governing decisions.++**Reviewer suggestions** — paste a PR file list into Blast Radius and get a+ranked list of likely reviewers, scored by direct authorship (×1.0), co-change+partners (×0.5), and recency (×0.4), capped at the 5 strongest co-change signals+per file.++---++## Documentation Intelligence++An LLM-generated wiki for every module and file, rebuilt **incrementally** on+every commit.++- **Coverage tracking** — what's documented and what isn't.+- **Freshness scoring** per page — confidence scores show how current each page+ is relative to the underlying code.+- **Semantic search via RAG** — hybrid retrieval (full-text + vector merged via+ Reciprocal Rank Fusion) with PageRank bias and 1-hop graph expansion.++A typical single-commit update touches 3–10 pages and completes in under 30+seconds — only the pages your change actually touched are regenerated.++---++## Decision Intelligence++**The layer nobody else has.** Architectural decisions mined from **eight+sources** — ADR files (Nygard/MADR), CHANGELOG entries, PR and squash-commit+bodies, inline markers, git archaeology, README/docs, centrality-bounded code+comments, and the LLM doc-generation pass itself — linked to the graph nodes+they govern and tracked for staleness as code evolves.++```python+# WHY: JWT chosen over sessions — API must be stateless for k8s horizontal scaling+# DECISION: All external API calls wrapped in CircuitBreaker after payment provider outages+# TRADEOFF: Accepted eventual consistency in preferences for write throughput+```++Every decision is **evidence-backed**: each rationale traces to a verbatim+source span (ADR quote, commit body, code comment), and an anti-hallucination+substring gate stamps each as **verified / fuzzy / unverified** — corroborating+sources raise confidence rather than overwrite each other.++Decisions form a **graph**: typed edges (`supersedes` / `refines` /+`relates_to` / `conflicts_with`) let `get_why()` answer *"why is auth structured+this way?"* with a lineage chain (sessions → JWT → OAuth2), auto-detect when a+new commit reverses an old decision, and flag two active decisions that+contradict each other.++These structured records surface everywhere your agent already looks —+`get_why()` for the full archaeology, governing decisions in `get_context()`, a+`governance_risk` flag in `get_risk()` PR review, a Key Decisions section in+`get_overview()`, and `ungoverned_hotspot` / `stale_governance` /+`contradictory_decision` findings in the code-health layer.++```bash+repowise decision add # guided interactive capture (~90 seconds)+repowise decision confirm # review auto-proposed decisions from git history+repowise decision health # stale, conflicting, ungoverned hotspots+```++```+repowise decision health++ 2 stale decisions+ → "JWT over sessions" — auth/service.ts rewritten 3 months ago, decision may be outdated+ → "EventBus in-process only" — 8 of 14 governed files changed since recorded++ 1 conflict+ → payments/: two decisions with overlapping scope and contradictory rationale++ 1 ungoverned hotspot+ → payments/processor.ts — 47 commits/month, no architectural decisions recorded+```++The "why" usually walks out the door — when a teammate leaves, or when you+reopen your own repo six months later. Decision intelligence keeps it in the+codebase.++---++## Code Health Intelligence++repowise computes a **1–10 health score for every file** from **25 deterministic+biomarkers** — McCabe complexity, deep nesting, brain methods, class cohesion+(LCOM4), god classes, native Rabin–Karp clone detection, untested hotspots,+function-level churn, code-age volatility, ownership dispersion, change entropy,+co-change scatter, prior-defect history, test-quality smells, and more.++**Zero LLM calls. Zero cloud requirement. Zero new runtime dependencies** —+pure Python over tree-sitter and git data, designed to finish in under 30+seconds on a 3,000-file repo.++The biomarker **weights are calibrated offline against a real defect corpus, not+hand-tuned**: each file is scored at the pre-window commit (T0, no leakage) and+an L2-logistic regression — with NLOC as an explicit control — fits each+biomarker's defect lift *beyond* file size. Only the learned constants ship; the+runtime stays fully deterministic.++```bash+repowise health # KPIs + lowest-scoring files+repowise health --coverage cov.lcov # ingest coverage, light up untested-hotspot+repowise health --refactoring-targets # ranked by impact / effort+repowise health --trend # last 10 snapshots + declining/predicted-decline alerts+repowise status # one-line summary in the status report+```++- **Coverage ingestion** — LCOV, Cobertura, Clover, or normalized JSON light up+ the test-coverage biomarkers (`untested_hotspot`, `coverage_gap`,+ `coverage_gradient`).+- **Trend tracking** — a rolling 50-row snapshot history powers `Declining+ Health` and `Predicted Decline` alerts.+- **Refactoring suggestions** — deterministic, rule-based, ranked by+ impact / effort, on the dashboard and via `get_health(include=["refactoring"])`.+- **Per-file overrides** via `.repowise/health-rules.json`.++Validated against real defect history — see+[`docs/CODE_HEALTH.md`](CODE_HEALTH.md) for the full user guide, the per-biomarker+reference, and the calibration story, and+[repowise-bench](https://github.com/repowise-dev/repowise-bench) for the+reproducible defect-prediction and head-to-head benchmarks.++---++## Proactive context enrichment — hooks++Most MCP tools are passive — the agent has to know to call them. repowise hooks+are **active**. They inject graph context into every search automatically, so+agents are smarter even when they don't explicitly ask for help. Hooks are+installed automatically during `repowise init`.++### PreToolUse — every search gets graph context++When your AI agent runs `Grep` or `Glob`, repowise intercepts the call and+enriches it with the top 3 related files — found via multi-signal search (symbol+name match, file-path match, full-text search on wiki content), ranked by+relevance then PageRank. No LLM calls. No network. Pure local SQLite queries.++```+[repowise] 3 related file(s) found:++ src/core/ingestion/graph.py+ Symbols: class:GraphBuilder, method:__init__, method:build+ Imported by: src/core/ingestion/__init__.py+ Uses: src/core/analysis/communities.py, src/core/analysis/execution_flows.py+```++### PostToolUse — auto-detect stale wiki++After a successful `git commit`, repowise checks whether the wiki is out of date+and notifies the agent:++```+[repowise] Wiki is stale — last indexed at commit a1b2c3d4, HEAD is now f9a0499b.+Run `repowise update` to refresh documentation and graph context.+```++---++## Auto-sync — five ways to stay current++repowise keeps your intelligence layers in sync with your code. Pick the method+that fits your workflow:++| Method | Command | Best for |+|--------|---------|----------|+| **Post-commit hook** | `repowise hook install` | Set-and-forget local development |+| **File watcher** | `repowise watch` | Active development without committing |+| **GitHub webhook** | Configure in repo settings | Teams, CI/CD |+| **GitLab webhook** | Configure in project settings | Teams, CI/CD |+| **Polling fallback** | Automatic with `repowise serve` | Safety net for missed webhooks |++```bash+repowise hook install # install post-commit hook (current repo)+repowise hook install --workspace # install for all workspace repos+repowise hook status # check if hooks are installed+repowise watch # or use the file watcher (single repo)+repowise watch --workspace # all workspace repos+```++A typical single-commit update touches 3–10 pages and completes in under 30+seconds. Full guide: [`docs/AUTO_SYNC.md`](AUTO_SYNC.md).++---++## Auto-generated CLAUDE.md++After every `repowise init` and `repowise update`, repowise regenerates your+`CLAUDE.md` from actual codebase intelligence — not a template. No LLM calls.+Under 5 seconds.++```bash+repowise generate-claude-md+```++The generated section includes: architecture summary, module map, hotspot+warnings, ownership map, hidden coupling pairs, active architectural decisions,+and dead-code candidates. A user-owned section at the top is never touched.++```markdown+<!-- REPOWISE:START — managed automatically, do not edit -->+## Architecture+Monorepo with 4 packages. Entry points: api/server.ts, cli/index.ts.++## Hotspots — handle with care+- payments/processor.ts — 47 commits/month, high complexity, primary owner: @sarah+- shared/events/EventBus.ts — 23 dependents, co-changes with all service listeners++## Active architectural decisions+- JWT over sessions (auth/service.ts) — stateless required for k8s horizontal scaling+- CircuitBreaker on all external calls — after payment provider outages in Q3 2024++## Hidden coupling (no import link, but change together)+- auth.ts ↔ middleware/session.ts — co-changed 31 times+<!-- REPOWISE:END -->+```++---++## Dead code detection++Pure graph traversal and SQL. No LLM calls. Completes in under 10 seconds for+any repo size.++```+repowise dead-code++ 23 findings · 4 safe to delete++ ✓ utils/legacy_parser.ts file 1.00 safe to delete+ ✓ auth/session.ts file 0.92 safe to delete+ ✓ helpers/formatDate export 0.71 safe to delete+ ✗ analytics/v1/tracker.ts file 0.41 recent activity — review first+```++Conservative by design. `safe_to_delete` requires confidence ≥ 0.70 and excludes+dynamically-loaded patterns (`*Plugin`, `*Handler`, `*Adapter`, `*Middleware`).+Dynamic-import detection (`importlib.import_module()`, `__import__()`) and+framework awareness (Flask/FastAPI/Django/Rails/Laravel/TYPO3 routes and+convention files) further reduce false positives. repowise surfaces candidates.+Engineers decide.diff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.mdindex 45bc7569a..a7a31de0b 100644--- a/docs/MCP_TOOLS.md+++ b/docs/MCP_TOOLS.md@@ -1,6 +1,6 @@# MCP Tools Reference-repowise exposes 7 tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). These tools give AI coding assistants (Claude Code, Cursor, Cline, Windsurf) structured access to your codebase intelligence — dependency graph, git history, documentation, and architectural decisions.+repowise exposes 9 tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). These tools give AI coding assistants (Claude Code, Cursor, Cline, Windsurf) structured access to your codebase intelligence — dependency graph, git history, documentation, and architectural decisions.**Start the MCP server:**@@ -20,10 +20,12 @@ repowise mcp --transport sse --port 7338 # for web clients| `get_overview` | Architecture summary | First call on any unfamiliar codebase || `get_answer` | One-call RAG Q&A | First call on any code question || `get_context` | Rich context for targets | Before reading or modifying code |+| `get_symbol` | Raw source bytes for one symbol | When you need one function/class body || `search_codebase` | Semantic search | Discovering code by topic || `get_risk` | Modification risk | Before changing hotspot files || `get_why` | Architectural decisions | Before structural changes || `get_dead_code` | Unreachable code | Cleanup tasks |+| `get_health` | Code-health biomarker scores | Before refactoring — find the worst files |---@@ -81,7 +83,7 @@ The workhorse tool. Returns docs, symbols, ownership, freshness, and community m| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| `targets` | list[string] | Yes | File paths, module names, or symbol IDs. Batch multiple targets in one call. |-| `include` | list[string] | No | Additional data to include: `"source"` (symbol body), `"callers"` (who calls this), `"callees"` (what this calls), `"metrics"` (PageRank, centrality), `"community"` (cluster membership) |+| `include` | list[string] | No | Additional data to include: `"full_doc"` (full wiki markdown), `"callers"` (who calls this — symbol targets), `"callees"` (what this calls — symbol targets), `"ownership"` (primary owner, bus factor, contributor count), `"last_change"` (last commit date + author), `"metrics"` (PageRank, betweenness, percentiles), `"community"` (cluster membership + neighbors), `"decisions"` (full decision records; default returns titles only) || `compact` | boolean | No | Default `true`. Set `false` for full structure block and importer list. || `repo` | string | No | *(workspace only)* Target repo alias, or `"all"` |@@ -99,6 +101,36 @@ get_context(targets=["src/auth"], compact=false, include=["community"])---+## `get_symbol`++Raw source bytes for one indexed symbol with exact line bounds — cheaper and+safer than `Read` + offset math. The only tool that returns actual source code.++**Parameters:**++| Parameter | Type | Required | Description |+|-----------|------|----------|-------------|+| `symbol_id` | string | Yes | Canonical `"path/to/file.py::SymbolName"` from `get_context`'s symbol list. Normalises `::` / `.` / `/` separators across languages. |+| `context_lines` | int | No | Extra source lines before/after the symbol (0–50, default 0) |+| `repo` | string | No | *(workspace only)* Usually omitted; `"all"` is not supported |++**Returns:** The symbol's source bytes (bounded at ~400 lines), its exact start/end+line numbers, kind, and a `truncated` flag. On a miss, returns an `error` with+the closest matches.++**When to use:** When you need the body of one function or class. Pipe the+`symbol_id` straight from `get_context`'s symbol list. Deterministic resolution+on overloads.++**Example call:**++```+get_symbol(symbol_id="src/auth/service.py::AuthService")+get_symbol(symbol_id="src/auth/service.py::login", context_lines=10)+```++---+## `search_codebase`Semantic search over the full wiki. Natural language queries.@@ -205,13 +237,46 @@ get_dead_code(min_confidence=0.8, include_internals=true)---+## `get_health`++Code-health biomarker scores — the same 25 deterministic biomarkers the+`repowise health` CLI computes, exposed for agentic workflows. Zero LLM calls.++**Parameters:**++| Parameter | Type | Required | Description |+|-----------|------|----------|-------------|+| `targets` | list[string] | No | File paths, or `module:foo` to expand a module's file set. Empty → dashboard mode. |+| `include` | list[string] | No | `"refactoring"` (rule-based suggestions), `"trend"` (snapshot diff + declining / predicted-decline alerts), `"coverage"` |+| `repo` | string | No | *(workspace only)* Target repo alias |+| `limit` | int | No | Max rows in the lowest-scoring file list (default 20, capped at 50) |++**Returns:** Dashboard mode (no `targets`) returns repo-level KPIs (hotspot+health, average health, worst performer), the lowest-scoring files, and a+per-module NLOC-weighted rollup. Targeted mode returns per-file biomarker+findings with severity and the score breakdown.++**When to use:** Before refactoring — find the worst-scoring files and what to+fix first. Pair with `get_risk` on hotspots.++**Example calls:**++```+get_health()+get_health(include=["refactoring"])+get_health(targets=["src/api/server.py"])+get_health(targets=["module:src.api"], include=["trend"])+```++---+## Workspace ModeIn workspace mode (initialized with `repowise init .`), all tools accept an optional `repo` parameter:- **Omit `repo`** — queries the default (primary) repo- **`repo="backend"`** — targets a specific repo by alias-- **`repo="all"`** — queries across all workspace repos (supported by `search_codebase`, `get_context`, `get_overview`)+- **`repo="all"`** — queries across all workspace repos (supported by `search_codebase`, `get_context`, `get_overview`; not supported by `get_symbol`)The MCP server automatically enriches responses with cross-repo intelligence:- **Co-change partners** from other repos surfaced in `get_context` and `get_risk`@@ -222,7 +287,7 @@ The MCP server automatically enriches responses with cross-repo intelligence:## Proactive Hooks (Complementary)-In addition to the 7 MCP tools, `repowise init` installs Claude Code hooks that provide **passive, automatic** context enrichment:+In addition to the 9 MCP tools, `repowise init` installs Claude Code hooks that provide **passive, automatic** context enrichment:- **PreToolUse** — every `Grep`/`Glob` call is enriched with graph context (symbols, importers, dependencies, git signals) at ~24ms latency- **PostToolUse** — after git commits, the agent is notified when the wiki is stalediff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex 5756bd1c6..a684227a8 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -185,7 +185,7 @@ REPOWISE_API_URL=http://localhost:7337 npm run dev --workspace packages/web- **[User Guide](USER_GUIDE.md)** — full CLI reference, web UI features, MCP setup, common workflows, and troubleshooting- **[CLI Reference](CLI_REFERENCE.md)** — every command with every flag-- **[MCP Tools](MCP_TOOLS.md)** — all 7 MCP tools with parameters and examples+- **[MCP Tools](MCP_TOOLS.md)** — all 9 MCP tools with parameters and examples- **[Workspaces](WORKSPACES.md)** — multi-repo workspace setup and cross-repo intelligence- **[Auto-Sync](AUTO_SYNC.md)** — hooks, file watcher, webhooks, polling- **[Architecture](architecture/ARCHITECTURE.md)** — how repowise is built internallydiff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.mdindex 702f9c05a..d8f2f001f 100644--- a/docs/USER_GUIDE.md+++ b/docs/USER_GUIDE.md@@ -352,17 +352,19 @@ This is how you connect repowise to Claude Code, Cursor, Cline, Windsurf, and ot| `--transport` | Protocol: `stdio` (default, for editors) or `sse` (for web clients) || `--port` | Port for SSE transport (default: 7338) |-**MCP tools exposed (7 tools):**+**MCP tools exposed (9 tools):**| Tool | What it does ||------|-------------|| `get_overview` | Repository architecture summary, key modules, entry points, git health, community summary || `get_answer` | One-call RAG: confidence-gated synthesis over the wiki, with cited 2–5 sentence answers and a per-repository question cache || `get_context` | Complete context for files/modules/symbols — docs, ownership, decisions, freshness, community membership. Defaults to `compact=True`; pass `compact=False` for the full structure block and importer list. In workspace mode, accepts `repo` parameter. |+| `get_symbol` | Raw source bytes for one indexed symbol with exact line bounds (cheaper/safer than `Read` + offset math) || `search_codebase` | Semantic search over wiki with git freshness boosting. In workspace mode, searches across all repos. || `get_risk` | Modification risk assessment — hotspot score, dependents, co-change partners, bus factor, blast radius, test gaps, 0–10 risk score || `get_why` | Why code is structured the way it is — architectural decisions, git archaeology. Three modes: NL search, path-based, health dashboard. || `get_dead_code` | Tiered dead code report grouped by confidence with cleanup impact estimates |+| `get_health` | 25-biomarker code-health scores — dashboard KPIs + lowest-scoring files, or per-file findings; `include` for refactoring suggestions and trend alerts |In workspace mode, tools are workspace-aware — pass `repo="backend"` to target a specific repo or `repo="all"` to query across the entire workspace. The default repo is used when `repo` is omitted.