RepoMap

Instant visual architecture diagrams for any GitHub repository.

Paste a public GitHub repo URL and get an interactive, folder-based flow chart of its modules, classes, functions, and dependencies — powered by tree-sitter parsing and an AI agent that can explain the codebase.

Screenshots

Landing Page	Interactive Graph

Detail Panel	AI Chat

Code Viewer

Features

Feature	Description
Universal parsing	tree-sitter supports 9 code languages + 20+ text/config formats — see Supported Languages
Folder-based flow chart	Top-down tree layout (dagre) with folder hierarchy and file groups, animated dependency edges
AI labels (on demand)	Instant structural analysis by default; click "Ask AI for detailed analysis" for a deep LLM-generated summary per file/folder
AI Architect chat	Ask questions about the codebase — architecture, patterns, entry points — answered with real file/class/function names
Code viewer	Click any file (or "View code") to read it in a VS Code Dark+ themed viewer with Prism syntax highlighting and line numbers
Markdown rendering	AI chat and analysis render `#` headings, lists, bold, inline code, and highlighted code blocks
Search	Instant filter across modules, classes, functions, and folders
Export	Save the diagram as PNG or raw JSON
Zoom & fit	Custom glassmorphism controls (zoom in / out / fit view) in the top-right corner
Live stats	Folders, files, classes, functions, lines, and language breakdown
Dark theme	Modern glass-style UI with custom thin scrollbars
Responsive	Fully responsive layout — works from 320px phones to ultrawide monitors

Supported Languages

RepoMap parses code structure (classes, functions, imports, dependencies) for 9 code languages using tree-sitter, and tracks 20+ text/config formats as line-count modules.

Code Languages (tree-sitter parsing)

Language	Extensions	Parses
Python	`.py`	Classes, functions, imports, docstrings
JavaScript	`.js`, `.jsx`, `.mjs`, `.cjs`	Classes, functions (incl. arrow), imports/exports
TypeScript	`.ts`	Classes, functions, interfaces, type aliases, imports
TSX	`.tsx`	Same as TypeScript + JSX component support
Go	`.go`	Functions, methods, structs, imports
Rust	`.rs`	Functions, impls, structs, enums, traits, imports
Java	`.java`	Classes, methods, interfaces, imports
C	`.c`, `.h`	Functions, structs, includes
C++	`.cpp`, `.cc`, `.hpp`	Functions, classes, structs, includes

Text & Config Formats (line-count modules)

These files are tracked as modules in the graph (with line counts) but don't extract classes/functions:

Category	Extensions
Config	`.yaml`, `.yml`, `.json`, `.toml`, `.ini`, `.cfg`
Web	`.html`, `.htm`, `.css`, `.scss`, `.svg`, `.xml`
Docs	`.md`, `.markdown`, `.rst`, `.txt`
Shell	`.sh`, `.bash`, `.zsh`, `.fish`
Scripts	`.ps1`, `.bat`, `.cmd`
Data	`.sql`

Named Files

Special files without extensions are also recognized:

File	Type
`Dockerfile`	Container config
`Makefile`	Build system
`Procfile`	Process manager

Adding More Languages

tree-sitter has grammars for 40+ languages. Adding support for Ruby, PHP, Swift, Kotlin, Scala, Haskell, Elixir, Dart, Lua, Perl, and others is straightforward:

Install the grammar: pip install tree-sitter-<language>
Add one entry to the LANGUAGES dict in universal_parser.py
Define extraction rules for classes, functions, and imports

Quick Start

Prerequisites

Python 3.12+
Node.js 18+
A GitHub URL to analyze

Step 1 — Backend (port `8765`)

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
uvicorn main:app --port 8765

Step 2 — Frontend (port `3000`)

cd frontend
npm install
npm run dev

Step 3 — Open & Analyze

Open http://localhost:3000, paste a GitHub repo URL, and hit Analyze.

Step 4 — (Optional) AI API key

AI labels and the chat agent use the Agnes AI API. Copy the example env file and add your key:

cd backend
copy .env.example .env   # Windows
# cp .env.example .env   # macOS / Linux

