On this page
To index a monorepo, run repowise init at the repository root. One pass builds a wiki with a page per file and per subsystem, a dependency graph that resolves imports across package boundaries, and an ownership map from git history. None of it needs an LLM key. This post covers what each layer answers for a monorepo and the commands to read it.
Part of the code health guide.
What goes wrong in a monorepo
A monorepo's problem is not size, it is that three kinds of knowledge stop fitting in anyone's head: what each package is for, who depends on it, and who knows it. A root README.md answers none of them.
- Documentation drifts. A package's interface changes weekly, and hand-written docs describe last quarter's version.
- Dependencies hide. A change to a shared UI package ripples into three apps and two functions, and you learn which at CI time.
- Ownership blurs. Fifty teams commit to one history, so "who should review this" becomes a guess.
Nx answers part of this for JavaScript workspaces: npx nx graph opens an interactive view of project dependencies. repowise covers the same ground at file and symbol level across languages, and adds documentation and ownership on top of the same index.
Index it
cd your-monorepo
repowise init # graph, wiki, health, ownership; no key needed
repowise init -x "**/dist/**" -x "vendor/" # gitignore-style excludes, repeatable
repowise init --mode fast # graph and essential git only, for very large repos
repowise update --full # upgrade a fast index to a full one later
repowise serve # dashboard at localhost:3000
init reads .gitignore and your exclude patterns, so build output and vendored code stay out. --mode fast skips per-file blame and co-change, which keeps indexing short on very large repos; repowise update --full backfills them incrementally. After the first run, repowise update re-processes only what your commits touched.
Layer 1: a graph that understands workspaces
repowise resolves imports through each ecosystem's own workspace rules, so a cross-package import becomes a real edge in the graph. From the language support doc:
| Ecosystem | What the resolver understands |
|---|---|
| TypeScript and JavaScript | tsconfig path aliases, npm, yarn and pnpm workspaces, export * from barrels |
| Python | source roots including packages/*/src, PEP 420 namespaces, __init__.py barrels |
| Java | Maven and Gradle reactor discovery, JPMS |
| Go | multi-module go.mod discovery; a package import fans out to every file in the package |
| Swift | Package.swift targets |
| Dart | package: imports through every pubspec.yaml |
Scroll the table sideways to see every column.
28 languages are parsed to a full AST, so a TypeScript frontend, a Go service and Python scripts land in one graph. Every edge records how it was resolved and a confidence, so a name-based guess is never presented as fact.

The map above is repowise's own monorepo: each cluster is a community found by Leiden clustering, and the thick links are the heavy cross-package dependencies. Communities often differ from the directory layout, which is how you find a package that is really two.
What to read from the graph
| Question | Signal | Where |
|---|---|---|
| Which shared code does everything depend on? | PageRank over files | Dashboard graph views, get_context metrics |
| Which packages cannot be built or published alone? | Strongly connected components (cycles) | Wiki scc_page per cycle, health findings |
| What breaks if I change this file? | Blast radius over dependency edges | get_risk, dashboard Blast radius |
| What changes together without importing each other? | Co-change coupling | Dashboard Coupling |
Scroll the table sideways to see every column.
repowise context packages/ui/src/button.tsx --include callers --include community
repowise risk --target packages/core/src/auth.ts
Blast radius turns a package-level question into a concrete list: changing one file reports its direct and transitive dependents, the co-change partners it usually travels with, and the tests that cover it.

Layer 2: documentation per subsystem
The wiki gives a monorepo a page per source file, per selected public symbol, per subsystem and per dependency cycle, plus a repository overview and onboarding pages. Per the wiki layer doc, almost all of it is rendered from structure with no model, so a repo indexed without a key still gets a complete wiki. A provider key adds prose to subsystem and overview pages.
repowise generate --path packages/core # prose for one subsystem
repowise export --format markdown # write the wiki out as files
For agents, get_overview returns the architecture map in one call, and get_answer answers questions with cited sources:
get_overview()
get_answer(question="how does packages/api call packages/core auth?")
Because repowise update runs on each commit (or through repowise watch and the CI integration), pages follow the code rather than the last time someone remembered to edit them.
Layer 3: ownership from git history
Ownership in repowise is computed from git log and git blame: a primary owner per file, a bus factor, and silo and knowledge-loss findings. A CODEOWNERS file states who is asked to review; the history shows who actually knows the code. The two answer different questions, and CODEOWNERS entries go stale without anyone noticing.
repowise context packages/billing/src/invoice.ts --include ownership
repowise risk --target packages/billing/src/invoice.ts
The ownership block holds the primary owner, their share of commits and lines, the recent owner (who edited it in the last 90 days), the contributor count and the bus factor. From the ownership layer doc:
| Signal | Meaning |
|---|---|
| Bus factor | How many top authors cover 80% of a file's commits; 1 means one person wrote most of it |
| Silo | A module where one person owns more than 80% of the files |
knowledge_loss | A file still being edited whose main author is no longer the recent owner |
ownership_risk | Many drive-by authors and no clear owner |
developer_congestion | A busy file with too many hands on it |
| Truck factor | Fewest primary owners who together own more than half the files (Stats page) |
Scroll the table sideways to see every column.
Two surfaces suggest reviewers for a change: get_risk(changed_files=[...]) lists up to five owners of the affected files in directive.recommended_reviewers, and the dashboard's Impact tab adds co-change partners to the scoring. Identities go through .mailmap, so one person with several addresses counts once. repowise init --follow-renames keeps ownership intact across moves, which matters when packages get reorganized.
You can browse a finished example on the FastAPI ownership map, its generated docs and its architecture view.
Monorepo or many repos
A single repository with many packages is one index. When the code lives in several repositories, repowise workspace add registers each one and adds cross-repo analysis on top: API contracts matched between producers and consumers, cross-repo co-changes, a service-level system map, and declared dependency rules with cycle detection. See the multi-repo workspaces docs.
Give agents the whole monorepo
The index is served over MCP through ten tools: get_overview for the map, get_context for a package or file, get_risk before an edit, get_health for findings, and get_dead_code for unreachable files and unused packages. An agent working in a large monorepo reads the relevant slice instead of searching directories. See the MCP guide for setup.
FAQ
- How do I document a monorepo automatically?
- Run
repowise initat the root. It generates a page per file, symbol and subsystem, plus a repository overview and onboarding pages, andrepowise updatekeeps them current on every commit. Rendering from structure needs no LLM key, and a provider adds prose. - How do I see dependencies between packages in a monorepo?
- Run
repowise serveand open the Graph, Architecture and Coupling views, or ask from the CLI withrepowise context <path> --include callers. Cross-package imports resolve through npm, yarn and pnpm workspaces, Maven and Gradle reactors, multi-module Go and other workspace rules. - Does repowise replace CODEOWNERS?
- No.
CODEOWNERSassigns review requests; repowise reports who has actually written and recently edited each file, with bus factor and silo findings. Use the history to keepCODEOWNERSaccurate. - How long does indexing a very large monorepo take?
- Use
repowise init --mode fastfor the graph and essential git history, thenrepowise update --fullto backfill blame and co-change incrementally. After the first run, updates re-process only changed files. - Does it work with private repositories?
- Yes. repowise is open source (AGPL-3.0) and runs locally. The graph, health and ownership layers make no network calls and need no key, so code leaves your machine only if you choose an LLM provider for prose.
- Which languages does it support?
- 28 languages are parsed to a full AST, with 15 at the Full tier. See language support for the per-language table.



