KawnGraph GitHub

The Agent Context Universe

Give agents the map, not the repo.

KawnGraph scans code, docs, data, tests, and Git changes into an evidence-backed project graph, then gives coding agents focused Context Packs for the task at hand.

npx kawngraph setup
View on GitHub Open npm
Local-first
No cloud required for scan or retrieval.
No telemetry
Your project stays on your machine.
Read-only MCP
Agents retrieve context without writing.
kawn check 
[PASS] Agent Context Graph: fresh
[PASS] MCP server resolvable: npx -y @kawngraph/mcp@0.1.1
[PASS] MCP handshake + retrieval
[PASS] Integration: claude, codex

healthy - 5 pass - 0 warn - 0 fail

The problem

Coding agents still waste time rereading repositories.

When you give an 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 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.

How it works

Scan once. Serve precise context.

01

Scan

Read project structure locally: code, Markdown, SQL, packages, tests, and Git changes.

02

Graph

Build a layered graph with evidence on relationships, stable IDs, and freshness metadata.

03

Context Pack

Return the few files, docs, tables, risks, and tests relevant to a specific task.

04

Agent

Expose retrieval through CLI, MCP, and Studio without making agents read the full repo.

KawnGraph reads your repo with deterministic scanners into one layered graph at .kawn/graph.json (code, data, config, docs, test layers), served read-only to the kawn CLI, the MCP server, and Studio. No network, no LLM, no telemetry.
Deterministic scanners build one layered graph, served read-only to the CLI, MCP, and Studio.
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

Context Packs

The graph is the substrate. The Context Pack is the product.

A task flows into KawnGraph, which returns a token-budgeted Context Pack: must-read files, related docs, tables, tests, risks, an excluded list, and a confidence score.
kawn ask 
$ 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 (over budget) · confidence 0.6

Read-only MCP

Four retrieval tools. Zero writes.

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. Local git only.

Agent support

One project universe. Every coding agent.

Claude Code Codex Cursor GitHub Copilot Gemini CLI Aider Generic export Local LLMs

Studio

Inspect the graph locally.

kawn map opens a local, read-only explorer for the existing .kawn/graph.json: an interactive 2D graph, a scalable 3D Universe view, a Context Pack builder, reverse-impact, Git change views, and benchmark reports. Served over 127.0.0.1 — it never scans, rebuilds, or writes.

KawnGraph Studio — the read-only 3D Universe view of this repository's own graph: 1,261 nodes clustered by layer with connection lines and per-layer filters.
The 3D Universe view — this repository's own graph (1,261 nodes), read-only.
KawnGraph Studio — the 2D graph view of the bundled example project: files, functions, routes, tables, and docs as nodes with labeled evidence-backed edges.
The 2D graph view — the bundled example project, with layer / type / edge filters.

Benchmarks

Honest, and task-dependent.

KawnGraph ships a local A/B harness that runs the same agent on the same task with vs without KawnGraph. Results are honest and task-dependent — including neutral and negative cases. It can reduce repository exploration on unfamiliar multi-file work, while adding overhead on already-focused tasks.

Read the methodology

Privacy model

Built for local control.

No telemetry

KawnGraph does not phone home during scan or retrieval.

No internal LLM required

Core scanning and Context Packs are deterministic.

Project-scoped setup

Agent integrations are reversible and scoped to the repository.

Install

Start with one command.

npx kawngraph setup
kawn check kawn map kawn ask "fix the OAuth callback"