Getting Started

The 60-second path to codebase intelligence.

Table of contents

  1. Quick start (under 5 minutes, no API key)
  2. Choose your path
  3. Path 1: Claude Code Plugin
    1. Step 1: Install the plugin
    2. Step 2: Index your repo
    3. What happens
    4. What you see
  4. Path 2: pip + Claude Code
    1. Step 1: Install repowise
    2. Step 2: Set your API key
    3. Step 3: Index your repo
    4. Step 4: Connect Claude Code
  5. Path 3: pip + Codex
    1. Step 1: Install repowise and Codex
    2. Step 2: Index your repo
    3. Step 3: Start Codex
  6. Path 4: Standalone CLI
    1. Step 1: Install and set up
    2. Step 2: Index your repo
    3. Step 3: Start the web dashboard
    4. Step 4: Start the MCP server (optional)
  7. The keyless path (the default)
  8. Keeping docs in sync
  9. Next steps

Quick start (under 5 minutes, no API key)

Index once, and give your agent the dependency graph + git history + code-health — not 40 greps.

1. Install

pip install repowise          # Windows: python -m pip install repowise
repowise --version            # -> repowise, version 0.27.x

2. Index your repo

cd /path/to/your/repo
repowise init

Bare init scans the repo and asks how to index it: everything (the wiki written by a model), no prose (the same wiki rendered from your code’s structure, no key and no spend), or advanced for every knob. Nothing is spent before you see an estimate and confirm it.

Scripting it instead? Name the mode and skip the questions: repowise init --no-prose -y for the free path, repowise init --prose -y for model-written subsystem pages. Either way you get the dependency graph, git history, code-health score and dead-code findings in seconds, plus every wiki page.

3. Connect your agent — the MCP server is repowise mcp, served from the repo dir.

Claude Code 
# Plugin (MCP tools + slash commands + skills):
/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowise

# …or wire the MCP server directly:
claude mcp add repowise -- repowise mcp

Or commit a project .mcp.json:

{ "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp"] } } }
Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.repowise]
command = "repowise"
args = ["mcp"]

Or: codex mcp add repowise -- repowise mcp

4. First real call. Ask your agent: “Use repowise get_overview to summarize this repo,” or “get_context for src/auth.py.” You get graph-grounded architecture and per-file triage instead of a flurry of greps. ✅

get_overview and get_context work in index-only mode with no key, synthesized from the graph, git and health layers. search_codebase and get_answer read the wiki, which index-only mode does build, but they answer from pages rendered from structure rather than model-written prose, and search_codebase is full-text only until you configure an embedder.

Ready for the full picture? Run repowise init --provider … for the generated wiki + semantic search, or skip key management entirely with the hosted tier. The detailed setup paths below walk through each editor and mode.

Choose your path

There are three ways to set up repowise. Pick the one that fits how you work.

Path Best for Time
Claude Code Plugin Claude Code users ~30 seconds
pip + Claude Code Manual control + Claude Code ~2 minutes
pip + Codex Codex CLI users ~2 minutes
Standalone CLI No AI editor, or CI use ~2 minutes

Path 1: Claude Code Plugin

The recommended path. Claude handles everything — installation, API key setup, indexing, and MCP registration.

Step 1: Install the plugin

Open Claude Code and run:

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

Step 2: Index your repo

Navigate to your project directory and run:

/repowise:init

Or just ask Claude naturally:

set up repowise for this repo

What happens

Claude walks you through:

  1. Mode selection — full documentation, index-only (free, no LLM), or advanced
  2. Provider setup — choose Anthropic, OpenAI, Gemini, or local Ollama
  3. API key — entered once, saved to .repowise/.env (gitignored automatically)
  4. Indexing — parses your code, runs git analysis, generates docs

When it finishes, the MCP server is registered and Claude can query your codebase directly. You’ll see a progress bar as each phase completes.

What you see 

 repowise
