Repowise

<div align="center">

<img src=".github/assets/logo.png" width="280" alt="repowise" /><br /> Codebase intelligence for AI-assisted engineering teams.

Four intelligence layers. Eight MCP tools. One pip install.

Live Demo → · Hosted for teams · Docs · Discord · Contact

---

<img src=".github/assets/demo.gif" alt="repowise demo — repowise init → Claude Code querying via MCP tools" width="100%" />

---

</div>

When Claude Code reads a 3,000-file codebase, it reads files. It does not know who owns them, which ones change together, which ones are dead, or why they were built the way they were.

repowise fixes that. It indexes your codebase into four intelligence layers — dependency graph, git history, auto-generated documentation, and architectural decisions — and exposes them to Claude Code (and any MCP-compatible AI agent) through eight precisely designed tools.

The result: Claude Code answers "why does auth work this way?" instead of "here is what auth.ts contains."

---

What repowise builds

repowise runs once, builds everything, then keeps it in sync on every commit.

◈ Graph Intelligence

tree-sitter parses every file into symbols. NetworkX builds a dependency graph — files, classes, functions, imports, inheritance, and call relationships. PageRank identifies your most central code. Community detection finds logical modules even when your directory structure doesn't reflect them.

◈ Git Intelligence

500 commits of history turned into signals: hotspot files (high churn × high complexity), ownership percentages per engineer, co-change pairs (files that change together without an import link — hidden coupling), and significant commit messages that explain why code evolved.

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

◈ Decision Intelligence

The layer nobody else has. Architectural decisions captured from git history, inline markers, and explicit CLI — linked to the graph nodes they govern, tracked for staleness as code evolves.

# 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

These become structured decision records, queryable by Claude Code via get_why().

---

Quickstart

pip install repowise

cd your-project
repowise init        # builds all four intelligence layers (~25 min first time)
repowise serve       # starts MCP server + local dashboard

Add to your Claude Code config (~/.claude/claude_desktop_config.json):

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

Note on init time: Initial indexing analyzes your entire codebase — AST parsing, 500-commit git history, LLM doc generation, embedding indexing, and decision archaeology. This is a one-time cost (~25 minutes for a 3,000-file project). Every subsequent update after a commit takes under 30 seconds.

---

Eight MCP tools

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.

| Tool | What it answers | When Claude Code calls it | |---|---|---| | get_overview() | Architecture summary, module map, entry points | First call on any unfamiliar codebase | | get_context(targets, include?) | Docs, ownership, decisions, freshness for any targets — files, modules, or symbols | Before reading or modifying code. Pass all relevant targets in one call. | | get_risk(targets) | Hotspot scores, dependents, co-change partners, plain-English risk summary | Before modifying files — understand what could break | | get_why(query?) | Three modes: NL search over decisions · path-based decisions for a file · no-arg health dashboard | Before architectural changes — understand existing intent | | search_codebase(query) | Semantic search over the full wiki. Natural language. | When you don't know where something lives | | get_dependency_path(from, to) | Connection path between two files, modules, or symbols | When tracing how two things are connected | | get_dead_code() | Unreachable code sorted by confidence and cleanup impact | Cleanup tasks | | get_architecture_diagram(module?) | Mermaid diagram for the repo or a specific module | Documentation and presentation |

Tool call comparison — a real task

"Add rate limiting to all API endpoints."

| 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 (8 tools) | 5 calls | ~2 min | Nothing |

The 5 calls for that task:

get_overview()                                         # orient: understand the architecture
get_context(["middleware", "api/routes", "payments"])  # understand 3 modules at once
get_risk(["middleware/auth.ts"])                       # assess: 47 dependents, co-changes
get_why("rate limiting")                               # check: any prior decision?
search_codebase("rate limit OR throttle OR retry")     # find: any prior implementation?

---

How Claude Code uses it

User: Implement rate limiting on all API endpoints

Claude Code:
→ get_overview()
  "Express API. Entry points in api/routes/. Middleware in middleware/."

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

→ 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."

→ search_codebase("rate limit throttle retry")
  "Found: payments/retry.ts already has RetryQueue class.
   Found: payments/middleware.ts has idempotency key middleware."

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.

This is what happens when an AI agent has real codebase intelligence.

---

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%" />

| View | What it shows | |---|---| | Chat | Ask anything about your codebase in natural language | | Docs | AI-generated wiki with syntax highlighting and Mermaid diagrams | | Graph | Interactive dependency graph — handles 2,000+ nodes | | Search | Full-text and semantic search with global command palette (Ctrl+K) | | Symbols | Searchable index of every function, class, and method | | Coverage | Doc freshness per file with one-click regeneration | | Ownership | Contributor attribution and bus factor risk | | Hotspots | Ranked high-churn files with commit history | | Dead Code | Unused code with confidence scores and bulk actions | | Decisions | Architectural decisions with staleness monitoring |

---

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.

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.

<!-- 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 in last 500 commits
<!-- REPOWISE:END -->

---

Git intelligence

repowise mines your last 500 commits (configurable) to produce signals no static analysis can find.

Hotspots — files i