Local-First MCP Sidecar

34 MCP Tools

18 Languages

✦ v1.7.0

✦ ctxloom-bot NEW

The Universal Code Context Engine

Local-first MCP sidecar that gives AI coding assistants intelligent, structured code context — 24.6× token reduction, F1 = 0.42 against an external PR-diff oracle, 100% symbol & import coverage.

Start free — 14 days View Documentation

No credit card required · Pro from €9.90/mo

auth-controller.ts

150 lines→15 lines

Original

1import { UserService } from './services/user';

3export class AuthController {

4 private userService: UserService;

5 private tokenSecret: string;

6 private refreshInterval: number;

8 constructor(config: AuthConfig) {

9 this.userService = new UserService(config.db);

10 this.tokenSecret = config.tokenSecret;

11 this.refreshInterval = config.refreshInterval;

12 }

14 async login(credentials: LoginDTO): Promise<AuthResponse> {

15 const user = await this.userService.findByEmail(credentials.email);

16 if (!user) throw new NotFoundError('User not found');

17 const valid = await bcrypt.compare(credentials.password, user.passwordHash);

18 if (!valid) throw new UnauthorizedError('Invalid credentials');

19 const token = this.generateToken(user);

20 const refreshToken = this.generateRefreshToken(user);

21 return { token, refreshToken, user: user.toJSON() };

22 }

24 async register(dto: RegisterDTO): Promise<AuthResponse> {

25 const existing = await this.userService.findByEmail(dto.email);

26 if (existing) throw new ConflictError('Email already registered');

27 const hash = await bcrypt.hash(dto.password, 12);

28 const user = await this.userService.create({ ...dto, passwordHash: hash });

29 const token = this.generateToken(user);

30 return { token, user: user.toJSON() };

31 }

33 private generateToken(user: User): string {

34 return jwt.sign({ sub: user.id, email: user.email }, this.tokenSecret, { expiresIn: '1h' });

35 }

37 private generateRefreshToken(user: User): string {

38 return jwt.sign({ sub: user.id, type: 'refresh' }, this.tokenSecret, { expiresIn: '7d' });

39 }

40}

Skeletonized

1import { UserService } from './services/user';

3export class AuthController {

4 private userService: UserService;

5 private tokenSecret: string;

6 private refreshInterval: number;

7 constructor(config: AuthConfig);

8 async login(credentials: LoginDTO): Promise<AuthResponse>;

9 async register(dto: RegisterDTO): Promise<AuthResponse>;

10 private generateToken(user: User): string;

11 private generateRefreshToken(user: User): string;

12}

92% token reduction, measured on 6,154 filesctx_get_context_packet

The Context Bottleneck

AI coding assistants are only as good as the context they receive. Too little context causes hallucinations; too much wastes tokens and money.

The Problem

●

Too little context → Hallucinations

AI makes up APIs, invents non-existent functions, and suggests incorrect patterns when it lacks project context.

●

Too much context → Token waste

Dumping entire codebases into context windows costs $0.50+ per query and hits token limits on complex projects.

●

No structure → Irrelevant results

Grep-based tools find text matches but miss semantic relationships, call chains, and dependency context.

// AI without context:

const user = await db.findUser(); // ❌ doesn't exist

const result = userService.getProfile(); // ❌ wrong method

import { Auth } from './auth'; // ❌ wrong import

The Solution

●

Structured Dependency Graph

Build an in-memory graph of imports, calls, and type relationships. Navigate code by structure, not just text.

●

Semantic Vector Index

LanceDB-powered embeddings find files by meaning, not just name. "Where is authentication handled?" → instant results.

●

AST Skeletonization

tree-sitter strips function bodies, leaving only signatures and types. 200-line files → 15 lines of pure interface.

// AI with ctxloom:

const user = await userService.findByEmail(email); // ✓ correct

const profile = user.toProfile(); // ✓ real method

