Repowise

<a href="https://www.repowise.dev"><img src=".github/assets/banner.png" alt="repowise: the codebase intelligence layer for your AI coding agent" width="100%" /></a>

AI now writes a large and growing share of the code, and the humans accountable for it have to trust what ships. A score that says "this file is risky" isn't enough: you need to know where the risk concentrates and how to fix it.

repowise closes that loop. It indexes your codebase once and scores every file for defect risk, maintainability, and performance from 25 deterministic markers, calibrated against a real defect corpus, no LLM, in under 30 seconds (the proof ↓). The same index then locates the risk through a real dependency graph and git history, and generates the fix: concrete, graph-aware refactoring plans (split this god class, move this method, break this dependency cycle, dedup this clone) that your coding agent can execute.

And because it is all one index, your agent gets the rest for free: five intelligence layers: dependency graph, git history, auto-generated docs, architectural decisions, and code health, exposed to Claude Code, Codex, and any MCP-compatible agent through nine task-shaped tools. 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 ↓). One index: context your agent can use, signals your team can trust, and the fix it can apply.

The five layers

repowise 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.

Full deep-dive on every layer (graph, git, docs, decisions, hooks, auto-sync, dead code, CLAUDE.md generation): docs/INTELLIGENCE_LAYERS.md →

★ Code Health: the layer nobody else nails

Code health is repowise's deepest differentiator: the one layer with no real equivalent, and the only one we can prove predicts real bugs. It runs as a loop: measure every file across three signals, locate where the risk concentrates through the graph and git history, then fix it with a concrete refactoring plan your agent can execute.

repowise scores every file 1–10 from 25 deterministic markers: 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.

Three signals, one index. The headline 1–10 is defect risk: the defect-calibrated, bug-predictive score in the table below. From the same marker stream, repowise surfaces two co-equal companion views: maintainability (cohesion, brain methods, DRY and god-class smells that raise change-cost without predicting bugs) and performance (static N+1 / I/O-in-loop risk, followed across files through the call graph: file-local linters found 0 of those cross-function cases on a 12k-file benchmark where repowise surfaced 557). They are separate lenses, never blended into the defect headline, so the bug-predictive number stays clean.

Zero LLM calls. Zero cloud requirement. Zero new runtime dependencies. Pure Python over tree-sitter + git data, finishing in under 30 seconds on a 3,000-file repo. The marker weights are calibrated against a real defect corpus, not hand-tuned; only the learned constants ship and the runtime stays fully deterministic.

repowise health                       # KPIs + lowest-scoring files
repowise health --coverage cov.lcov   # ingest LCOV/Cobertura/Clover → untested-hotspot
repowise health --refactoring-targets # ranked by impact / effort
repowise health --trend               # snapshots + declining / predicted-decline alerts

And it proves itself on your repo, not just a benchmark: after every index, repowise checks its own flags against your git history and reports the hit rate in the terminal and on the dashboard: "16/20 lowest-health files had a bug fix in the last 6 months, 3.3x the 24% baseline". See Does the score find the bugs?.

Does the score actually find bugs? Yes, and it out-ranks CodeScene, 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:

Ranking by repowise health surfaces 2.3× the defects under a fixed review budget (Popt Δ +0.144, recall Δ +0.098, density Δ all p = 0.003, paired and significant; the ROC AUC edge is marginal). Full methodology & CIs →

User guide & per-marker reference: docs/CODE_HEALTH.md

Refactoring intelligence

A health score tells you a file is in trouble. Every other tool stops there, or prints the same static sentence for every god class in every repo. repowise names the specific fix, computed deterministically from the graph, the class model, and git co-change: Extract Class, Extract Helper, Move Method, Break Cycle, and Split File. Each plan names the exact methods, edges, or symbols that move, and carries its blast radius (the callers and co-changing files that must move with it). Ranking is graph-aware (impact × call-graph centrality × blast radius), so a fix on a central hub outranks the same fix on a leaf. That is the wedge: CodeScene's AI refactoring stays within a single function, where repowise names the cross-file move and the dependents it ripples to.

The deterministic plan is the product; an optional LLM step (never in the indexing path, only on explicit request) expands any plan into generated code plus a unified diff, fed the graph and co-change context a bare codegen tool throws away.

repowise health --refactoring-targets    # ranked plans; get_health(include=["refactoring"]) over MCP

The web Refactoring tab renders each plan as a card with a copy-to-agent button and the opt-in Generate code diff view. Per-detector mechanics: docs/CODE_HEALTH.md · full reference: docs/REFACTORING.md

Change risk & agent provenance

Two more deterministic signals, built on the same graph and git history, for the people who have to trust what ships:

• ★ Change risk: score any commit or base..HEAD range 0–10 for defect risk from the shape of the diff (Kamei-style just-in-time metrics), with PR-mode directives (will_break, missing_cochanges, missing_tests). One command: repowise risk main..HEAD. Reference: docs/CHANGE_RISK.md.
• ★ Agent provenance: attribute commits to the AI agents that wrote them, straight from git history, so you can see how much of your codebase an agent produced and which of that code is a low-health hotspot owned by a single person. Risk management for AI-era codebases, not developer surveillance.

Both are zero-LLM and reproducible. Deep dives on the hosted site: change risk → · agent provenance →.

