Karna
Your codebase, as a knowledge graph. For AI agents that don't waste tokens.
pip install karna && karna serve .
One command. Your AI agent now understands your entire codebase.
The Problem
Every time an AI coding agent starts a task, it reads files from scratch. Each file-read stays in the conversation history and gets retransmitted on every subsequent turn. We call this the Conversation History Tax -- and it grows quadratically with turn count.
An 8-turn coding session doesn't cost 8x a single turn. It costs 36x.
The result? You're burning tokens (and money) on context the agent already saw.
The Solution
Karna builds a persistent knowledge graph of your codebase -- every class, function, method, import, call, test, and contributor -- indexed and queryable in sub-second time. Instead of reading files turn after turn, your agent calls one tool and gets everything it needs.
|
Without Karna
|
With Karna
|
Proven Results
This isn't a benchmark game. We ran a real agent A/B study -- Claude Sonnet 4, live API calls, actual coding tasks on a 1,125-file production codebase (FastAPI).
| Task | Baseline | Karna | Savings |
|---|---|---|---|
| Add rate limiting middleware | 17,243 | 8,613 | 50.0% |
| Fix WebSocket authentication bug | 21,950 | 9,077 | 58.6% |
| Refactor dependency injection | 17,096 | 8,013 | 53.1% |
| Add response caching layer | 17,188 | 8,623 | 49.8% |
| Improve OpenAPI generation | 30,274 | 9,403 | 68.9% |
| Mean | 20,750 | 8,746 | 57.9% |
Paired t-test: t(4) = 5.18, p < 0.007, Cohen's d = 2.96 (large effect). Full methodology and statistical analysis in the paper.
Works With Every MCP-Compatible Editor
Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"karna": {
"command": "karna",
"args": ["serve", "--no-live-view", "."]
}
}
}
Claude Code
Add to .mcp.json:
{
"mcpServers": {
"karna": {
"type": "stdio",
"command": "karna",
"args": ["serve", "--no-live-view", "."]
}
}
}
Gemini CLI
Add to settings.json:
{
"mcpServers": {
"karna": {
"command": "karna",
"args": ["serve", "--no-live-view", "."]
}
}
}
What Karna Extracts
Karna parses your code into a richly-connected graph:
| Layer | What it captures |
|---|---|
| Entities | Classes, functions, methods, modules, files, tests, configs, packages, contributors |
| Relationships | contains, imports, calls, defines, inherits, tested_by, owned_by, co_changed |
| Call graphs | Intra-file function-to-function call edges |
| Body previews | First 10 lines of every function, class, and method |
| Git history | Authorship, file ownership, co-change patterns |
| Entity resolution | Automatically discovers implicit links -- test-to-implementation, cross-module dependencies |
Validated on 1,556 source files across three repositories with zero parse errors:
| Repository | Language | Files | Entities | Relationships |
|---|---|---|---|---|
| FastAPI | Python | 1,125 | 6,488 | 8,200 |
| Zod | TypeScript | 391 | 1,431 | 2,911 |
| Karna | Python | 40 | 446 | 1,198 |
MCP Tools
The star tool is karna_task_context -- complete context in one call, one turn, minimal tokens.
| Tool | What it does |
|---|---|
karna_task_context(task) |
One-shot context: entities, files to modify, tests, relationships, body previews |
karna_understand(topic) |
Lightweight overview of matching entities |
karna_plan(task) |
Planning mode: files to modify, tests to update |
karna_context_for(role, task) |
Role-specific context (implementer, test writer, reviewer) |
karna_files_to_edit(task) |
Targeted file list with line ranges |
karna_read_entity(name) |
Full entity detail with call graph and relationships |
karna_changed(file) |
Incremental re-parse after edits |
karna_status() |
Graph statistics |
karna_who(file) |
File ownership and connections |
Architecture
Source Code ──> Parsers ──> Entity Resolution ──> SQLite + FTS5 ──> MCP Server ──> AI Agents
| | | |
|-- Python AST |-- Blocking |-- Entities |-- Cursor
|-- TypeScript |-- Scoring (6 dim) |-- Relationships|-- Claude Code
|-- Git History |-- Union-Find |-- FTS5 Index |-- Gemini CLI
|-- Filesystem |-- Any MCP client
Live View
Karna ships with a real-time 3D visualization of your knowledge graph (shown in the hero image above). Watch your codebase as a living, breathing graph -- with entity types color-coded, relationships traced, and agent activity highlighted live.
karna live .
# Open http://localhost:3849
CLI Reference
karna init [path] # Build the knowledge graph
karna serve [path] # Start MCP server (+ Live View)
karna live [path] # Start Live View only
karna status [path] # Show graph stats
karna query [path] "topic" # Search from terminal
Research Paper
Karna: Reducing LLM Coding Agent Token Consumption by 58% via Persistent Code Knowledge Graphs Shailesh Tripathi, 2026. Read on Zenodo
@article{tripathi2026karna,
title = {Karna: Reducing LLM Coding Agent Token Consumption
by 58\% via Persistent Code Knowledge Graphs},
author = {Tripathi, Shailesh},
journal = {Zenodo preprint, DOI: 10.5281/zenodo.19433427},
year = {2026}
}
Contributing
git clone https://github.com/shailesht003/karna-ai
cd karna
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest # 89 tests, all green
We welcome contributions. See CONTRIBUTING.md for guidelines.
License
Apache License 2.0. See LICENSE.
Built by Shailesh Tripathi · Production-grade cloud version with universal language support at karna.ai
Metadata
Release files for karna 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| karna-0.1.0.tar.gz | 54.8 kB | Without provenance | Details for karna-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| karna-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for karna-0.1.0-py3-none-any.whl |
Total release size: 111.7 kB
Release files / karna-0.1.0.tar.gz
| Download URL | karna-0.1.0.tar.gz |
|---|---|
| Size | 54.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8441f9031b3e79feaeb5f3ccc416a29f5535c4203f33300b4108d685cc3df4d
|
|
BLAKE2b-256 checksum How to use checksums |
7af1c582066a339150c7798440f03828b40c17aa5b24154e40cfc708ece2066f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / karna-0.1.0-py3-none-any.whl
| Download URL | karna-0.1.0-py3-none-any.whl |
|---|---|
| Size | 56.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fbdf429ec9baf8056e3d430f892574106277b7820a3abfecf6a5e455731e395c
|
|
BLAKE2b-256 checksum How to use checksums |
5fbc339bd3501bd31770a3bfa292e47302b2c5298b33fcdaa46c26454ee65f3c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for karna 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.