import { UserService } from '@/services'; // ✓ verified

92%

Token Reduction

<500ms

Retrieval Speed

Zero

API Keys

Features

Everything You Need for Intelligent Context

Twelve core capabilities that transform how AI assistants understand your codebase.

Hybrid Search

Vector embeddings (semantic) + dependency graph (structural) combined. Find files by meaning OR by relationship.

LanceDB-powered semantic search finds code by concept — "authentication logic" returns the right files. Graph-based search traverses imports and calls to find related code.

Code Skeletonization

Compress files to signature-only views. 200-line file → 15 lines. Class bodies, function implementations stripped.

Uses tree-sitter AST parsing to strip function bodies, keeping only signatures, types, imports, and class declarations. Preserves all the information an AI needs without the noise.

Call Graph Traversal

Bidirectional: find who calls a function (callers) or what it depends on (callees). Configurable depth for transitive analysis.

Navigate the dependency graph in both directions. Find all callers of a function to understand impact, or trace callees to understand behavior. Configurable depth from 1 to N hops.

Agent-First Harness

One ctxloom init writes the agent-rule files, hooks, and skills so AI agents reach for ctxloom MCP tools by default — no rule-memorization required.

ctxloom init writes HMAC-signed CTXLOOM-RULES blocks into CLAUDE.md / AGENTS.md / GEMINI.md, six pre-packaged Claude Code skills (/ctxloom-blast, /ctxloom-explore, /ctxloom-review-pr, /ctxloom-refactor-safely, /ctxloom-coverage-gap, /ctxloom-budget-stats), and SessionStart + PostToolUse hooks. Add --host=cursor / aider / copilot / windsurf to extend rules to those agents. HMAC drift detection rejects hand-edited blocks unless --force.

Self-Guiding API

Every response carries next_tool_suggestions with why-reasoning + token-cost estimates — agents follow the path instead of guessing.

Start every workflow with ctx_get_minimal_context — a ~150-token orientation anchor that returns graph readiness, recent changes, top hubs, and a task-aware suggested-first-tool routed by regex from your prompt ("review PR", "rename X", "blast radius"). Every budget-wrapped response includes meta.next_tool_suggestions (up to 3 follow-ups with token estimates). Telemetry-learned suggestions replace static rules once enough usage accumulates.

Response Budgets

Server-side max_response_tokens + skeleton fallback. 92% token reduction without losing structural signal.

Pass max_response_tokens to any of the 12 source-returning tools and over-budget responses auto-substitute a Skeletonizer signature view (or a per-tool lighter form). Pre-tuned defaults per tool; CTXLOOM_DISABLE_BUDGET=1 kill switch. A server-enforced ≤8-call task-tool budget kicks in when an agent exceeds the protocol target — args auto-throttle to skeleton/minimal mode, the agent can't opt out.

Slash Commands

Direct tool invocation with /ctx_search, /ctx_get_file, etc. Skip the AI middleman for instant, deterministic results.

Type /ctx_search auth code to search directly, or /ctx_get_context_packet src/auth.ts for instant context. Works in Claude Desktop, custom MCP clients, and CLI. No AI interpretation step — pure speed.

Live File Watching

Chokidar-based watcher with 200ms debounce. Index updates in <2 seconds when files change. No manual re-indexing.

Automatically detects file changes, creations, and deletions. Debounced at 200ms to batch rapid saves. Incremental re-indexing completes in under 2 seconds.

Rule Injection

Automatically loads .cursorrules, CLAUDE.md, CONTEXT.md, .ctxloomrc. Project conventions injected into AI context automatically.

Scans for project convention files and injects them into AI context on every request. Ensures AI assistants always follow your team's coding standards and architectural decisions.

Path Security

PathValidator prevents CWE-22 path traversal attacks. All file access validated against project root. Symlink escape prevention.

Every file path is resolved and validated against the project root before access. Prevents directory traversal attacks (../ escapes), symlink escapes, and unauthorized file reads.