Benchmarks

Reproducible, on public codebases. repowise-bench →

1 · Agent efficiency: repowise does the exploration once, offline

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):

up to −96% tokens to load context  ·  −89% file reads  ·  −70% fewer tool calls  ·  answer quality at parity

The win is context: repowise hands the agent a curated answer instead of a pile of files to read. Loading a commit's context via get_context costs 2,391 tokens vs 64,039 raw, ~27× fewer (−96%). Across the two benchmarks, agents read −69% to −89% fewer files and make −49% to −70% fewer tool calls at answer quality on par with raw exploration; on a long, multi-step investigation that compounds to −41% of the context re-read across the whole session. Saved tokens are tokens you don't pay for, so dollar cost drops too, though agent-side prompt caching now mutes the cost delta. Reports: flask48 · flask v3 · sklearn48

2 · Distill: index-aware output distillation

Most of what an agent reads from a shell command is noise: 300 lines of passing tests around 4 failures, full commit bodies for "what changed recently". repowise distill <cmd> compresses command output before the agent reads it, errors-first, exit code preserved, and every omission reversible via an inline [repowise#<ref>] marker (repowise expand <ref>). Paired runs on a public OSS repo, per command:

Small outputs pass through untouched (net-positive guard), and in an end-to-end spot-check the agent reached the identical root-cause diagnosis from distilled output as from raw. Opt-in Claude Code hook rewrites noisy commands automatically (shown for approval); repowise saved tracks tokens and dollars saved. Full guide: docs/DISTILL.md →

3 · Code health predicts real defects

Health scores are collected at a historical commit (T0); bug-fixing commits are counted over the following 6 months; the two are correlated, with strictly no leakage. Across 21 open-source repositories spanning all 9 Full-tier languages:

• 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), so 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).

Full report: health-defect/BENCHMARK_REPORT.md →

Local dashboard

repowise serve starts a full web UI alongside the MCP server, no separate setup.

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 (three signals: defect, maintainability, performance; coverage, trends) · Refactoring (ranked plan cards, blast radius, copy-to-agent, opt-in code-gen diff) · Security (local pattern scan) · Costs · Workspace (cross-repo contracts & co-changes). Full view-by-view list in docs/USER_GUIDE.md.

VS Code extension

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

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

Supported languages

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

Adding a language needs one .scm query file and one config entry, with no changes to the parser core. Full per-language matrix, code-health checklist, and the contributor recipe: docs/LANGUAGE_SUPPORT.md →

Who it's for

Quickstart

pip install repowise          # or: uv tool install repowise

Single repo

cd your-project
repowise init        # builds all five intelligence layers (one-time)
repowise serve       # starts MCP server + local dashboard

Multi-repo workspace

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, Live System Map + per-repo pages

The workspace Live System Map renders your services and their typed relationships (HTTP / gRPC / events / package deps / co-change) as a code-derived, always-current diagram, health-colored, filterable, with drill-down to the underlying contracts. See Workspaces.

repowise init automatically registers the MCP server, installs a PostToolUse hook in ~/.claude/settings.json, generates .mcp.json at the project root, and offers a post-commit hook that keeps everything in sync. If the Codex CLI is installed and logged in, interactive runs also offer to write project-local .codex/config.toml, .codex/hooks.json, and a managed AGENTS.md; non-interactive runs require --codex. Skip Codex setup with --no-codex; force or skip AGENTS.md with --agents / --no-agents.

Claude Code plugin. Prefer a one-command setup? Install the plugin from the marketplace: it registers the MCP server and hook and adds /repowise:* slash commands (init, health, risk, dead-code, decision, …):

/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowise

To add the MCP server to another editor manually:

{
  "mcpServers": {
    "repowise": { "command": "repowise", "args": ["mcp", "/path/to/your/project"] }
  }
}

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.

Docs: Quickstart · User Guide · CLI Reference · Codex · MCP Tools · Distill · Workspaces · Auto-Sync · Upgrading · Config

Nine MCP tools

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.

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 →

How it compares

repowise is the intersection: behavioral git intelligence + a defect-validated code-health score with the graph-aware fix attached + auto-generated docs + agent-native MCP + architectural decisions + multi-repo workspace intelligence, self-hostable and open source. Full side-by-side comparisons (CodeScene, DeepWiki, Sourcegraph, Cursor, GitClear): repowise.dev/compare →.

For teams & enterprises

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 → · explore public repos →.

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 → · Learn more →
• CVE-aware security layer, cross-repo intelligence at scale, and integrations (Slack, Jira/Linear, Confluence/Notion, PagerDuty) (rolling out).

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

Privacy

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

CLI & configuration

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 distill pytest   # compact errors-first output (reversible), saves 60–90% tokens
repowise saved            # tokens & dollars saved by distillation
repowise doctor           # check setup, API keys, store drift

repowise init generates .repowise/config.yaml (provider, model, embedder, reasoning mode, exclude patterns, git commit depth). Full command set: docs/CLI_REFERENCE.md · config reference: docs/CONFIG.md.

Contributing

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

Full guide, including how to add languages and LLM providers: CONTRIBUTING.md.

License

AGPL-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 or contact hello@repowise.dev.

<em>Built for engineers who got tired of watching their AI agent <code>cat</code> the same file for the fourth time.</em>