Skip to content
BranchesTags

Repository files navigation

🧠 RepoMind

Understand any codebase in 5 minutes.

RepoMind turns a repository into a searchable architecture map, an interactive dashboard, and a repository‑aware AI assistant — with zero infrastructure and no required API keys.

CI License: MIT Python Dependencies Offline-first Version

Quick Start · Features · Architecture · Docs · Roadmap · Contributing

📸 Screenshots

🚧 Screenshots and a demo GIF are coming soon. Until then, run it locally in under a minute — see Quick Start. Capture instructions live in docs/images/.

The problem

Opening an unfamiliar repository is slow and disorienting. You scroll through folders, guess at entry points, grep for where a feature lives, and try to hold the architecture in your head. Onboarding takes days, "what breaks if I change this?" is a manual investigation, and documentation drifts out of sync with the code.

Why RepoMind exists

RepoMind reads the repository for you and turns it into something you can see, search, and ask questions about — in minutes, offline, with nothing to install beyond Python.

It is intentionally zero‑infrastructure: no Neo4j, no Qdrant, no Docker, no database, no message queue, and no LLM key required. Everything the MVP needs — parsing, the knowledge graph, keyword‑based code search, the dashboard, and a grounded local assistant — runs on the Python standard library. An LLM (via OpenRouter) is an optional enhancement, not a dependency.

✨ Features

Capability What you get Source
Repository summary Headline, languages, primary components, architecture layers, stats, detected entry points analyzer.py
Dependency graph A knowledge graph of directories, files, classes, functions, methods, imports, calls, inheritance, tests, and external deps analyzer.py
Interactive dashboard Overview, graph, API map, impact, and onboarding views — vanilla HTML/CSS/JS, no framework static/
API map Auto‑detected routes for FastAPI, Flask, Express, Next.js (route handlers), and Spring analyzer.py
Onboarding guide Auto‑generated "where to start" guide from the analysis analyzer.py
Change impact analysis For any file/symbol/API: affected files, APIs, tests, and a risk rating (2‑hop reverse dependency walk) analyzer.py
Code search (BM25) In‑process lexical BM25 index with identifier‑aware tokenization and structural boosts — keyword‑based, no embeddings, no keys retrieval.py
Repository‑aware AI chat Retrieval‑grounded answers with file + line citations; strong extractive fallback when no key is set assistant.py
Multi‑turn conversations Remembers the discussion; resolves follow‑ups like "what calls it?" against previously discussed code conversation.py
Languages parsed Python (via ast), JavaScript / TypeScript / JSX / TSX and Java (via lightweight parsers) analyzer.py

🏗️ Architecture overview

 Repository (local path or GitHub URL)
        │
        ▼
 ┌──────────────┐   ast + regex parsers (Python / JS / TS / Java)
 │  analyzer.py │─► knowledge graph: nodes + relationships
 └──────┬───────┘   summary · components · API map · onboarding · impact_index
        │
        ├─► .repomind/analysis.json   (the knowledge map)
        │
 ┌──────▼───────┐   BM25 code index, identifier-aware + structural boosts
 │ retrieval.py │─► .repomind/index.json
 └──────┬───────┘
        │
 ┌──────▼────────────┐   grounded answers + citations
 │ assistant.py      │   ── no key ──► local extractive answer
 │ conversation.py   │   ── OPENROUTER_API_KEY ──► LLM answer (optional)
 └──────┬────────────┘
        │
 ┌──────▼───────┐   stdlib http.server, no framework
 │  server.py   │─► /api/analysis · /api/impact · /api/analyze · /api/ask · /api/chat
 └──────┬───────┘
        │
 ┌──────▼───────┐
 │  static/     │   vanilla dashboard (Overview · Graph · APIs · Impact · Guide)
 └──────────────┘

Everything above is standard library only. The repomind/integrations/ package holds optional, documented boundaries for a future production deployment — Neo4j (graph_store.py) and Qdrant (vector_store.py) are stubs; OpenRouter (llm.py) is implemented but only activates when a key is present.

For the full design, see docs/ARCHITECTURE.md.

📁 Repository structure

RepoMind/
├── repomind/
│   ├── __init__.py           # package version (0.1.0)
│   ├── __main__.py           # `python -m repomind`
│   ├── cli.py                # argparse CLI: analyze / serve
│   ├── analyzer.py           # parsing → knowledge graph, summary, APIs, impact
│   ├── retrieval.py          # zero-dependency BM25 code search
│   ├── assistant.py          # retrieval-grounded Q&A + local fallback
│   ├── conversation.py       # multi-turn conversation memory
│   ├── server.py             # stdlib HTTP server + JSON API
│   ├── integrations/         # optional future boundaries
│   │   ├── llm.py            # OpenRouter (implemented, optional)
│   │   ├── vector_store.py   # Qdrant (stub)
│   │   └── graph_store.py    # Neo4j (stub)
│   └── static/               # dashboard: index.html, app.js, styles.css
├── tests/                    # unittest suite
├── docs/                     # ARCHITECTURE, ROADMAP, CONTRIBUTING, FAQ
├── pyproject.toml
├── .env.example
└── README.md

📦 Installation

Requirements: Python 3.11+. That's it — there are no third‑party dependencies.

git clone https://github.com/Philipcyrus/RepoMind.git
cd RepoMind

# Option A — run in place, no install
python -m repomind analyze .

# Option B — install the CLI entry point
pip install -e .
repomind analyze .

git on your PATH is only needed to analyze a GitHub URL (RepoMind shallow‑clones it to a temp dir).

🚀 Quick Start

