Content
# codensa
[](LICENSE)
> **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
```bash
# 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)
```bash
# 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
```bash
# 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:
```json
{
"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):
```json
{
"mcpServers": {
"codensa": {
"command": "python",
"args": ["/path/to/codensa/server.py", "/path/to/your/project"]
}
}
}
```
## Manual MCP config (Cursor)
Add to `.cursor/mcp.json`:
```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
```gitignore
.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](LICENSE) © 2026 Afroz Khan
