Who is this for?

Repolect is built primarily for:

• 🧠 Developers exploring new code: Quickly understand a project's architecture and logic better without reading thousands of lines of code.
• 🤖 AI Coding Agent Users: Supercharge agents (like Cursor, Claude Code) with precise structural context to improve edit performance and significantly reduce hallucinations.
• 📊 Local-First Enthusiasts: Index, query, and beautifully visualize your codebase's dependencies entirely locally.
• ⚡ SLM Power Users: Maximize the potential of locally hosted Small Language Models (via Ollama) to autonomously analyze, edit, and update your codebases.

Features

• 🌳 Hierarchical Semantic Tree: Every node (module, file, class, function) gets a bottom-up LLM-generated summary. The abstract meaning of your codebase is indexed, not just the raw text.
• 🎯 Vectorless Search: Navigate the semantic tree using LLM reasoning (in O(log N) steps). Finds actual answers, saving huge amounts of tokens compared to blind similarity searches.
• 🕸️ Knowledge Graph: Maps CALLS, IMPORTS, EXTENDS, and IMPLEMENTS relations across your codebase. Useful for tracing execution paths or finding the "blast radius" of a change.
• 🔌 Full MCP Integration: Exposes 14 powerful tools to AI editors (Cursor, Claude Code etc) out of the box, drastically reducing token usage and round trips.
• 🛡️ Prescriptive Agent Context: Generates "Agent Skills" depending on functional groups (Louvain communities) in your code to inject targeted context when and where it's needed.
• 🔒 Local-First & SLM Optimized: Engineered to run perfectly on efficient local models like qwen3.5 or qwen2.5-coder via Ollama. No data leaves your machine unless you want it to.

How It Works

Repolect builds a hierarchical tree of your codebase where every node — module, file, class, function — gets an LLM-generated summary. Queries navigate this tree using LLM reasoning, finding relevant code in O(log N) steps without any vector similarity search.

RepoNode: "E-commerce backend in Python/FastAPI..."
├── ModuleNode src/auth: "JWT-based authentication layer..."
│   ├── FileNode jwt.py: "Token generation and validation..."
│   │   ├── ClassNode JWTService: "Manages token lifecycle..."
│   │   └── FunctionNode verify_token: "Validates Bearer tokens..."
│   └── DocNode README.md: "Auth module documentation..."
└── ModuleNode src/payments: "Stripe payment processing..."

A knowledge graph runs alongside the tree, storing structural relations (CALLS, IMPORTS, EXTENDS, IMPLEMENTS) that power dependency analysis, impact tracing, and execution flow tracking.

Architecture

flowchart LR
    subgraph indexing [Indexing Pipeline]
        Scan[Scan Repo] --> Parse[Parse Files]
        Parse --> Summarize[LLM Summarize]
        Summarize --> Graph[Build Graph]
    end
 
    subgraph storage [Dual Storage]
        Tree["tree.json\n(semantic tree)"]
        GraphDB["graph.pkl / graph.db\n(knowledge graph)"]
    end
 
    subgraph query [Query Layer]
        CLI[CLI Commands]
        MCP[MCP Server]
    end
 
    Graph --> Tree
    Graph --> GraphDB
    Tree --> CLI
    Tree --> MCP
    GraphDB --> CLI
    GraphDB --> MCP

Quick Start

Recommended: One-liner Installer

The interactive installer sets up Ollama, configures your LLM provider, and makes repolect available system-wide:

curl -fsSL https://raw.githubusercontent.com/Bibyutatsu/Repolect/main/install.sh | bash

The installer uses pipx (isolated environment, no dependency conflicts) with a pip --user fallback. It automatically updates your shell PATH via a Conda-style marker block in .zshrc/.bashrc.

Install via pipx (recommended for CLI tools)

pipx install repolect
pipx inject repolect ollama          # for Ollama support
pipx inject repolect falkordblite    # for FalkorDB graph backend

Install from PyPI

pip install repolect[all]

Install from source

git clone https://github.com/Bibyutatsu/Repolect.git
cd Repolect
pip install -e ".[all]"

Index and query

cd your-project/
repolect analyze          # Index the codebase
repolect ask "how does authentication work?"

Requires an LLM provider. Repolect defaults to Ollama (local, free, private). See Configuration for other providers.

CLI Reference

MCP Server Integration

The Model Context Protocol (MCP) lets AI editors use Repolect as a live code intelligence backend.

Auto-configure with repolect mcp

Running repolect mcp opens an interactive setup flow:

1. Displays the config snippet you can copy into any editor manually
2. Detects installed editors (Cursor, Claude Code, Antigravity, Windsurf, VS Code)
3. Asks which to configure — select by number or press a for all
4. Writes/merges the correct JSON config into each editor automatically

$ repolect mcp

  🔌 Repolect MCP Server
  ────────────────────────────────────────────────────────

  Add this to your editor's MCP config file:

    {
      "mcpServers": {
        "repolect": {
          "command": "/usr/local/bin/repolect",
          "args": ["mcp", "--serve"]
        }
      }
    }

  Binary resolved to: /usr/local/bin/repolect

  ────────────────────────────────────────────────────────
  Detected editors:  [1] Cursor  ,  [2] Antigravity (Gemini)

  Enter numbers to auto-configure (e.g. 1,3), 'a' for all, or Enter to skip:
  → a

  Cursor  →  ~/.cursor/mcp.json  [✓ written]
  Antigravity (Gemini)  →  ~/.gemini/mcp.json  [✓ written]

  ✅ Done! Restart your editor for changes to take effect.