─────────────────────────────────────────────
 Indexing your codebase...

 Phase 1 of 4 — Ingestion
  Scanning & filtering files...      [████████████████████]
  Scanned 1,247 files, 247 included
    Excluded: 820 by .gitignore, 45 by extension, 12 binary, 123 unknown type
    Languages: python 892, typescript 245, go 80, yaml 18, json 12
  Parsing files...                   [████████████████████] 247/247
  Building dependency graph...       done

 Phase 2 of 4 — Analysis
  Indexing file history...           done
  Detecting dead code...             done
  Extracting decisions...            done

 Phase 3 of 4 — Generation
  Languages: python 58%, typescript 28%, go 10%, yaml 2%, json 1%
  Generating wiki pages...           [████████████████░░░░] 82%
  Estimated tokens: ~180k

 Phase 4 of 4 — Persistence
  Writing to database...             done
  Building vector index...           done
  Generating CLAUDE.md...            done

 Done. 247 pages generated.
─────────────────────────────────────────────

Path 2: pip + Claude Code

Install manually, then connect Claude Code to the MCP server.

Step 1: Install repowise 

pip install repowise

Step 2: Set your API key 

export ANTHROPIC_API_KEY="sk-ant-..."
# or: export OPENAI_API_KEY="sk-..."
# or: export GEMINI_API_KEY="AI..."

Step 3: Index your repo 

cd /path/to/your-repo
repowise init

repowise detects your API key automatically and starts the interactive setup. Follow the prompts — it takes about 2 minutes for a medium-sized codebase.

Step 4: Connect Claude Code

After init completes, repowise writes a .mcp.json file at your repo root. Claude Code picks this up automatically next time you open the project.

To verify the MCP server is connected:

/repowise:status

Path 3: pip + Codex

Use the local Codex CLI auth/subscription flow and project-local MCP/hooks config.

Step 1: Install repowise and Codex 

pip install repowise
npm install -g @openai/codex
codex login
codex login status

Step 2: Index your repo 

cd /path/to/your-repo
repowise init --codex --provider codex_cli --yes

This writes .codex/config.toml, .codex/hooks.json, and managed AGENTS.md in the repository. It does not edit global ~/.codex/config.toml.

Step 3: Start Codex 

codex

Codex reads AGENTS.md, starts the Repowise MCP server from project config, and receives lightweight lifecycle/freshness hooks. See Codex Integration.

Path 4: Standalone CLI

Use repowise without Claude Code — with the web dashboard, REST API, or any MCP-compatible editor.

Step 1: Install and set up 

pip install repowise
export ANTHROPIC_API_KEY="sk-ant-..."

Step 2: Index your repo 

cd /path/to/your-repo
repowise init

Step 3: Start the web dashboard 

repowise serve

Open http://localhost:3000 in your browser. You’ll see the full wiki, dependency graph, search, and more.

Step 4: Start the MCP server (optional)

To connect any MCP-compatible editor (Codex, Cursor, Cline, Windsurf):

repowise mcp

Then add the MCP server to your editor’s configuration. See MCP Server → for editor-specific setup.

The keyless path (the default)

You don’t need an LLM API key at all. A bare repowise init with no key configured succeeds and produces a wiki, rendered from the parsed structure of your code:

repowise init

repowise init --no-prose is the explicit spelling of the same thing, and guarantees no spend. Either way you get the full ingestion and analysis pipeline (parsing, graph, git, dead code) plus a complete wiki. It’s free, takes under a minute for most repos, and still gives you:

  • Dependency graph
  • Hotspot detection
  • Dead code findings
  • Ownership data

You can always run repowise init --prose (or repowise generate) later to write the subsystem pages as model prose on top of an existing index.

Keeping docs in sync

After the initial index, keep your wiki current with:

repowise update          # Sync changed files since last commit
repowise watch           # Auto-update on file saves

Or in Claude Code, run /repowise:update — Claude detects changed files and regenerates only the affected pages.

Next steps