Architecture Rules

Enforce import boundaries as CI lint. Define no-import rules in .ctxloom/rules.yml and catch architectural violations before they merge.

Rules are checked against the live dependency graph via picomatch globs. CLI exits 1 on error violations, 0 on clean. MCP tool ctx_rules_check brings the same engine to your AI assistant — config reloaded per call, no restart needed.

Multi-Project Dashboard

One web dashboard, every codebase you work on. Switch projects from the sidebar — graph, risk, communities, ownership all follow.

Register repos with `ctxloom register <path>` and they appear in the dashboard switcher. Hot-swap the active project without restarting the server. Selection persists across reloads. Inactive projects keep their snapshots; switching back is a fast snapshot read, not a full re-index.

Local web dashboard

Your codebase, visualized.

Run ctxloom dashboard and a local web UI opens at localhost:7842. Every tab below mirrors the real thing, populated with demo data from two registered projects.

localhost:7842

Overview

indexed 34s ago↻ Refresh

Files

2,345

Edges

2,402

Communities

1,311

Git history

enabled

Risk breakdown

critical2 files0%

high30 files1%

medium253 files11%

low2,060 files88%

Token consumption

With skeletonization

251.6k

Full files

6.1M

5.8M saved96% reduction

Top architectural hubs

db.ts↑250 ↓0
utils.ts↑189 ↓0
store.ts↑161 ↓2
api/client.ts↑142 ↓4

Click any tab in the sidebar to explore that view. Project switcher auto-cycles every 7s.

Live Graph

Your codebase, structured

Three lenses on your code — structural dependencies, git risk scores, and blast radius — all from a single index.

File

Class

Function

MCP Tool

Test

18 nodes · 23 edges visible

MCP Tools

34 tools. Five categories. One install.

The most complete code context engine for AI assistants — search, graph analysis, navigation, review, and automation in a single MCP server.

ctx_search

Hybrid semantic + graph search. Vector similarity + import graph expansion combined for intelligent file discovery.

Parameters

Name	Type	Req.	Description
query	string	yes	Natural language or code symbol query
limit	number	opt	Max results (default: 10)

Input

Output

Direct Slash Commands

Skip the AI middleman. Invoke any tool directly — instant, deterministic, zero latency.

/ctx_search auth logic/ctx_blast_radius src/auth/controller.ts/ctx_execution_flow handlePayment/ctx_detect_changes/ctx_get_workflow review

Git Intelligence

The risk your static graph can't see

Two new tools fuse git history onto the structural graph — surfacing coupling, churn, and ownership signals invisible to AST analysis.

GitHub Action · v1

Risk-scored reviews on every PR

ctxloom-bot posts automated structural analysis the moment a PR opens — blast radius, risk scores, and reviewer suggestions. No hosted service, no LLM calls, no API keys.

$ ctxloom install-pr-bot

One command writes .github/workflows/ctxloom-review.yml — runs a pre-built Docker image from GHCR on every PR.

ctxloom-botjust nowBot

## ctxloom analysis · risk: high (0.81)

📊 Blast radius: 14 files · 3 communities

🔥 Top risk: src/auth/controller.ts (churn: high, bus factor: 1)

👥 Suggested reviewers: @alice, @bob (ownership match)

Updates on new commits · idempotent · runs entirely in your Actions runner

Posts on every PR — idempotent, updates on new commits
Inline annotations at the highest-risk lines
Suggests reviewers from git ownership data
Docs-only PRs scored low — never noisy on README changes
Optional Check Run — gate merges on risk threshold

Git History · v0.7

Historical coupling the static graph misses

Mines your git log to surface files that change together even when they have no import relationship — the hidden couplings that break refactors.

ctx_git_coupling

Co-change analysis — files that historically move together (Jaccard + recency decay)

node: "src/auth/controller.ts"

