gitplex
See how a codebase thinks.
Paste a public GitHub repository and gitplex turns it into an interactive graph
of its files, imports, functions and calls. Explore the architecture, trace what
a change touches, find the path between two pieces of code, and export the whole
map as Markdown for your AI agent.
No API key, no account and no LLM call in the loop. Every relationship is parsed
from the syntax tree and carries the evidence that produced it, so the same
commit always gives the same map.
Live demo ·
Docs ·
Architecture
| |
|---|
| |
| Landing page | Blast radius: everything a change can reach |
| |
| Shortest path between two nodes | Hybrid search with score breakdowns |
| |
| Markdown export for agents | Light theme |
Features
- Two detail levels. Architecture Map fetches files and the imports
between them through the GitHub API without cloning (up to 2,000 files, fast).
Full Code Graph shallow-clones the repository (up to 6,000 files) and adds
functions, classes, calls and inheritance.
- Blast radius. Pick any node and see everything that depends on it, ring by
ring, with a risk summary. Copy it as Markdown or JSON.
- Path finding. The shortest chain of real relationships between two nodes,
hop by hop. Copy it too.
- Export for agents. A structured Markdown briefing of the repository
(entry points, hotspots, layout, key relationships) to paste into an AI
assistant's context.
- Hybrid search. BM25 fused with graph signals (centrality, entry points,
exact match, node type). Every hit shows its score breakdown.
⌘K opens the
palette; file:, function:, class:, route: and test: prefixes narrow it.
- Guided tour and entry points. Starting places detected from manifests,
filename conventions, framework imports and centrality, plus a narrated tour
that flies the camera through the graph.
- Repository profile and structure tree. Coupling shape, test culture,
hotspots and external dependencies, plus the on-disk tree with rolled-up
counts.
- Four layouts. Force (off-thread ForceAtlas2), Folders, Layers (by
dependency depth) and Rings.
- Evidence, not guesses. Direct relationships are drawn straight; inferred
ones curve and carry a confidence score. Partial analyses say so up front.
- Recent maps and a repository switcher to jump between analyses.
- Dark and light themes, four accent colours (Grass, Psychic, Water, Fire).
- Huge repositories are analysed in part, not refused. VS Code and the Linux
kernel both work, with coverage stated in the UI.
Language support
| Tier | Languages | What you get |
|---|
| Full code graph | Python, JavaScript, TypeScript (including JSX and TSX), Go, Java | Files, imports, functions, classes, calls, inheritance, routes |
| Files and imports | Rust, Kotlin, Swift, C, C++, C#, Ruby, PHP, Scala, Dart, Elixir, Erlang, Haskell, OCaml, Clojure, Julia, Lua, Perl, R, Bash, PowerShell, Groovy, Objective-C, Fortran, Solidity, Zig, Vim script | Files and the import graph between them |
Adding symbol extraction for another language means implementing one interface
(backend/app/core/symbol_extractors/base.py); the graph builder doesn't change.
Quick start
You need Docker with Compose and nothing else.
git clone https://github.com/yadavdevv/gitplex.git
cd gitplex
cp .env.example .env
docker compose up --build # or: docker-compose up --build
Paste a repository and watch it map. https://github.com/psf/requests is a good
first one: a few seconds as an Architecture Map, still quick as a Full Code Graph.
The ports are deliberately non-default (6390 rather than 6379, and so on) so the
stack doesn't collide with databases you already run. Change them in .env.
Locally, FalkorDB also acts as the plain Redis store; it is a Redis module.
A GITHUB_TOKEN in .env is optional. It raises GitHub API limits, which helps
Architecture Maps of large repositories.
Local development
Backend (use a virtualenv, not your system Python; Python 3.11+):
docker compose up -d falkordb # datastore only
cd backend
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
FALKORDB_HOST=localhost FALKORDB_INTERNAL_PORT=6390 \
REDIS_HOST=localhost REDIS_INTERNAL_PORT=6390 \
.venv/bin/uvicorn app.main:app --reload --port 8420
The analysis worker runs inside the API process by default
(RUN_WORKER_INPROCESS=true). To run it separately, set that to false and
start arq app.workers.tasks.WorkerSettings.
Frontend (Node 20+):
cd frontend
npm install
echo "NEXT_PUBLIC_API_BASE_URL=http://localhost:8420/api/v1" > .env.local
npm run dev # http://localhost:3000
CORS_ORIGINS in .env.example allows ports 3000, 3200 and 3201. Hot-reloading
containers for both services: docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build.
Testing
# Backend (integration tests skip themselves when FalkorDB is unreachable)
cd backend
.venv/bin/ruff check app tests
.venv/bin/mypy app
FALKORDB_HOST=localhost FALKORDB_INTERNAL_PORT=6390 \
REDIS_HOST=localhost REDIS_INTERNAL_PORT=6390 REDIS_DB=9 .venv/bin/python -m pytest
# Frontend
cd frontend
npm run lint && npm run typecheck && npm test
npx playwright install chromium
npm run test:e2e # mocked API, no backend required
CI runs all of this on every push (ci.yml).
How it works
Next.js (App Router) ──HTTP──► FastAPI ──► FalkorDB typed code graph
Sigma.js / WebGL │ ──► Redis jobs, search corpus, insights
│
ARQ worker ──► fetch or clone → tree-sitter → graph
Each analysed commit and detail level is its own FalkorDB graph, so queries need
no tenancy filters and eviction is one GRAPH.DELETE. Reads are label-routed,
indexed Cypher with per-process caches; path search is a breadth-first search
over a cached edge list. Details, trade-offs and failure behaviour are in
docs/ARCHITECTURE.md.
Deployment
The reference deployment is a Vercel frontend, a Render backend (API and worker
in one container), FalkorDB Cloud and Upstash Redis, all on free tiers. Step by
step, including the keep-alive setup, is in DEPLOY.md. Kubernetes
manifests are in infra/k8s. Put the backend in the same region as
its databases; cross-region hops dominate latency.
Limitations
These are deliberate boundaries, not bugs:
- Call resolution is name-based, not a language server. A call is resolved
within its file, then through imports, then by a repo-unique name, and the edge
is dropped when still ambiguous rather than guessed. Expect roughly 40–60%
of calls to resolve; the rest are counted in
stats.unresolved_calls.
- No dynamic behaviour. Reflection, runtime imports, monkey-patching and
dependency injection are invisible to static analysis.
- Route detection is heuristic: FastAPI and Flask decorators, Express
app.get(...), Next.js file conventions.
- Public repositories only. No OAuth.
- Large repositories are analysed in part. Over the file budget, paths are
ranked (source roots and entry points first, tests and examples last) and the
top ones analysed. The UI states the fraction covered. Search indexes at most
25,000 documents.
- Free-tier hosting is small. FalkorDB's free tier caps at 100 MB, so the
least-recently-viewed graphs are evicted; a cleared map is mapped again on
request. New analyses are limited to 8 per hour per address.
- Vendor, generated and minified paths (
node_modules, .venv, dist, .next,
…) and files over MAX_FILE_SIZE_KB are skipped.
Contributing
Issues and pull requests are welcome.
- Keep the core deterministic. Anything that needs a LLM call goes behind a flag
and degrades gracefully when off.
- Never invent a relationship. If it can't be resolved statically, drop the edge
and set
confidence honestly.
- Extractor changes need a test in
backend/tests/unit/; graph schema changes
need one in backend/tests/integration/ and an update to
docs/GRAPH_SCHEMA.md.
- Run lint, typecheck and tests for both services before opening a PR.
Documentation
- docs/ARCHITECTURE.md: services, data flow, caching, memory management
- docs/GRAPH_SCHEMA.md: nodes, edges, evidence model, Cypher examples
- docs/API.md: endpoint contract
- docs/UI_DESIGN.md: the Phosphor design system, interactions, accessibility
- docs/DECISIONS.md: why FalkorDB, why tree-sitter, why deterministic-first
- DEPLOY.md: free-tier deployment guide
License
MIT. See LICENSE.