Manual config (all editors use the same format)

{
  "mcpServers": {
    "repolect": {
      "command": "repolect",
      "args": ["mcp", "--serve"]
    }
  }
}

--serve flag: Use args: ["mcp", "--serve"] in your mcp.json. This skips the interactive menu and starts the stdio server directly — which is what editors need.

MCP Tools

14 tools exposed via MCP:

Resources & Prompts

Agent Skills & Context

Repolect influences AI agent behavior through three layers:

Layer 1: MCP Tools (what the agent can do)

The 14 tools listed above — plan_change, tree_search, impact_analysis, etc.

Layer 2: Prescriptive Context File (what the agent should do)

repolect analyze generates REPOLECT.md at the repo root with:

• "Always Do" rules — call plan_change before changes, find_similar before creating, get_conventions before modifying, diff_analysis before committing, scope_test after changes
• "Never Do" rules — never skip impact analysis on widely-used symbols, never commit without diff_analysis
• Debugging and Refactoring workflows — step-by-step tool chains
• Community map — Louvain-detected functional areas with key symbols
• Marker-based upsert — re-indexing replaces only the Repolect section, preserving any user-written content

Layer 3: Workflow Skills (what the agent does in specific situations)

Static skills (installed every repolect analyze):

Generated community skills (repolect analyze --skills):

Per-community skill files describing each functional area of the codebase — key files, entry points, cross-community connections, associated tests, and LLM-synthesized descriptions of what each area does.

Skills are auto-installed into detected editors:

• Cursor: .cursor/rules/repolect-*.mdc
• Claude Code: .claude/skills/repolect/*.md

Configuration

Repolect reads from ~/.repolect/config.yaml:

# LLM Provider
provider: ollama                    # or "openai-compatible"
base_url: http://localhost:11434    # or your API endpoint
model_name: qwen3.5:4b             # your preferred model
api_key: ""                         # empty for Ollama
 
# Embeddings (optional — enables hybrid vector+tree search)
embedding_provider: ollama
embedding_model: qwen3-embedding:0.6b

provider: openai-compatible
base_url: https://api.openai.com/v1
model_name: gpt-4o-mini
api_key: sk-...
 
embedding_provider: openai-compatible
embedding_model: text-embedding-3-small
embedding_api_key: sk-...

Environment variables override config: REPOLECT_PROVIDER, REPOLECT_BASE_URL, REPOLECT_MODEL, REPOLECT_API_KEY, REPOLECT_EMBEDDINGS (1/0).

Why Vectorless?

Vector similarity finds files that are similar to your query — not files that answer it.

"How does payment work?" doesn't semantically resemble stripe_adapter.py. LLM reasoning over a structured tree does.

Repolect's tree search operates in O(log N) LLM calls: probe the root, pick the most relevant branch, descend until you reach the answer. Every node has a pre-computed summary, so the LLM reasons about meaning, not similarity.

Embeddings are optional — enable them for hybrid search when you want both approaches.

MCP Performance Analysis

Benchmarked across 8 complex real-world coding scenarios on Repolect's own codebase (807 nodes, 28 files).

Summary

Tool Tier Ranking

Tier 1 — Transformative (use on every task):

Tier 2 — High Value (use frequently):

Tier 3 — Useful (for specific tasks):

In Practice

For a typical coding session with 5–10 tasks, Repolect MCP tools save approximately:

• ~150,000–300,000 input tokens (~$0.45–$0.90 per session at $0.003/1K tokens)
• 30–50 tool calls reduced to 8–15
• 15–25 round trips reduced to 5–8 (each round trip = 2–5 seconds of latency)
• 30–120 seconds of latency eliminated from fewer round trips

Project Structure

repolect/
├── __init__.py          # Package exports and version
├── cli.py               # Click CLI commands (analyze, ask, sync, mcp, ...)
├── config.py            # Config loading (~/.repolect/config.yaml)
├── embedder.py          # Optional vector embeddings (Ollama, OpenAI)
├── git_utils.py         # Git operations (branch, diff, hash, etc.)
├── graph_db.py          # Knowledge graph (NetworkX + FalkorDB backends)
├── mcp_server.py        # MCP server with 14 tools, 2 resources, 2 prompts
├── models.py            # Core data models (CodeNode, Relation, TreeMeta)
├── parser.py            # Hybrid parser (tree-sitter + regex enhancer)
├── search.py            # Tree search, explanation, flow tracing
├── skill_installer.py   # Agent skill installer (static + generated community skills)
├── skills/              # Static workflow skills (exploring, planning, debugging, ...)
├── storage.py           # Persistence (tree.json, meta.json, REPOLECT.md)
├── summarizer.py        # Bottom-up LLM summarization pipeline
└── tree_builder.py      # Indexing orchestrator (scan → parse → link → graph)

License

MIT