repowise init: Index Your Codebase in One Command

To index a codebase with repowise, install it and run repowise init --yes --no-prose from the repository root. The run needs no API key, makes no model calls and sends nothing off your machine. It parses every file, builds the dependency graph, reads git history, scores code health, finds dead code and renders a wiki from that structure, all into a local .repowise/ directory.

Part of the codebase intelligence guide.

The quick answer

Three commands take a repository from nothing to an indexed one your agent can query (as of repowise 0.56, October 2026):

uv tool install repowise          # or: pipx install repowise
cd path/to/your-repo
repowise init --yes --no-prose

Python 3.11 or newer and Git are required. pipx install repowise and python3 -m pip install repowise work as well, and repowise --version confirms the install. A large repository takes a few minutes. When it finishes, restart your coding agent and ask it to call get_overview; an architecture summary back means the setup works.

What repowise init builds

repowise init runs four phases, and the first three need no LLM. The CLI reference lists them in order.

The graph is what makes the rest possible. A file's importance comes from how many files depend on it, not from its size, and the same graph answers "what breaks if I change this" for a person or an agent. See the graph layer for how nodes, edges and ranking work.

The repowise wiki for the repowise repository: a generated repository overview with a page tree, an on-this-page outline and links to related files and symbols

The wiki that repowise init renders, shown here for the repowise repository itself. File, symbol, API and infrastructure pages come from structure alone.

Install and run it

Choose how to index

Bare repowise init on a terminal opens a menu with three modes:

For scripts, CI and agent setups, skip the menu: repowise init --yes --no-prose. --yes never prompts, and --no-prose keeps the run keyless even when an API key happens to be set in the environment. Before any model call, init shows a cost estimate and waits for confirmation.

Let your agent run it

If you would rather not type the commands, paste this into Claude Code, Codex, Cursor or any MCP client opened in the repository:

Read https://docs.repowise.dev/setup.md and set up repowise in this repository.

The agent installs repowise, runs the keyless index, wires the MCP server into its own host and asks you one question: free structural docs or model-written ones. It never asks you to paste a key into the chat.

Flags worth knowing

The full list is in the CLI reference. repowise also respects .gitignore, and the file-page count is capped automatically on very large repositories so the wiki stays publishable.

What gets created

Everything lives in .repowise/ at the repository root, and repowise adds that directory to .gitignore for you. It is a local cache, not a source of truth, so it is not committed.

Settings persist in config.yaml, so exclusions and options you pass once carry into later updates:

exclude_patterns:
  - "**/legacy/**"
  - "**/tests/fixtures/**"

Connect your coding agent

Unless you pass --no-editor-setup, init registers the MCP server for you. It writes .mcp.json and .claude/CLAUDE.md in the repo, .vscode/mcp.json for VS Code, the Claude Code and Claude Desktop entries, Claude Code hooks, and a git post-commit hook that runs repowise update after each commit.

Other hosts need one more command after init:

Restart the host after setup, since most agents read MCP config only at startup. The server exposes ten tools by default, among them get_overview for the architecture, get_answer for how and where questions, get_context for files and symbols, get_risk and get_change_risk for review priority, get_health, get_dead_code and get_why for decisions. The MCP tools reference lists each one, and how repowise reaches your agent shows what it returns.

The same answers are on the command line, with no agent involved:

repowise health            # lowest-scoring files, and why
repowise dead-code         # what nothing references
repowise risk main..HEAD   # review priority for your branch
repowise serve             # dashboard at http://localhost:3000

repowise serve starts the API on port 7337 and the dashboard on port 3000. The dashboard needs Node.js 20 or newer and downloads once, about 50 MB. To see the output before you run it yourself, browse the live examples, such as the FastAPI architecture view.

Add model-written docs later

The keyless index is complete on its own; model prose is an upgrade you can add without re-indexing. repowise generate rewrites the subsystem pages, the repository overview, the architecture diagram and the onboarding collection as prose, reusing the index you already have. Put the provider key in .repowise/.env, preview the cost, then write:

repowise generate --provider anthropic --dry-run   # cost estimate only
repowise generate --provider anthropic             # asks before spending

Supported providers include Anthropic, OpenAI, Gemini, OpenRouter, DeepSeek and local Ollama, so code can stay on your machine. claude_cli, codex_cli and opencode use a login you already have. Full-text search works either way; for semantic search, configure an embedder (--embedder on init, or REPOWISE_EMBEDDER) and run repowise reindex.

Keep the index fresh

After the first run, the post-commit hook keeps the index current. repowise update re-processes only what changed since the last synced commit, so it is fast and, without a provider, free. Run it by hand, or keep it running while you edit:

repowise update     # incremental catch-up
repowise watch      # update continuously while you edit
repowise status     # what is indexed and how far behind HEAD

repowise hook uninstall removes the hook. A new git worktree seeds its index from the main checkout instead of re-indexing. For webhook and polling sync across many repositories, see Auto-Sync.

Pitfalls

• repowise: command not found after install. The install directory is not on PATH. Run uv tool update-shell (uv) or pipx ensurepath (pipx), open a new shell and restart the agent host, which starts repowise by name.
• The agent does not see the tools. Restart the host first. If they are still missing, repowise doctor --repair re-registers the Claude Code entry and refreshes each wired agent's config.
• The agent answers from old code. repowise status shows drift from HEAD, and repowise update catches up.
• A run was interrupted, or a provider outage left pages missing. repowise init --resume writes only the absent pages and pays for nothing twice.
• Rate limits during model-written docs. Lower --concurrency (the default is 10) or switch to a local provider such as Ollama.
• A second repo repoints the MCP entry. Each Claude config holds one repowise entry, so indexing another repository moves it. Use --no-editor-setup for scratch clones and CI.

repowise doctor is the first stop for any of these: it checks the install, keys, index drift, store health and each agent's MCP entry.