Citadel

curl -fsSL https://raw.githubusercontent.com/antonygiomarxdev/citadel/main/install.sh | sh

irm https://raw.githubusercontent.com/antonygiomarxdev/citadel/main/install.ps1 | iex

cd your-project
citadel init -i

When Claude Code explores a codebase, it spawns Explore agents that scan files with grep, glob, and Read — consuming tokens on every tool call.

Citadel gives those agents a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.

Tested across 7 real-world open-source codebases spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question with and without Citadel. Each cell is the savings at the median of 4 runs per arm.

Average: 35% cheaper · 59% fewer tokens · 49% faster · 70% fewer tool calls

The gains scale with codebase size: on large repos the agent answers from the index in a handful of calls with zero file reads, while the no-Citadel agent fans out across grep/find/Read (and the sub-agents it spawns). On a small repo like Gin (~150 files) native search is already cheap, so the margin narrows.

Measured on a Ryzen 7 5800X, NVMe SSD, Node 24.

Why identical? Both still use the same WASM tree-sitter extraction pipeline. The Rust migration replaced storage + graph traversal, but extraction — the bottleneck — remains in TypeScript/WASM. The 7% overhead on rustc is the NAPI boundary cost.

The native Rust extractor is ~5× faster and extracts 63% more detail (more node kinds, better qualified names). Rayon parallelizes across all CPU cores — near-linear speedup.

Projection: once native extraction is stable and wired into the index pipeline, VSCode index drops from 213s → ~35s, rustc from 432s → ~70s.

• Stabilize native extraction — fix segfaults on edge-case files
• Add Rust extractors for Go, Java, C#, PHP, Ruby (TS/Python done)
• Wire native extraction into the index pipeline → 5-7× faster indexing
• Rango integration — Storage trait allows swapping SQLite for a distributed backend

→ View full plan on GitHub

Citadel detects web-framework routing files and emits route nodes linked by references edges to their handler classes or functions. Querying callers of a view/controller now surfaces the URL pattern that binds it.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/antonygiomarxdev/citadel/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/antonygiomarxdev/citadel/main/install.ps1 | iex

The installer will:

• Ask which agent(s) to configure — auto-detects installed ones from: Claude Code, Cursor, Codex CLI, opencode
• Prompt to install citadel on your PATH (so agents can launch the MCP server)
• Ask whether configs apply to all your projects or just this one
• Write each chosen agent's MCP server config + an instructions file (e.g. CLAUDE.md, .cursor/rules/citadel.mdc, ~/.codex/AGENTS.md)
• Set up auto-allow permissions when Claude Code is one of the targets
• Initialize your current project (local installs only)

Non-interactive (scripting / CI):

citadel install --yes                              # auto-detect agents, install global
citadel install --target=cursor,claude --yes       # explicit target list
citadel install --target=auto --location=local     # detected agents, project-local
citadel install --print-config codex               # print snippet, no file writes

Restart your agent (Claude Code / Cursor / Codex CLI / opencode) for the MCP server to load.

cd your-project
citadel init -i

Builds the per-project knowledge graph index. Also wires up any project-local agent surfaces (e.g. Cursor's .cursor/rules/citadel.mdc) so a single global citadel install works in every project you open — no need to re-run the installer per project.

That's it — your agent will use Citadel tools automatically when a .citadel/ directory exists.

npm install -g citadel

{
  "mcpServers": {
    "citadel": {
      "type": "stdio",
      "command": "citadel",
      "args": ["serve", "--mcp"]
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__citadel__citadel_search",
      "mcp__citadel__citadel_context",
      "mcp__citadel__citadel_callers",
      "mcp__citadel__citadel_callees",
      "mcp__citadel__citadel_impact",
      "mcp__citadel__citadel_node",
      "mcp__citadel__citadel_status",
      "mcp__citadel__citadel_files"
    ]
  }
}

## Citadel

Citadel builds a semantic knowledge graph of codebases for faster, smarter code exploration.

### If `.citadel/` exists in the project

**NEVER call `citadel_explore` or `citadel_context` directly in the main session.** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?").

**When spawning Explore agents**, include this instruction in the prompt:

> This project has Citadel initialized (.citadel/ exists). Use `citadel_explore` as your PRIMARY tool — it returns full source code sections from all relevant files in one call.
>
> **Rules:**
> 1. Follow the explore call budget in the `citadel_explore` tool description — it scales automatically based on project size.
> 2. Do NOT re-read files that citadel_explore already returned source code for. The source sections are complete and authoritative.
> 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if citadel returned no results.

**The main session may only use these lightweight tools directly** (for targeted lookups before making edits, not for exploration):

| Tool | Use For |
|------|---------|
| `citadel_search` | Find symbols by name |
| `citadel_callers` / `citadel_callees` | Trace call flow |
| `citadel_impact` | Check what's affected before editing |
| `citadel_node` | Get a single symbol's details |

### If `.citadel/` does NOT exist

At the start of a session, ask the user if they'd like to initialize Citadel:

"I notice this project doesn't have Citadel initialized. Would you like me to run `citadel init -i` to build a code knowledge graph?"

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code                               │
│                                                                  │
│  "Implement user authentication"                                 │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐      ┌─────────────────┐                   │
│  │  Explore Agent  │ ──── │  Explore Agent  │                   │
│  └────────┬────────┘      └────────┬────────┘                   │
│           │                        │                             │
└───────────┼────────────────────────┼─────────────────────────────┘
            │                        │
            ▼                        ▼
┌───────────────────────────────────────────────────────────────────┐
│                     Citadel MCP Server                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
│  │   Search    │  │   Callers   │  │   Context   │               │
│  │  "auth"     │  │  "login()"  │  │  for task   │               │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │
│         │                │                │                       │
│         └────────────────┼────────────────┘                       │
│                          ▼                                        │
│              ┌──────────────────────────────────┐                 │
│              │        Rust Native Core          │                 │
│              │  ┌──────────┐  ┌──────────────┐  │                 │
│              │  │  Graph   │  │    Search    │  │                 │
│              │  │ Traversal│  │  (FTS5+tantivy)│  │                 │
│              │  └────┬─────┘  └──────┬───────┘  │                 │
│              │       │               │          │                 │
│              │  ┌────▼───────────────▼───────┐  │                 │
│              │  │   rusqlite / SQLite DB     │  │                 │
│              │  │   • 387 symbols            │  │                 │
│              │  │   • 1,204 edges            │  │                 │
│              │  │   • Instant lookups        │  │                 │
│              │  └────────────────────────────┘  │                 │
│              └──────────────────────────────────┘                 │
└───────────────────────────────────────────────────────────────────┘

1. Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements). Native Rust tree-sitter replaces the WASM worker pool — no heap recycling, no serialization overhead.