schema/migrations/001_users.sql0.91████████████

src/auth/middleware.ts0.84███████████

tests/auth.test.ts0.76██████████

config/jwt.config.ts0.62████████

ctx_risk_overlay

Composite risk score: churn 35% + bug density 30% + bus factor 20% + coupling 15%

src/auth/controller.tshigh0.81

src/api/payments.tshigh0.74

src/db/migrations.tsmedium0.55

src/utils/logger.tslow0.18

v1.7.0 · External-oracle benchmark

Numbers measured against real merged PRs.

Most code-context tools grade their own homework — they measure prediction quality against their own graph traversal. That's tautological. Our bench uses an external oracle: the human-authored merged-PR diff from GitHub.

Avg F1

0.42

Honest. We report it instead of cherry-picking a higher derivative.

Graph reachability

0.94

94% of source-file ground truth reachable from the entry point via BFS.

Symbol coverage

1.00

Every AST-declared function/class/method/interface in the symbol index.

Import coverage

1.00

Every relative import resolves to a graph edge.

Token reduction

24.6×

Naive baseline (full files + 1-hop imports) vs skeleton view.

Per-repo breakdown

15 merged PRs across 5 popular OSS frameworks · ground truth from GitHub

Repository	PRs	F1	Source recall	Graph reach	Symbol cov	Import cov	Reduction
`expressjs/express`	3	0.26	0.67	1.00	1.00	1.00	20.3×
`tiangolo/fastapi`	3	0.46	0.59	0.89	1.00	1.00	32.3×
`pallets/flask`	3	0.39	0.74	0.98	1.00	1.00	17.5×
`gin-gonic/gin`	3	0.47	0.49	0.95	1.00	n/a	28.3×
`encode/httpx`	3	0.50	0.54	0.86	1.00	1.00	24.5×
Aggregate · 5 repos · 15 PRs	15	0.42	0.61	0.94	1.00	1.00	24.6×

Methodology

For each PR: pick the most-modified file as the entry point, ask ctxloom what's affected, compare to the human-authored file list in the merged diff. F1/precision/recall computed against that external ground truth.Symbol & import coverage are direct AST-vs-graph comparisons — no oracle needed. Token reduction uses the same Skeletonizer + token estimator the production tools use.

Reproduce every number

git clone github.com/kodiii/ctxloom && npm run bench:full

Output lands in evaluate/reports/summary.md. Same corpus, same methodology, same numbers.Full methodology →

Benchmarks

92% reduction. Measured, not estimated.

14.1M tokens \u2192 1.1M across 6,154 files in 5 real frameworks (small libs to monorepos). Reproduce it yourself: npm run bench:repos

weighted aggregate

92%token reduction

Across 6,154 files in 5 real frameworks

Raw tokens100%

Skeleton tokens8%

Token reduction \u2014 full source, every file

Walks the full source tree of each repo (skips tests, .d.ts, build output, minified vendor bundles)

Repository	Language	Raw tokens	Skeleton tokens	Reduction
`vercel/next.js`	TypeScript	~12.2M	~584k	95%
`honojs/hono`	TypeScript	~185k	~30k	84%
`vitejs/vite`	TypeScript	~459k	~105k	77%
`withastro/astro`	TypeScript	~805k	~191k	76%
`nestjs/nest`	TypeScript	~409k	~177k	57%
Weighted average · 6,154 files		~14.1M	~1.1M	92%

How ctxloom compares

Feature	ctxloom	Others
Zero Python	✅ Pure JS/TS	❌ Python required
Local-first (no cloud)	✅	varies
Blast radius analysis	✅ `ctx_blast_radius`	❌
Community / cluster detection	✅ Louvain (pure JS)	❌
Execution flow tracing	✅ `ctx_execution_flow`	❌
Refactor rename preview	✅ `ctx_refactor_preview`	❌
Wiki generation (no LLM)	✅ `ctx_wiki_generate`	❌
PR-native GitHub App	✅ `ctxloom-bot`	❌
18 languages (import + symbol)	✅	varies
17 MCP host adapters + auto-detect	✅ ctxloom setup	varies
External-oracle benchmark (F1, recall)	✅ vs PR diff from GitHub	❌ self-referential
Monorepo support (50k+ files)	✅ streaming + batched upserts	varies
92% token reduction (6,154 files)	✅ measured	❌ estimated

