Map your codebase, navigate any part.
A local code-knowledge-graph daemon that gives AI agents structural navigation across one or many repos. A companion to grep, not a replacement — its value is navigation; token savings is a side effect.
Where grep gets lost, grafel shows the way.
The difference, one question at a time
Pick a real question an AI agent gets asked. Watch it grind through the grep way, then toggle to the grafel way — the answer as a graph: complete, connected, and correct — where grep could only guess.
How the AI talks to it
grep matches text across files. grafel maps the structure between them — the questions grep can't answer: where X is defined, who calls Y, how a request flows end to end, what a rename really breaks.
grep matches characters across files; grafel resolves what those characters are — a call, a query, a route — and how they connect.
Every TODO or every if err != nil is a grep job. "Who calls X?" is a graph traversal.
grep runs anywhere with nothing to install; grafel trades that for a typed index spanning every repo in the group.
grep returns matching lines; grafel returns the function, the caller, and the typed edge between them.
grep stops at a repo boundary; grafel follows a field across the wire into Terraform, Kafka, and the DB.
grep hands back everything it matched; grafel ranks the right symbol to the top and connects it to its neighbors.
An HTTP field crossing repos is invisible to text search; grafel tracks its shape end to end, DTO to DTO.
grep answers by making the agent open every file; grafel answers directly over the Model Context Protocol.
grafel narrows a 500-file repo to the 8 handlers that matter; grep then verifies the exact string inside them.
If the question is "where/who/how does it connect," reach for grafel. If it's "every instance of this string," reach for grep.
Coverage matrix
Tree-sitter extractors plus framework-aware passes recover the edges that matter — routes, models, jobs, ORM queries, topics — tracked in a generated coverage matrix, not a marketing claim.
The graph model
Extraction turns source into a graph: nodes are the things in your system, edges are how they relate — the same shape whether it's a function call or a Kafka topic.
The nodes — what exists in the system.
The typed edges — how nodes connect.
The complete set, generated from the type registry.
Under the hood
From AST to graph math — every phase runs on your machine and lands in one compact artifact (graph.fb), never a cloud.
Language-aware parsers turn source across 39 languages into typed syntax trees — functions, types, endpoints, fields — the base entities and edges every later pass is built on.
e.g. a Python module → its classes, functions and imports, typed and located, not just lines of text.
Dedicated analyzers recognize each framework, ORM and tool separately — Spring, Django, FastAPI, Rails, React, Play, Quartz and more — then staged passes resolve references and imports and trace data-lineage, process & event flow, coupling and shared databases: the semantic edges generic parsing can't see.
e.g. a FastAPI route → its handler → the ORM model → the orders table, linked into one traversable path.
Term-frequency × inverse-document-frequency with length normalization — how find ranks the right symbol to the top, where naive grep returns everything and orders nothing.
e.g. agent asks "find the auth middleware" → AuthMiddleware ranked #1, above 200 raw string matches of "auth".
Callers, reachability and end-to-end paths resolve in a hop across typed edges — the single query that replaces reading N files to trace a chain by hand.
e.g. "who calls PaymentService.charge?" → 3 callers across 2 repos in one hop, no file reads.
PageRank surfaces load-bearing code, community detection recovers module boundaries, betweenness finds articulation points, and taint-flow & def-use passes follow data through the system.
e.g. "what's load-bearing here?" → PageRank surfaces DbPool + AuthMiddleware; community detection recovers the 6 modules.
An always-on server exposes the graph over MCP while a background engine re-indexes incrementally on each commit — memory-tiered, with a live status plane, and it never phones home.
e.g. the agent queries over MCP while the engine re-indexes your last commit — the answer is always current, no manual reindex.
Get started
A local binary — no account, no cloud call. Install it, then run the wizard from any repo (or a folder of repos) and ask the question you couldn't grep.
Downloads the latest release binary into ~/.grafel/bin.
Downloads the latest release binary into ~/.grafel/bin.
Recommended — PowerShell:
Or from CMD:
Installs into %USERPROFILE%\.grafel\bin, no admin rights required.
git clone https://github.com/cajasmota/grafel.git cd grafel make build # builds dashboard (npm) + Go binary ./grafel --version
Prereqs: Go 1.26+ (CGO enabled), a C/C++ compiler, Node.js 20+ & npm (dashboard build), git.
Optional system-wide install: go install -ldflags="-X main.commit=$(git rev-parse --short HEAD)" ./cmd/grafel
Run grafel wizard from your project root to index a single repo — or from a folder that holds several repos to map them as one connected group. The wizard detects what's there, builds the graph, starts the file watcher, and wires up the MCP server for your agent. Everything runs on your machine and stays there.