2. Storage — Everything goes into a local SQLite database (.citadel/citadel.db) with FTS5 full-text search. Powered by rusqlite (Rust) — no WASM fallback, no adapter layer.

3. Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. Runs in native Rust with concurrent name matching.

4. Graph Traversal — BFS/DFS impact analysis, callers/callees, and path finding execute in parallel Rust via rayon — sub-millisecond even on graphs with 100k+ nodes.

5. Auto-Sync — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed.

citadel                         # Run interactive installer
citadel install                 # Run installer (explicit)
citadel init [path]             # Initialize in a project (--index to also index)
citadel uninit [path]           # Remove Citadel from a project (--force to skip prompt)
citadel index [path]            # Full index (--force to re-index, --quiet for less output)
citadel sync [path]             # Incremental update
citadel status [path]           # Show statistics
citadel query <search>          # Search symbols (--kind, --limit, --json)
citadel files [path]            # Show file structure (--format, --filter, --max-depth, --json)
citadel context <task>          # Build context for AI (--format, --max-nodes)
citadel affected [files...]     # Find test files affected by changes (see below)
citadel serve --mcp             # Start MCP server

Traces import dependencies transitively to find which test files are affected by changed source files.

citadel affected src/utils.ts src/api.ts         # Pass files as arguments
git diff --name-only | citadel affected --stdin   # Pipe from git diff
citadel affected src/auth.ts --filter "e2e/*"     # Custom test file pattern

CI/hook example:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | citadel affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

When running as an MCP server, Citadel exposes these tools to Claude Code:

import Citadel from 'citadel';

const cg = await Citadel.init('/path/to/project');
// Or: const cg = await Citadel.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

The .citadel/config.json file controls indexing:

{
  "version": 1,
  "languages": ["typescript", "javascript"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
  "frameworks": [],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true
}

"Citadel not initialized" — Run citadel init in your project directory first.

Indexing is slow — Check that node_modules and other large directories are excluded. Use --quiet to reduce output overhead.

Indexing is slow / MCP database is locked / WASM fallback active — citadel ships with a WASM SQLite fallback for environments where better-sqlite3 (a native module, declared as optionalDependencies) can't install. The fallback is 5-10x slower than the native backend and uses a journal mode that lets writers block readers, so MCP queries can also hit database is locked while indexing runs.

⚡ Upcoming: The Rust core migration eliminates both the WASM fallback and better-sqlite3 entirely — rusqlite with bundled SQLite is the only backend. See the Rust Roadmap.

Run citadel status and look at the Backend: line:

• Backend: native — you're on the fast path, nothing to do.

• Backend: wasm — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix:

  # macOS
  xcode-select --install                                  # installs the C compiler
  
  # Linux (Debian / Ubuntu)
  sudo apt install build-essential python3 make
  
  # Linux (RHEL / Fedora)
  sudo yum groupinstall "Development Tools"
  
  # Then rebuild on any platform:
  npm rebuild better-sqlite3
  
  # Or force-include as a hard dep:
  npm install better-sqlite3 --save

  After the fix, citadel status should show Backend: native.

MCP server not connecting — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that citadel serve --mcp works from the command line.

Missing symbols — The MCP server auto-syncs on save (wait a couple seconds). Run citadel sync manually if needed. Check that the file's language is supported and isn't excluded by config patterns.

MIT