Run it yourself:npx tsx benchmarks/benchmark.ts

Architecture

Built for Speed & Intelligence

Five-layer architecture designed for sub-second context retrieval with live indexing.

Data Flow

Context Engine

The core intelligence layer combining three specialized engines for comprehensive code understanding.

Components

In-Memory Graph

Dependency graph with bidirectional traversal. Tracks imports, calls, and type relationships in real-time.

VectorDB (LanceDB)

Semantic search via vector embeddings. Finds code by meaning, not just text matching.

Skeletonizer (tree-sitter)

AST-based code compression. Strips implementations, preserves signatures and types.

Receives data from: MCP Interface Layer

Sends data to: Auto Setup & Integration

Getting Started

Up and Running in 30 Seconds

Install, index, and connect. No API keys, no cloud accounts, no configuration required.

Install ctxloom

One-time global install. Node.js 20+ required.

bash

npm install -g ctxloom-pro

Activate your license

Start a free 14-day trial — no credit card required. You'll receive a license key by email; paste it into the command below.

Get your free trial key →

bash

ctxloom activate CTXL_PRO_-<your-key>

Connect your AI tools

Run the setup wizard once — it detects every MCP-compatible tool on your machine and writes the config automatically.

bash

ctxloom setup

Claude Code

Cursor

VS Code

Windsurf

Augment Code

Kilo Code

Continue.dev

Aider

+ 5 more: Codex CLI, Kimi, Qwen Code, JetBrains AI, Claude Desktop

Pin ctxloom to this project

Run once per project. Writes a .mcp.json that ties ctxloom to this directory and appends .ctxloom/ to .gitignore. Without this, MCP-aware editors can keep the server pinned to whichever project you opened first — switching workspaces won't move it.

bash

cd /path/to/your/project
ctxloom init

Index your project

Builds the dependency graph, indexes symbols, and generates vector embeddings. Takes 5–15 seconds on a typical mid-size repo. Re-runs automatically as you edit files.

bash

ctxloom index

✓

Open your AI tool — you're done

ctxloom starts automatically when your AI tool connects. No terminal to keep open. All 34 tools are instantly available.

✦

No API keys. Everything runs locally on your machine.

No cloud. Code never leaves your environment.

Auto-updates. The file watcher keeps the graph in sync as you code.

MCP Client Configuration

Recommended: Run ctxloom setup to auto-configure all detected clients. The manual configs below are for reference or if you prefer to configure by hand.

Claude Code

json

{
  "mcpServers": {
    "ctxloom": {
      "command": "ctxloom",
      "args": []
    }
  }
}

Add to ~/.claude.json

Cursor

json

{
  "mcpServers": {
    "ctxloom": {
      "command": "ctxloom",
      "args": []
    }
  }
}

Add to ~/.cursor/mcp.json

The global entry above lets your AI tool find the ctxloom binary; the per-project pinning happens via ctxloom init, which writes a .mcp.json in your project root with an explicit CTXLOOM_ROOT. MCP clients like Claude Code merge per-project config over global, so init is what actually keeps the server pointed at the codebase you're working in — even when you switch workspaces mid-session.

Environment Variables

Variable	Description	Default
CTXLOOM_ROOT	Project root directory to index (auto-detected if not set)	process.cwd()
LOG_LEVEL	Logging verbosity: debug, info, warn, error	info

Need more? The full reference covers all 34 tools, advanced configs, and integration guides.

Read the Full Docs