Skip to main content

Karna Live View — 3D knowledge graph visualization

Karna

Your codebase, as a knowledge graph. For AI agents that don't waste tokens.

License  Python 3.10+  DOI  MCP Compatible


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

Turn 1: list_directory → 2,100 tokens
Turn 2: grep_search → 3,400 tokens
Turn 3: read_file → 4,200 tokens
Turn 4: read_file → 3,800 tokens
Turn 5: read_file → 2,900 tokens
Turn 6: read_file → 1,800 tokens
Turn 7: grep_search → 1,200 tokens
Turn 8: final answer → 1,400 tokens
────────────────────────────
Total input: ~20,800 tokens

With Karna

Turn 1: karna_task_context → 8,700 tokens
Turn 2: final answer → done
────────────────────────────
Total input: ~8,700 tokens



                    58% saved.




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)

Source distribution for karna 0.1.0
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)

Table of built distributions (wheels) for karna 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page