Kawngraph

The Agent Context Universe

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.

[](https://xd7fx.github.io/kawngraph-site/) [](https://www.npmjs.com/package/kawngraph) [](LICENSE) [](package.json) [](tsconfig.base.json) [](docs/PRIVACY.md) [](docs/PRIVACY.md) [](SUPPORT.md) [](https://www.linkedin.com/in/abdulrahman-alnashri-ai/) [](https://github.com/sponsors/xd7fx)

English · [العربية](README.ar.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Deutsch](docs/i18n/README.de.md) · [Português (BR)](docs/i18n/README.pt-BR.md) · [简体中文](docs/i18n/README.zh-CN.md) · [繁體中文](docs/i18n/README.zh-TW.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [हिन्दी](docs/i18n/README.hi.md) · [Bahasa Indonesia](docs/i18n/README.id.md) · [Türkçe](docs/i18n/README.tr.md) · [Русский](docs/i18n/README.ru.md) · [Italiano](docs/i18n/README.it.md) · [فارسی](docs/i18n/README.fa.md) · [اردو](docs/i18n/README.ur.md) · [Polski](docs/i18n/README.pl.md) · [Nederlands](docs/i18n/README.nl.md) · [Українська](docs/i18n/README.uk.md) · [Tiếng Việt](docs/i18n/README.vi.md) · [ภาษาไทย](docs/i18n/README.th.md) · [Svenska](docs/i18n/README.sv.md) · [Ελληνικά](docs/i18n/README.el.md) · [Română](docs/i18n/README.ro.md) · [Čeština](docs/i18n/README.cs.md) · [Suomi](docs/i18n/README.fi.md) · [Dansk](docs/i18n/README.da.md) · [Norsk](docs/i18n/README.no.md) · [Magyar](docs/i18n/README.hu.md) · [עברית](docs/i18n/README.he.md)

English is canonical · العربية is AI-assisted · owner review pending · the other 29 languages are machine-assisted (human review needed) — see [translation status](docs/i18n/STATUS.md).

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Studio](#studio) · [Benchmarks](#benchmarks) · [Docs](#documentation) · [Contributing](#contributing)

---

---

Why KawnGraph?

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. — اعطِ الإيجنت الخريطة، مو المشروع كامل.

---

Quick Start

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 explorer

Or 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 explorer

Then 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/GETTINGSTARTED.md](docs/GETTINGSTARTED.md).

---

Connect it to your coding agent

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 entry

setup 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/AGENTINTEGRATION.md](docs/AGENTINTEGRATION.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).

---

How It Works

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/GRAPHMODEL.md](docs/GRAPHMODEL.md).

A Context Pack, end to end

$ 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/CONTEXTPACKS.md](docs/CONTEXTPACKS.md).

---

Studio

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.

---

KawnGraph vs. plain repository search

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](docs/COMPARISON.md).

---

Benchmarks

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 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](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](benchmarks/published/campaign-2026-06-20.md).

Methodology, environment, sample sizes, the per-metric tables, and limitations: [docs/BENCHMARKS.md](docs/BENCHMARKS.md) — generated from the committed, validated artifact in [benchmarks/published/](benchmarks/published/).

---

Supported scanners & layers

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](docs/SCANNERS.md).

---

Privacy & security

• 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](docs/PRIVACY.md). Report a vulnerability privately via [SECURITY.md](SECURITY.md).

---

Status & limitations

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 [PROJECTPLAN.md](PROJECTPLAN.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/FAQ.md](docs/FAQ.md) · [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

---

Documentation

| Guide | What's inside | | ----- | ------------- | | [Getting started](docs/GETTINGSTARTED.md) | Install, scan, first Context Pack | | [Agent integration](docs/AGENTINTEGRATION.md) | MCP setup contract, reversibility | | [Context Packs](docs/CONTEXTPACKS.md) | Ranking, budgets, UCP wire format | | [Graph model](docs/GRAPHMODEL.md) | Nodes, edges, layers, evidence, IDs | | [Scanners](docs/SCANNERS.md) | What each language plugin extracts | | [Benchmarks](docs/BENCHMARKS.md) | Methodology, environment, full results | | [Comparison](docs/COMPARISON.md) | Dated, sourced capability comparison | | [Privacy](docs/PRIVACY.md) | Data boundaries per layer | | [Troubleshooting](docs/TROUBLESHOOTING.md) · [FAQ](docs/FAQ.md) | Common issues & questions |

---

Contributing

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](CONTRIBUTING.md) for setup, conventions, and the privacy review every PR passes; [CODEOFCONDUCT.md](CODEOFCONDUCT.md) for community expectations; [docs/i18n/TRANSLATING.md](docs/i18n/TRANSLATING.md) to add or review a language; and [SUPPORT.md](SUPPORT.md) for where to ask questions.

---

License & acknowledgements

[MIT](LICENSE) © 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](https://lezer.codemirror.ne

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xd7fx
• Source: xd7fx/kawngraph
• License: MIT
• Homepage: https://xd7fx.github.io/kawngraph-site/

Install and usage instructions live in the source repository linked above.