codensa

GraphRAG-powered project knowledge for AI coding assistants — zero manual file reading, maximum token savings.

Drop this into any project and your AI coding tool (Claude Code, Cursor, Codex) automatically understands the entire codebase on first use — without you asking it to read files one by one.

---

How it works

Your project/
  ├── src/...
  ├── .codensa/     ← auto-created on first run
  │   ├── graph.json        ← dependency + symbol graph (NetworkX)
  │   ├── vectors.pkl       ← TF-IDF semantic search index
  │   ├── summary.md        ← compressed project map
  │   └── meta.json         ← file hashes, stats
  └── .claude/mcp.json      ← auto-written by integrate.py

On first prompt, the MCP server:

1. Parses all source files (Python AST, regex for TS/JS/Go)
2. Builds a knowledge graph of files → imports → symbols
3. Indexes all code into a TF-IDF semantic search store
4. Generates a project summary (tech stack, file map, architecture)

Every subsequent prompt the AI can call project_summary (one tool call) instead of reading 30+ files.

---

Token savings

Without this	With this
AI reads 10-50 files to understand project	1 project_summary call gives the full map
grep-style file scanning	semantic_search finds relevant chunks instantly
AI asks you what files are relevant	find_symbol + file_graph give exact answers
Context window fills with boilerplate	Only relevant code snippets loaded

Estimated savings: 60–80% fewer tokens per session on a medium-sized project.

---

Quick start

1. Install

# Clone into your tools dir or anywhere convenient
git clone https://github.com/yourname/codensa
cd codensa
pip install -e .

2. Integrate with your AI tool (one command)

# Run from inside your project
cd /path/to/your/project
python /path/to/codensa/integrate.py --index

# Or specify the tool
python integrate.py --tool claude   # Claude Code only
python integrate.py --tool cursor   # Cursor only
python integrate.py --tool all      # All (default)

This writes .claude/mcp.json and/or .cursor/mcp.json and runs the initial index.

3. Start coding

Restart your AI coding tool. On the first prompt, the server auto-indexes the project. The AI will call project_summary automatically (guided by CLAUDE.md) and know the full codebase structure instantly.

---

MCP Tools available to the AI

Tool	Purpose	When to use
project_summary	Full project map in markdown	Always first
semantic_search	Find relevant code by description	Before opening files
find_symbol	Locate class/function definition	Instead of grep
file_graph	Imports/callers for a file	Understanding blast radius
list_files	Browse file tree with stats	Navigation
get_file_content	Read exact file content	Only when needed
hot_files	Most-imported / core modules	Architecture overview
index_status	When was it last indexed	Freshness check
reindex	Force full re-scan	After major refactor

---

CLI usage

# Index a project
codensa index /path/to/project

# Print the project summary
codensa summary /path/to/project

# Semantic search
codensa search "authentication middleware" /path/to/project

# Check index freshness
codensa status /path/to/project

# Start as MCP server (stdio — for Claude Code / Cursor)
codensa serve /path/to/project

# Start as HTTP MCP server (for testing / remote)
codensa serve /path/to/project --http --port 8765

# Force reindex on start
codensa serve /path/to/project --reindex

---

Manual MCP config (Claude Code)

Add to .claude/mcp.json in your project:

{
  "mcpServers": {
    "codensa": {
      "command": "codensa",
      "args": ["serve", "/absolute/path/to/your/project"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Or with python directly (if not installed as package):

{
  "mcpServers": {
    "codensa": {
      "command": "python",
      "args": ["/path/to/codensa/server.py", "/path/to/your/project"]
    }
  }
}

Manual MCP config (Cursor)

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "codensa": {
      "command": "codensa",
      "args": ["serve", "${workspaceFolder}"]
    }
  }
}

---

Supported languages

Language	Parser	What's extracted
Python	AST (built-in)	Classes, functions, decorators, docstrings, imports, calls
TypeScript/TSX	Regex	Functions, classes, interfaces, imports
JavaScript/JSX	Regex	Functions, classes, requires
Go	Regex	Functions, structs, imports
Markdown	Raw	Full text for semantic search
YAML/TOML/JSON	Raw	Config keys for search

---

Configuration

Set via environment variable or .codensa/.config.json:

Variable	Default	Description
PROJECT_ROOT	cwd	Project directory to index
MAX_FILE_SIZE_KB	200	Skip files larger than this
TOKEN_BUDGET	8000	Max tokens per file content response

---

How the graph works

Each indexed project gets a directed graph where:

• File nodes contain: size, extension, symbols, imports
• Symbol nodes (file.py::ClassName) track definitions
• Edges: defines (file → symbol), imports (file → module)

hot_files ranks by in-degree (most imported = most central to project).
file_graph shows the local neighbourhood around any file.

---

.gitignore recommendation

.codensa/

The index is auto-rebuilt when files change — no need to commit it.

---

Requirements

• Python 3.11+
• fastmcp, networkx, tiktoken, scikit-learn
• No GPU, no model downloads, no API keys needed for indexing

---

License

MIT © 2026 Afroz Khan