# 1. Analyze a repository (writes .repomind/analysis.json + .repomind/index.json)
python -m repomind analyze .

# 2. Launch the dashboard
python -m repomind serve

# 3. Open it
#    http://127.0.0.1:8765

Analyze a remote repository directly:

python -m repomind analyze https://github.com/org/repo

🖥️ CLI usage

repomind analyze <target> [--output PATH] [--json]
repomind serve   [--analysis PATH] [--host HOST] [--port PORT]
repomind --version
Command Description
analyze <target> Analyze a local path or GitHub URL. Writes <repo>/.repomind/analysis.json and index.json.
analyze -o, --output PATH Write the analysis JSON to a custom path.
analyze --json Print the full analysis JSON to stdout.
serve Serve the dashboard (default 127.0.0.1:8765).
serve --analysis PATH Serve a specific analysis file.
serve --host / --port Bind address and port.

Examples:

python -m repomind analyze . --output reports/analysis.json
python -m repomind serve --analysis reports/analysis.json --port 9000

📊 Dashboard usage

Open http://127.0.0.1:8765 after serve. The dashboard has five tabs:

  • Overview — summary, architecture layers, components, and the Repository Assistant chat.
  • Graph — the dependency graph on a canvas; filter by Files / Classes / APIs and search nodes.
  • APIs — the detected API map, filterable.
  • Impact — pick a file/symbol and see affected files, APIs, tests, and risk.
  • Guide — the generated onboarding guide.

You can also re‑analyze any path straight from the top bar.

🤖 AI Chat examples

The assistant answers from the indexed repository and always cites file + line. It works with no key (extractive answers from retrieval) and upgrades to LLM‑written prose when OPENROUTER_API_KEY is set.

# Single-shot, stateless endpoint
curl -sX POST localhost:8765/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"Where is authentication handled?"}'

Good questions to ask:

  • "Where is login implemented?"
  • "How does the BM25 retrieval scoring work?"
  • "Which files detect API routes?"
  • "What are the entry points?"

Multi‑turn conversation examples

POST /api/chat remembers the discussion, so follow‑ups feel like talking to an engineer who read the code with you. References such as "it", "that function", and "this module" are resolved against the previously discussed code, and recent turns are folded into both retrieval and the prompt.

# Turn 1 — returns a conversation_id
curl -sX POST localhost:8765/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"How does the conversation manager cap turns?"}'

# Turn 2 — pass the id back; "that module" resolves to the previous topic
curl -sX POST localhost:8765/api/chat \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"<id>","question":"and how does that module resolve pronouns?"}'

# Reset the conversation
curl -sX POST localhost:8765/api/chat \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"<id>","reset":true}'

Conversation state lives in in‑process memory (a thread‑safe, capped dict) — no Redis, no database. /api/ask stays stateless and unchanged.

🔀 Change Impact examples

Ask "if I change this, what breaks?" The analyzer precomputes an impact_index (a 2‑hop reverse dependency walk with a risk rating) for every file, class, function, method, and API.

# Via the API
curl -s "localhost:8765/api/impact?id=file:repomind/analyzer.py"

The response lists affected files, affected APIs, affected tests, and a risk of Low / Medium / High. The Impact dashboard tab exposes the same data with a dropdown selector. In local chat you can also ask "what breaks if I change X?" and get the higher‑risk change points.

🔌 Offline‑first philosophy

RepoMind is designed to be useful the moment you clone it, with nothing else installed:

  • Zero third‑party dependencies — pyproject.toml declares dependencies = []. Parsing, the graph, search, the server, and the assistant are all standard library.
  • No required services — no Neo4j, Qdrant, Docker, database, or queue to run the MVP.
  • No key required — code search is a pure‑Python BM25 index (lexical, no embeddings), and the assistant returns grounded, cited answers even with no LLM configured.
  • Graceful enhancement — features light up when you opt in, and degrade cleanly when you don't.

⚙️ Optional OpenRouter integration

To get LLM‑written answers (still grounded in retrieved snippets, still cited), set an OpenRouter key:

cp .env.example .env
# edit .env
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=openai/gpt-4.1-mini   # optional; this is the default

Without a key, the assistant automatically uses the local extractive path — nothing breaks. The NEO4J_* and QDRANT_* entries in .env.example are placeholders for future optional integrations and are not required (or used) by the MVP.

⚠️ Never commit your real .env. It is git‑ignored by default; only .env.example is tracked.

🗺️ Roadmap

RepoMind v0.1.0 delivers the local, offline MVP. Planned directions (see docs/ROADMAP.md):

  • Optional embeddings layer behind the existing search() contract (Qdrant boundary).
  • Optional Neo4j export for very large graphs (boundary already stubbed).
  • Deeper parsing (call‑graph precision, more API frameworks, GraphQL/gRPC).
  • GitHub App / one‑click analysis and syncing.

All future work preserves the zero‑dependency, offline‑first default.

🤝 Contributing

Contributions are welcome! Please read docs/CONTRIBUTING.md and our Code of Conduct.

# Run the test suite (standard library unittest — no extra installs)
python -B -m unittest discover -s tests -v

The golden rule: keep it zero‑dependency and offline‑first. New capabilities should degrade gracefully with no configuration.

📄 License

Released under the MIT License. © 2026 Philipcyrus.

🙏 Acknowledgements

  • Built entirely on the Python standard library — ast, http.server, urllib, threading.
  • Retrieval uses the well‑known BM25 ranking function.
  • Optional AI answers are powered by OpenRouter when configured.

About

AI-powered repository understanding platform that analyzes codebases, visualizes architecture and dependencies, performs impact analysis, and enables repository-aware conversations with grounded citations.

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages