Content
# Cortex Index — Local-First AI Code Intelligence Engine
> A persistent semantic operating system for your code. Cortex Index converts raw source code into high-density, token-optimized Knowledge Graphs (`cortex_build_context`), empowering AI agents (Claude, Cursor, Antigravity) with precise cross-file AST intelligence.
---
## ⚡ Key Features
- 🧠 **Context Builder (`cortex_build_context`)**: Generates compact, token-optimized context bundles (target symbol + callers + callees + risk score + architectural advice) instead of dumping thousands of raw lines.
- ⚡ **Local-First & High Performance**: Pure-Go SQLite WAL database (`modernc.org/sqlite`). Cold index <150ms, query latency <0.3ms. Zero external dependencies.
- 🔌 **22 Native MCP Tools**: Full compliance with Model Context Protocol (MCP v1.0) over **Stdio** and **HTTP JSON-RPC 2.0**.
- 🔍 **Multi-Language AST Support**: Go, TypeScript / JavaScript, Python, and Rust AST parsers.
- 🔄 **Incremental & Git-Aware**: Real-time `fsnotify` file watcher (300ms debounced) and Git branch comparator (`cortex_compare_branches`).
- 📊 **Visual Web UI Dashboard**: Modern dark-mode dashboard powered by **Bun**, Vite, React 19, and Tailwind CSS.
- 🚀 **CLI Daemon Control**: Background daemon management (`cortex start -d`, `cortex stop`) with PID tracking.
---
## 🏗️ Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ AI Agents (Claude / Cursor / IDE) │
└──────────────────────────────┬──────────────────────────────┘
│ JSON-RPC 2.0 (Stdio / HTTP)
┌──────────────────────────────▼──────────────────────────────┐
│ Cortex Index MCP & API Server │
├─────────────────────────────────────────────────────────────┤
│ • Context Builder Engine • Graph Engine (BFS/DFS) │
│ • Query Planner & LRU Cache • AST Resolver v2 │
├─────────────────────────────────────────────────────────────┤
│ Pure-Go SQLite WAL Repository (index.db) │
└──────────────────────────────▲──────────────────────────────┘
│ Real-Time Indexing
┌──────────────────────────────┴──────────────────────────────┐
│ Incremental Indexer & File Watcher │
│ Go AST │ TypeScript AST │ Python AST │ Rust AST │
└─────────────────────────────────────────────────────────────┘
```
---
## 🚀 Getting Started
### Prerequisites
- **Go 1.22+**
- **Bun 1.0+** (for UI dashboard)
### 1. Build & Install Globally
Clone the repository and run:
```bash
# Build Go binary (bin/cortex) and UI bundle
make build
# Install cortex binary globally to /usr/local/bin (accessible anywhere)
make install
```
---
## 🛠️ How to Run
### Option A: Run Both Backend & UI in Development Mode
Starts the Go API Backend on `http://localhost:8080` and the Bun React UI on `http://localhost:3000`:
```bash
make dev
```
### Option B: Run Background Server Daemon (PID Mode)
Run the server in the background as a daemon:
```bash
# Start server daemon in background (outputs PID)
cortex start -d
# Output: ✓ Cortex Index daemon started in background [PID: 14101]
# Check daemon running status & metrics
cortex status
# Stop background server daemon PID
cortex stop
# Output: ✓ Cortex Index daemon stopped [PID: 14101]
```
### Option C: Run Server in Foreground
```bash
cortex serve
```
---
## 🪝 Automatic Git Hooks & Real-Time File Watcher
Keep your knowledge graph automatically in sync as you write code, switch branches, or commit:
```bash
# Install Git hooks (post-commit, post-checkout, post-merge)
cortex hooks install
# Output: ✓ Installed Cortex Index Git hooks (post-commit, post-checkout, post-merge)
# Start real-time file change watcher (300ms debounced)
cortex watch
# Remove Git hooks when needed
cortex hooks remove
```
---
## 🔌 How to Connect to MCP (Model Context Protocol)
Cortex Index exposes **22 native MCP tools** for AI assistants (Claude Desktop, Cursor IDE, Antigravity, Windsurf).
### 1. Connecting via Kilo AI (`~/.config/kilo/kilo.json`)
Add `cortex-index` to `~/.config/kilo/kilo.json`:
```json
{
"mcp": {
"cortex-index": {
"type": "local",
"command": [
"cortex",
"mcp",
"stdio"
]
}
}
}
```
### 2. Connecting via Stdio (Claude Desktop / Antigravity / Cursor)
Add Cortex Index to your MCP client configuration (e.g. `claude_desktop_config.json`):
```json
{
"mcpServers": {
"cortex-index": {
"command": "cortex",
"args": ["mcp", "stdio"]
}
}
}
```
### 3. Connecting via HTTP Transport
If running `cortex serve` or `cortex start -d` on port `8080`:
```json
{
"mcpServers": {
"cortex-http": {
"url": "http://localhost:8080/mcp"
}
}
}
```
---
## 🛠️ 22 Native MCP Tools Reference
| Category | MCP Tool Name | Description |
| :--- | :--- | :--- |
| **High-Level Intelligence** | `cortex_build_context` | Generates token-optimized AI context bundle for target symbol |
| | `cortex_find_entry_points` | Locates main entry points, API routes, and handlers |
| | `cortex_find_dead_code` | Identifies unreferenced symbols with zero callers |
| | `cortex_get_diagnostics` | Deep system health, parse errors, and unresolved symbols |
| | `cortex_compare_branches` | Architectural diff comparator against Git target branch |
| **Code Intelligence** | `cortex_find_symbol` | Search symbol by name across workspace |
| | `cortex_get_definition` | Retrieve symbol definition and file line location |
| | `cortex_find_references` | Find all references to a symbol across files |
| | `cortex_find_callers` | Find all caller functions invoking target symbol |
| | `cortex_find_callees` | Find all functions invoked by target symbol |
| **Structure Navigation** | `cortex_get_file` | Retrieve file metadata and contained symbols |
| | `cortex_get_module` | Retrieve module files and directory packages |
| | `cortex_get_package` | Retrieve package details and contained files |
| | `cortex_list_symbols` | List all symbols in a specific file |
| | `cortex_explore_directory` | Explore directory structure and tracked files |
| **Architecture** | `cortex_get_architecture` | High-level module architecture graph |
| | `cortex_get_dependency_graph` | Dependency graph (`IMPORTS` & `DEPENDS_ON`) |
| | `cortex_get_call_graph` | Hierarchical call graph tree for symbol |
| | `cortex_get_type_graph` | Type hierarchy graph (structs, interfaces, classes) |
| **Search** | `cortex_search_symbol` | Search symbol by query string |
| | `cortex_search_text` | Search symbol doc comments or function text |
| | `cortex_search_path` | Search files by relative file path |
| **Project Intelligence** | `cortex_get_project_summary` | Workspace statistics summary |
| | `cortex_get_stats` | Total files, symbols, nodes, edges, and health |
| | `cortex_get_health` | Health status check |
| | `cortex_get_recent_changes` | Recent Git branch changes and dirty files |
---
## 🧪 Testing & Verification
```bash
# Run Go unit test suite and UI typecheck
make test
```
---
## 📄 License
MIT License © 2026 Cortex Index Team.