Edit .env and set your key:

AGNES_API_KEY=sk-your-key

Without a key, RepoMap still works — every module gets a structural fallback label and the codebase remains fully browsable.

Step 5 — (Optional) Customize AI prompts

All prompts live in backend/prompt.yaml (gitignored — safe from leaks). To customize:

cd backend
copy prompt.yaml.example prompt.yaml   # Windows
# cp prompt.yaml.example prompt.yaml   # macOS / Linux

Edit the prompts, then restart the backend. See the backend README for the full prompt reference.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  1. Paste GitHub URL                                             │
│  2. Backend shallow-clones the repo (kept for code viewing)      │
│  3. tree-sitter parses every supported file                      │
│     → classes, functions, imports, docstrings                    │
│  4. NetworkX builds the folder hierarchy + dependency graph      │
│  5. Structural fallback labels are generated instantly (no AI)   │
│  6. Frontend renders the interactive flow chart (dagre layout)   │
│  7. On demand: AI labels, AI chat, and code viewer               │
└─────────────────────────────────────────────────────────────────┘

Why is Analyze instant? The initial analysis uses deterministic structural fallbacks — the AI is only called when you explicitly ask (AI button, chat, code view), keeping the core flow fast and reliable.

Architecture

RepoMap/
├── backend/                          # FastAPI + tree-sitter + NetworkX
│   ├── main.py                       # API server (analyze / label / chat / code / health)
│   ├── universal_parser.py           # Multi-language tree-sitter parser
│   ├── graph.py                      # NetworkX dependency + folder graph
│   ├── labeler.py                    # AI labels + retry logic (_post_chat)
│   ├── prompts.py                    # prompt.yaml loader (falls back to .example)
│   ├── prompt.yaml                   # YOUR AI prompts (gitignored)
│   ├── prompt.yaml.example           # example prompts (committed)
│   ├── tests/                        # 61 pytest tests
│   └── requirements.txt
│
├── frontend/                         # Next.js 14 + React Flow
│   └── src/app/
│       ├── page.tsx                  # FlowApp: graph, panels, chat, code viewer, markdown
│       ├── layout.tsx                # Root layout + metadata
│       └── globals.css               # Dark theme, glassmorphism, custom scrollbars
│
└── showcase/                         # Screenshots for documentation

Backend Modules

File	Responsibility
`main.py`	FastAPI app, repo cloning, analysis pipeline, `/api/*` endpoints, in-memory cache
`universal_parser.py`	Language registry, tree-sitter parsing, text-file fallback, module extraction
`graph.py`	Dependency edges, folder tree nodes, JSON serialization with stats
`labeler.py`	Fallback + AI label generation, `_post_chat` with retry/backoff
`prompts.py`	Loads AI prompts from `prompt.yaml` (falls back to `prompt.yaml.example`)

Frontend Components (all in `page.tsx`)

Component	Purpose
`FlowApp`	Main state: URL, graph data, search, selection, viewer
`FileNode` / `FolderNode`	Custom React Flow nodes with language-colored dots
`DetailPanel`	Module details, AI button, clickable folder file list
`ChatPanel`	AI Architect chat with suggested questions
`Markdown` / `Inline`	Custom markdown renderer (headings, lists, code, bold)
`CodeViewer`	VS Code Dark+ themed code modal with Prism highlighting
`ZoomControls`	Glassmorphism zoom in / out / fit (top-right)

API Reference

Base URL: http://localhost:8765

Method	Endpoint	Description
`GET`	`/api/health`	Health check + supported languages
`POST`	`/api/analyze`	Analyze a GitHub repo → graph JSON
`POST`	`/api/label`	On-demand AI label for one node
`POST`	`/api/code`	Source code of a module (from cached clone)
`POST`	`/api/chat`	Ask the AI Architect about the codebase

`POST /api/analyze`

Body:

{ "url": "https://github.com/owner/repo" }

Response:

{
  "nodes": [...],
  "edges": [...],
  "folderNodes": [...],
  "folderEdges": [...],
  "labels": { "module_name": { "short": "...", "detailed": "..." } },
  "folderLabels": { "folder_name": { "short": "...", "detailed": "..." } },
  "stats": {
    "totalModules": 54,
    "totalFiles": 213,
    "totalClasses": 12,
    "totalFunctions": 89,
    "totalLines": 10421,
    "totalFolders": 5,
    "languages": ["python", "javascript", "typescript"],
    "languageBreakdown": { "python": 30, "javascript": 15, "typescript": 9 }
  },
  "repoUrl": "https://github.com/owner/repo",
  "repoName": "repo"
}

`POST /api/label`

Body: { "node_id": "auth" }

Response: { "short": "Authentication module", "detailed": "## Overview\nHandles user login..." }

`POST /api/code`

Body: { "node_id": "auth" }

Response:

{
  "node_id": "auth",
  "path": "auth.py",
  "language": "python",
  "content": "def login(): ...",
  "lineCount": 120
}

`POST /api/chat`

Body: { "message": "What is the overall architecture?" }

Response: { "reply": "# Architecture\n\nThe app uses..." }

Testing

cd backend
python -m pytest tests/ -v

61 tests across 4 suites — all offline (no network or AI calls):

Suite	Tests	Covers
`test_parser.py`	19	Language registry, Python/JS/TS/Go/Rust parsing, text files, multi-file repos
`test_graph.py`	13	Node/edge creation, folder tree, JSON structure, stats, empty graphs
`test_labeler.py`	12	Fallback labels, context building, folder labels, prompt loading
`test_api.py`	17	Endpoint contracts, validation, CORS

Tech Stack

Layer	Technologies
Backend	Python 3.13, FastAPI, tree-sitter, NetworkX, httpx, PyYAML, pytest
Frontend	Next.js 14, React 18, React Flow (XYFlow), dagre, PrismJS, html-to-image, TypeScript
AI	Agnes AI (`agnes-2.0-flash`) — labels + chat, with retry/backoff on transient failures

Project Status

Status	Feature
Done	Universal parser: 9 languages + 20+ text formats
Done	Instant structural analysis (~5s including clone)
Done	On-demand AI labels with fallbacks
Done	AI Architect chat with full codebase context
Done	VS Code-themed code viewer
Done	Markdown-rendered chat & analysis
Done	61 passing unit tests
Done	Responsive design (320px → ultrawide)
Done	Custom UI: zoom controls, scrollbars, glassmorphism
Planned	More languages (Ruby, PHP, Swift, Kotlin…)
Planned	Persistent repo cache & favorites
Planned	Light theme

License

MIT

Navigation Menu

Repository files navigation

RepoMap

Screenshots

Features

Supported Languages

Code Languages (tree-sitter parsing)

Text & Config Formats (line-count modules)

Named Files

Adding More Languages

Quick Start

Prerequisites

Step 1 — Backend (port `8765`)

Step 2 — Frontend (port `3000`)

Step 3 — Open & Analyze

Step 4 — (Optional) AI API key

Step 5 — (Optional) Customize AI prompts

How It Works

Architecture

Backend Modules

Frontend Components (all in `page.tsx`)

API Reference

`POST /api/analyze`

`POST /api/label`

`POST /api/code`

`POST /api/chat`

Testing

Tech Stack

Project Status

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
showcase		showcase
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

RepoMap

Screenshots

Features

Supported Languages

Code Languages (tree-sitter parsing)

Text & Config Formats (line-count modules)

Named Files

Adding More Languages

Quick Start

Prerequisites

Step 1 — Backend (port 8765)

Step 2 — Frontend (port 3000)

Step 3 — Open & Analyze

Step 4 — (Optional) AI API key

Step 5 — (Optional) Customize AI prompts

How It Works

Architecture

Backend Modules

Frontend Components (all in page.tsx)

API Reference

POST /api/analyze

POST /api/label

POST /api/code

POST /api/chat

Testing

Tech Stack

Project Status

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Step 1 — Backend (port `8765`)

Step 2 — Frontend (port `3000`)

Frontend Components (all in `page.tsx`)

`POST /api/analyze`

`POST /api/label`

`POST /api/code`

`POST /api/chat`