One project universe. Every coding agent.
KawnGraph maps code, docs, data, tests, and Git changes into evidence-backed Context Packs so Claude, Codex, and Cursor can reach the right files without reading the entire repository.
English · العربية · Español · Français · Deutsch · Português (BR) · 简体中文 · 繁體中文 · 日本語 · 한국어 · हिन्दी · Bahasa Indonesia · Türkçe · Русский · Italiano · فارسی · اردو · Polski · Nederlands · Українська · Tiếng Việt · ภาษาไทย · Svenska · Ελληνικά · Română · Čeština · Suomi · Dansk · Norsk · Magyar · עברית
English is canonical · العربية is AI-assisted · owner review pending · the other 29 languages are machine-assisted (human review needed) — see translation status.
Quick Start · How It Works · Studio · Benchmarks · Docs · Contributing
When you give a coding agent a task, it usually starts by reading — a lot. It opens dozens of files, re-derives how routes reach the database, and rebuilds the same mental model on every request. That is slow, token-expensive, and often inaccurate: the agent misses the one file that matters and drowns in five that do not.
KawnGraph scans the repository once, builds a layered, evidence-backed graph of how things relate, then answers, for a specific task, with the few files that matter — plus the relevant docs, the related database tables, the tests to run, and the risks to watch. That bundle is a Context Pack. The graph is the substrate; the Context Pack is the product.
Give agents the map, not the repo. — اعطِ الإيجنت الخريطة، مو المشروع كامل.
Install and run KawnGraph with one command — npx fetches it, nothing to
clone (Node ≥ 18):
npx kawngraph setup # scan, detect your agents, connect them, verify retrieval
kawn check # health: is the graph fresh? who is connected?
kawn map # open the local, read-only visual explorerOr from source (this monorepo, for contributors — pnpm):
pnpm install && pnpm build # build the workspace
pnpm kawn setup --agent all --yes # scan + connect Claude Code / Codex / Cursor
pnpm kawn check # is the graph fresh? who is connected?
pnpm studio:build && pnpm kawn map # open the read-only visual explorerThen open your agent and just describe your task — it pulls the few files that matter, on its own. No API keys, no telemetry, no network calls during scan or retrieval. New to it? Start with docs/GETTING_STARTED.md.
The point of KawnGraph is that the agent reaches for the map automatically.
One command wires a project to the agents you use — without editing CLAUDE.md
or AGENTS.md, every change reversible:
kawn setup # scan if needed, detect agents, connect, verify
kawn setup --agent all --yes # non-interactive (CI), every supported agent
kawn setup --dry-run # preview the exact file changes, write nothing
kawn status # is the graph fresh? who is connected?
kawn disconnect codex # cleanly remove only KawnGraph's entrysetup detects your coding agents — Claude Code, Codex, Cursor,
Copilot, Gemini CLI, and Aider (plus a generic Markdown/JSON export
and an optional local LLM) — and installs a read-only integration scoped to
the project (.mcp.json, .cursor/mcp.json, .codex/config.toml,
.vscode/mcp.json, .gemini/settings.json, or an Aider context file), backing up
anything it touches and verifying each MCP server with a live handshake. Full
contract: docs/AGENT_INTEGRATION.md.
The MCP server is a read-only stdio JSON-RPC loop with no MCP SDK (hand-rolled) and four tools:
| Tool | What it does |
|---|---|
kawn_context |
Token-budgeted Context Pack for a task. |
kawn_query |
Ranked, mode-scoped search over the graph. |
kawn_affected |
Reverse impact: what depends on a symbol. |
kawn_changes |
Impact of the current change set (uncommitted, or a branch vs a base ref). Local git only. |
It only reads the graph — it never scans, rebuilds, or writes it (it warns
when the graph looks stale and points to kawn update).
A project is not just code. It is code and docs and SQL and tests and the configuration that ties them together. KawnGraph models each as a distinct layer, so a query asks for exactly what it needs and nothing it does not — a code-impact query never drags in marketing docs; a docs query never returns raw call graphs unless you ask.
| Layer | Examples |
|---|---|
code |
files, functions, classes, imports, calls, routes |
data |
SQL tables, migrations, foreign keys |
config |
workspace packages, dependencies |
docs |
markdown sections, links, mentions |
test |
tests and what they cover |
Edges carry evidence (source path, line range, snippet) and a confidence level — mechanically derived where the scanner can attach it; every node has a stable, content-addressable ID so the graph stays diffable across scans. Deeper model: docs/GRAPH_MODEL.md.
$ kawn ask "fix the Zid OAuth callback that writes store tokens"
Must-read
app/api/zid/oauth/callback/route.ts entry route
packages/zid/src/oauth.ts token exchange
packages/db/.../storeTokens.ts writes store_tokens
Docs
docs/zid-oauth-core.md#callback-flow expected behaviour
Tables
store_tokens (written) · merchants (fk)
Tests oauth.test.ts
Risks token encryption · tenant isolation
Excluded unrelated UI components (over budget) · confidence 0.6
The same pack is available as Markdown, JSON, or the agent-neutral Universal
Context Protocol (--format ucp / ucp-md). More:
docs/CONTEXT_PACKS.md.
kawn map opens KawnGraph Studio — a local, read-only explorer served
over 127.0.0.1 that reads the existing .kawn/graph.json and never scans,
rebuilds, or writes. It offers an interactive 2D graph, a scalable 3D "Universe"
star-map (budgeted so it never draws a whole large graph at once), a Context-Pack
builder, reverse-impact, Git-change views, and a behavioral benchmark view. Built
in English and Arabic (RTL-aware). Run it from source with pnpm studio:build && pnpm kawn map.
The 3D Universe view — this repository's own graph (1,261 nodes), read-only.
The 2D constellation Map — a force-directed star-map of the graph (nodes coloured by layer, sized by degree), with filters, search, hover, and zoom.
A neutral comparison of approaches (not a competitor attack). Every cell is defensible; "varies" means it depends on the specific tool.
| Capability | Plain search | General RAG | Generic graph viewer | KawnGraph |
|---|---|---|---|---|
| Deterministic local scan | ✅ | varies | ✅ | ✅ |
| Symbol-level relationships | ❌ | varies | ✅ | ✅ |
| Docs / data / test layers | ❌ | varies | varies | ✅ |
| Evidence on edges | ❌ | ❌ | varies | ✅ |
| Bounded impact analysis | ❌ | ❌ | varies | ✅ |
| Git-change context | varies | ❌ | ❌ | ✅ |
| Token-budgeted Context Packs | ❌ | varies | ❌ | ✅ |
| Read-only MCP retrieval | ❌ | varies | varies | ✅ |
| No internal LLM required | ✅ | ❌ | ✅ | ✅ |
A dated, sourced, three-column comparison against a mature graph tool (capabilities KawnGraph leads on and capabilities it does not) lives in docs/COMPARISON.md.
KawnGraph ships a local A/B harness that runs the same agent on the same task with vs without KawnGraph and records behavior. Results are honest and task-dependent — including neutral and negative cases.
Local A/B harness: 72 sessions run, 60 usable across 10 task cells, seed 1, 3 repeats per arm (3/arm after grouping — exploratory, n<5, directional only). Same agent, same task, same repository snapshot; A = without KawnGraph, B = with. Δ = B − A. 12 of 72 sessions were excluded for gold provenance (see the artifact). Gold validation: all retained runs have a valid gold reference.
Headline task — zid-oauth (retrieval) on nextjs-supabase:
Claude Code — same task, same repository, same model (model not pinned in artifact):
| Metric | Without KawnGraph | With KawnGraph | Difference |
|---|---|---|---|
| task correctness | 100% | 100% | 0 pp |
| automatic KawnGraph invocation | 0% | 100% | +100 pp |
| relevant files found (recall) | 100% | 93% | -7 pp |
| opened-file precision | 83% | 89% | +6 pp |
| distinct files opened | 6 | 5.3 | -0.7 |
| tool calls | 8.3 | 8.7 | +0.3 |
| time to first relevant file | 20.7 s | 22.4 s | +1.7 s |
| total wall time | 54.6 s | 61.9 s | +7.3 s |
| output tokens | 2,867 | 3,130 | +262 |
Codex — same task, same repository, same model (model not pinned in artifact):
| Metric | Without KawnGraph | With KawnGraph | Difference |
|---|---|---|---|
| task correctness | 100% | 100% | 0 pp |
| automatic KawnGraph invocation | 0% | 0% | 0 pp |
| relevant files found (recall) | 80% | 87% | +7 pp |
| opened-file precision | 25% | 61% | +36 pp |
| distinct files opened | 1 | 4.3 | +3.3 |
| tool calls | 2.7 | 8 | +5.3 |
| time to first relevant file | 18.7 s | 17.8 s | -884 ms |
| total wall time | 36.4 s | 41 s | +4.5 s |
| output tokens | 822 | 1,082 | +260 |
KawnGraph is task-dependent. It can reduce repository exploration on unfamiliar multi-file work, while adding overhead on already-focused tasks. See the full methodology and limitations in docs/BENCHMARKS.md.
Where it helped, was neutral, or hurt (all 10 task cells):
| Task family | Agent | Mode | Outcome | Tool-call Δ | Time Δ |
|---|---|---|---|---|---|
| context-pack-ranking | claude | retrieval | Neutral | -0.3 | +6.2 s |
| docs-to-code-linking | claude | retrieval | Neutral | -0.3 | +9.6 s |
| freshness-gate | claude | retrieval | Improved | -9.7 | -54.6 s |
| oauth-code-guard | claude | e2e | Neutral | -0.3 | +5.9 s |
| zid-oauth | claude | retrieval | Regressed | +0.3 | +7.3 s |
| context-pack-ranking | codex | retrieval | Regressed | +4 | +33.3 s |
| docs-to-code-linking | codex | retrieval | Improved | -0.7 | -4.6 s |
| freshness-gate | codex | retrieval | Neutral | 0 | -2.1 s |
| oauth-code-guard | codex | e2e | Regressed | 0 | +1.5 s |
| zid-oauth | codex | retrieval | Regressed | +5.3 | +4.5 s |
Outcome labels (Improved / Neutral / Regressed / Insufficient data) are derived deterministically from tool-call and wall-time deltas; every cell is n=3/arm, so all are directional. Full per-metric tables: benchmarks/published/campaign-2026-06-20.md.
Methodology, environment, sample sizes, the per-metric tables, and limitations:
docs/BENCHMARKS.md — generated from the committed,
validated artifact in benchmarks/published/.
Every language/format is a versioned scanner plugin behind one registry (detect → scan → finalize): deterministic order, per-file failure isolation, explicit registration, and bounded file sizes.
| Language / format | Extracted |
|---|---|
| TypeScript / JS | files, top-level functions/classes, imports, calls, Next.js routes, tests |
| Python | top-level def/async def/class, decorators, methods (as metadata), imports, FastAPI/Flask routes, docstrings, tests (via @lezer/python — pure-JS, error-tolerant) |
| SQL | tables (CREATE/ALTER), foreign-key relationships |
| package.json | workspace packages and internal dependencies |
| Markdown | headings/sections linked to code, SQL, and routes |
Two deliberate omissions in both code scanners: methods/nested functions are
never separate nodes (a method rides on its class as metadata), and ambient
declaration files (.d.ts, .pyi) are never claimed. Details:
docs/SCANNERS.md.
- No network by default. Scan and retrieval read your repo and write JSON
under
.kawn/. Nothing leaves the machine. - No internal LLM. Code, docs, and SQL are parsed structurally; AI enrichment is opt-in and local-first.
- No telemetry. No query logging by default.
- Read-only MCP. The server serves the graph; it never scans, rebuilds, or writes — and refuses to serve a graph whose schema it cannot trust.
- Reversible, project-scoped integrations. Atomic writes, timestamped
backups, structured (not string) config edits; never edits
CLAUDE.md/AGENTS.md, never touches global config by default.
Full model: docs/PRIVACY.md. Report a vulnerability privately via SECURITY.md.
KawnGraph is in active development (v0.1.0, not yet published to npm). Built
and tested end-to-end: the code/data/config/docs/test graph, docs-to-code links,
mode-scoped query, impact analysis, Git/PR impact, token-budgeted Context Packs,
the Universal Context Protocol, the read-only MCP server, one-command agent setup
(Claude Code, Codex, Cursor, Copilot, Gemini, Aider, generic export, local LLM),
Studio, and the A/B benchmark harness.
Honest limits. The published benchmark is exploratory (n<5 per arm — directional, not significant). KawnGraph helps most on unfamiliar multi-file discovery and can add overhead on already-focused single-file tasks. Not built yet: opt-in suggest-only hooks, the visual layer, semantic/AI enrichment, and a runtime layer — all opt-in by design. See PROJECT_PLAN.md · ARCHITECTURE.md · docs/FAQ.md · docs/TROUBLESHOOTING.md.
| Guide | What's inside |
|---|---|
| Getting started | Install, scan, first Context Pack |
| Agent integration | MCP setup contract, reversibility |
| Context Packs | Ranking, budgets, UCP wire format |
| Graph model | Nodes, edges, layers, evidence, IDs |
| Scanners | What each language plugin extracts |
| Benchmarks | Methodology, environment, full results |
| Comparison | Dated, sourced capability comparison |
| Privacy | Data boundaries per layer |
| Troubleshooting · FAQ | Common issues & questions |
Contributions are welcome. Build from source, run the suite, and read the guide:
pnpm install && pnpm build
pnpm test # node:test suite (graph, context, MCP, agents, Studio)
pnpm pack:check # packaging audit (packs every package, installs from tarballs)See CONTRIBUTING.md for setup, conventions, and the privacy review every PR passes; CODE_OF_CONDUCT.md for community expectations; docs/i18n/TRANSLATING.md to add or review a language; and SUPPORT.md for where to ask questions.
MIT © KawnGraph contributors.
Created & maintained by Abdulrahman Alnashri.
Kawn (Arabic كَوْن — cosmos, universe, existence) treats a repository as
a living universe of knowledge; Graph is the evidence-backed Agent Context
Graph at its core. Built with TypeScript,
Vite, React,
React Flow, Three.js, and
@lezer/python.