ctxloom Documentation

Complete reference for all CLI commands, MCP tools, and configuration options.

Getting Started

Quick Start

Up and running in under a minute. No API keys, no cloud, no Python.

Install

bash

npm install -g ctxloom-pro

Configure AI tools

One-time. Detects all MCP clients automatically.

bash

ctxloom setup

Index project

bash

cd /path/to/your/project
ctxloom index

Prefer manual configuration? Add this to your MCP client config:

mcp-config.json

{
  "mcpServers": {
    "ctxloom": {
      "command": "npx",
      "args": ["-y", "ctxloom"],
      "env": { "CTXLOOM_ROOT": "/path/to/project" }
    }
  }
}

Reference

CLI Commands

Command	Description
`ctxloom`	Start MCP server (Stdio transport)
`ctxloom index`	Index current directory + build dependency graph
`ctxloom dashboard`	Open the web dashboard at http://localhost:7842
`ctxloom dashboard --port=N`	Start dashboard on a custom port
`ctxloom dashboard --open`	Launch and open browser automatically
`ctxloom setup`	Detect and configure MCP-compatible AI tools (interactive)
`ctxloom register <path>`	Register a repo for cross-repo search
`ctxloom repos`	List all registered repos
`ctxloom grammars`	Show grammar cache status
`ctxloom grammars --download`	Pre-download all language grammars
`ctxloom rules check`	Check .ctxloom/rules.yml against the dependency graph
`ctxloom rules check --json`	JSON output (schemaVersion: 1) for CI parsers
`ctxloom rules check --use-snapshot`	Skip re-indexing, use existing graph snapshot
`ctxloom rules check --limit=N`	Limit text output to N violations (default: 50)
`ctxloom --help`	Show help

Reference

MCP Tools32

◆detail_level="minimal" — 7 tools support this parameter for 40–60% fewer tokens in counts-only mode: ctx_blast_radius, ctx_hub_nodes, ctx_bridge_nodes, ctx_architecture_overview, ctx_knowledge_gaps, ctx_surprising_connections, ctx_detect_changes.

Search & Context6

ctx_search

Hybrid semantic + graph search. Use it when: finding files by concept or relationship.

ctx_get_file

Safe file read, 5 MB limit, path traversal protected. Use it when: reading a specific file safely.

ctx_get_context_packet

Primary file + dependency skeletons + reverse importers in one call. Use it when: giving AI full context for a file.

ctx_similar_files

Find semantically similar files via vector embeddings. Use it when: finding related implementations.

ctx_cross_repo_search

Federated search across all registered repos. Use it when: working across multiple repos.

ctx_full_text_search

Hybrid keyword + vector with regex. Use it when: finding exact strings or patterns.

Graph Intelligence8

ctx_blast_radius

"What breaks if I change this?" import + call graph traversal. Supports detail_level="minimal".

ctx_hub_nodes

Top-N files by import degree (chokepoints). Supports detail_level="minimal".

ctx_bridge_nodes

Top-N files by betweenness centrality (connectors). Supports detail_level="minimal".

ctx_community_list

Louvain clustering — groups files into architectural modules.

ctx_architecture_overview

High-level summary: communities, hubs, coupling. Supports detail_level="minimal".

ctx_knowledge_gaps

Isolated files, untested hubs, dead code candidates. Supports detail_level="minimal".

ctx_surprising_connections

Circular deps, cross-community imports, prod→test violations. Supports detail_level="minimal".

ctx_find_large_functions

Functions/classes exceeding a line threshold, sorted by size.

Code Navigation5

ctx_get_call_graph

Bidirectional call graph with configurable depth.

ctx_get_definition

Symbol definition lookup via AST index.

ctx_execution_flow

DFS call graph traversal from entry point with cycle detection.

ctx_refactor_preview

Read-only symbol rename diff preview across entire codebase.

ctx_apply_refactor

Write symbol renames atomically (supports dry_run).

Review & Export9

ctx_git_diff_review

All-in-one review packet: git diffs + skeletons + blast radius.

ctx_wiki_generate

Generate .ctxloom/wiki/ — one Markdown page per community. No LLM needed.

ctx_graph_export

Export to GraphML, DOT, Obsidian, SVG, or interactive D3.js HTML.

ctx_suggested_questions

Graph-driven review questions without LLM.

ctx_detect_changes

Risk-scored change analysis (critical/high/medium/low). Supports detail_level="minimal".

ctx_graph_snapshot

Save named checkpoint of the dependency graph.

ctx_graph_diff

Diff two named snapshots — added/removed nodes and edges.

ctx_git_coupling

Co-change analysis from git history (Jaccard + recency decay).

ctx_risk_overlay

Per-file composite risk: churn 35% + bug density 30% + bus factor 20% + coupling 15%.

Utilities4

ctx_rules_check

Check .ctxloom/rules.yml against the live dependency graph. Returns {schemaVersion:1, violations, warnings}. Config reloaded on every call.

ctx_get_rules

Inject project rules from .cursorrules, CLAUDE.md, .ctxloomrc.

ctx_status

Server status: graph size, vector count, init state.

ctx_get_workflow

Pre-written tool sequences for review/debug/onboard/refactor/audit.

Feature

Git Risk Overlay

Enable

ctxloom . --with-git --git-window-days=365

Disable (tools degrade gracefully, risk block becomes null)

ctxloom . --no-git

New tools

ctx_git_coupling

Given a file, returns top co-changed siblings with confidence score.

node — target file path
limit — default 10
minConfidence — default 0.1
windowDays — default 365

ctx_risk_overlay

Per-file composite risk score 0–1.

low < 0.4

medium 0.4–0.7

high ≥ 0.7

Enriched tools

ctx_detect_changes— each file now includes overlay_risk block with churn, bug density, owners, coupled siblings.

ctx_blast_radius— adds historicalCoupling section for files that co-change but aren't reachable via imports.

🔒The overlay is local only. No code or commit metadata is sent anywhere.

Feature

Architecture Rules Engine

Enforce import boundaries as a CI lint step — no runtime overhead, no flaky tests.

Quick start

bash

# Check rules against the indexed dependency graph
ctxloom rules check

# JSON output (CI-friendly)
ctxloom rules check --json

# Use existing snapshot, skip re-indexing
ctxloom rules check --use-snapshot

Config — `.ctxloom/rules.yml`

.ctxloom/rules.yml

version: 1
rules:
  - name: domain must not import infra
    type: no-import
    from: "src/domain/**"
    to: "src/infra/**"
    severity: error        # optional, defaults to "error"

  - name: no legacy shared imports
    type: no-import
    from: "src/features/**"
    to: "src/shared/legacy/**"
    severity: warning

Rule fields

Field	Required	Description
name	✅	Human-readable label shown in violations
type	✅	Always no-import in v1
from	✅	picomatch glob — files that must not import
to	✅	picomatch glob — files that must not be imported
severity	❌	"error" (default) or "warning"

Exit codes

Code	Meaning
0	Clean — no error violations (warnings are allowed)
1	One or more error-severity violations found
2	Config file invalid or I/O error

CI integration

.github/workflows/rules.yml

name: Architecture rules
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g ctxloom-pro
      - run: ctxloom index
      - run: ctxloom rules check --json

MCP tool — `ctx_rules_check`

Exposes the same engine to your AI assistant. Config is reloaded on every call — no server restart needed when rules change.

Response (schemaVersion: 1)

{
  "schemaVersion": 1,
  "violations": [
    {
      "rule": "domain must not import infra",
      "severity": "error",
      "from": "src/domain/user.ts",
      "to": "src/infra/db.ts"
    }
  ],
  "warnings": []
}

⚠v1 limitation: only direct imports are checked — transitive violations are not detected. Transitive support is planned for v2.

GitHub App

ctxloom-botBeta

What ctxloom-bot does on every PR:

→Posts risk-scored summary: overall risk label + score, blast radius, top high-risk files
→Inline review comments at highest-risk lines
→Suggests reviewers from git ownership data
→Slash commands: /ctxloom explain <file>, /ctxloom ignore, /ctxloom refresh
→Optional Check Run to gate merges on risk threshold

Config via `.ctxloom.yml`

.ctxloom.yml

risk_threshold: 0.7
inline_comments: true
suggested_reviewers: true
check_run: false
excluded_paths: []
max_inline_per_pr: 10

🔒All analysis is local to the bot host. No source code leaves the machine.

Web Dashboard

A local web UI that visualises your codebase's graph, risk, ownership, and community data in real time — no cloud required.

Launch

bash

# Index first (with git history for full metrics)
ctxloom index --with-git

# Start the dashboard
ctxloom dashboard

Visit http://localhost:7842 — no browser extension required. Use --port=N to change the port or --open to auto-launch the browser.

Views

View	What it shows
Overview	File count, edge count, community count, git status, risk breakdown donut, top architectural hubs
Dependency Graph	Interactive D3 force-directed graph — hover for details, click to highlight neighbours, search to pan, community colour legend, risk rings for high/critical files
Risk	Sortable, filterable table with composite risk score (churn × 0.3 + bug density × 0.3 + bus factor × 0.2 + coupling × 0.2)
Communities	Auto-detected Louvain modules — expandable cluster cards listing all member files
Ownership	Per-file primary owner, share %, bus factor — filterable by file or contributor name
Guide	In-app reference explaining every metric and how to interpret the data

Interactivity

◆Click any filename in Risk, Ownership, or Communities to open a file preview drawer with full source and an Open in IDE button (VS Code, Cursor, or system default).
◆Auto-reload — the dashboard watches .ctxloom/graph-snapshot.json and reloads in-place when ctxloom index updates it. No server restart needed.
◆↻ Refresh button in the Overview header triggers a manual reload of all graph and git data.

Risk Tiers

Tier	Score	Meaning
critical	> 0.8	Urgent — high churn, sole owner, heavily coupled
high	> 0.6	Should be addressed soon
medium	> 0.3	Monitor — watch for growth
low	≤ 0.3	Acceptable

◆Git history is required for Risk, Ownership, and bus factor data. Run ctxloom index --with-git to enable the full risk overlay before launching the dashboard.

Reference

Language Support

Language	Import Graph	Symbol Index	Skeletonization
TypeScript / JavaScript	✅ Full AST	✅	✅
Python	✅ Relative imports	✅	✅
Rust	✅ mod resolution	✅	✅
Go	✅ go.mod module-path	✅	✅
Java	✅ Dot-to-slash	✅	✅
C#	✅ Namespace resolution	✅	✅
Ruby	✅ Relative paths	✅	✅
Kotlin	✅ Package imports	✅	✅
Swift	✅ Module imports	✅	✅
PHP	✅ PSR-4 + require_once	✅	❌
Dart	✅ Relative imports	✅	❌
Vue SFC	✅ Script block	✅	❌
Jupyter Notebook	✅ Python cell imports	✅	❌

Internals

Architecture

System Overview

Entry Point

MCP Interface

Stdio transport

API Layer

32 Tools — ToolRegistry

SearchGraph IntelligenceNavigationReviewGit Risk

Context Engine

Dependency

Graph

VectorDB

LanceDB

Skeletonizer

tree-sitter

Sync Layer

File Watcher

chokidar · 200ms debounce · incremental re-index

Persistence

Snapshot Manager

atomic writes · crash-safe · local filesystem

How search works

1
Embed — Query embedded with sentence-transformers/all-MiniLM-L6-v2 (local, 384-dim)
2
Vector search — ANN query against LanceDB
3
Graph expansion — Results expanded via import graph (importers/imports get score boost)
4
Skeletonize — Dependency files reduced to signature-only views (~92% token reduction)

Performance

Token Reduction Benchmarks

Measured on real open-source repos — not estimated.

Repository	Language	Raw tokens	Skeleton tokens	Reduction
expressjs/express	JavaScript	~4,646	~390	92%
sindresorhus/got	TypeScript	~10,807	~742	93%
SergioBenitez/Rocket	Rust	~1,281	~90	93%
fastify/fastify	JavaScript	~2,136	~202	91%
Average				92%

Reproduce benchmarks

npm run bench:repos

Security

✓Path traversal prevention (CWE-22), symlink-aware — all file inputs validated against project root
✓Shell injection prevention — execFileSync with argument arrays, no shell string interpolation
✓XML injection prevention — all user-controlled strings escaped before XML output
✓File size limits — files over 5 MB rejected and skipped by indexer
✓Input bounds — limit capped at 100, depth capped at 20 across all tools
✓Atomic snapshot writes — written to .tmp then renamed, prevents torn reads
✓Snapshot schema validation — validated before hydration, prevents prototype pollution

Configuration

Environment Variables

Variable	Description	Default
CTXLOOM_ROOT	Project root directory to index	Current working directory
LOG_LEVEL	Logging verbosity: debug / info / warn / error	info
CTXLOOM_GRAMMAR_CDN	CDN base URL for grammar downloads (air-gapped environments)	Built-in

Advanced

Build from Source

bash

git clone https://github.com/kodiii/ctxloom.git
cd ctxloom
npm install
npm run build
ctxloom index
node dist/index.js

Changelog

v0.8.0Architecture Rules EngineApril 2026

+ctxloom rules check CLI — lint import boundaries against the dependency graph
+ctx_rules_check MCP tool — same engine available to AI assistants, config reloaded per call
+.ctxloom/rules.yml — picomatch glob rules with no-import type and error/warning severity
+--json, --use-snapshot, --limit flags on rules check
+Exit codes: 0 = clean, 1 = error violations, 2 = config error

v0.7.0Git History SprintApril 2026

+ctx_git_coupling — co-change coupling from git history
+ctx_risk_overlay — per-file composite risk score
+ctxloom-bot — GitHub App with PR comments, inline annotations, slash commands
+--with-git flag (on by default), --no-git to disable
~ctx_detect_changes enriched — overlay_risk block per file
~ctx_blast_radius enriched — historicalCoupling section

v0.6.0Competitive Parity Sprint

+ctx_find_large_functions
+detail_level="minimal" on 7 tools (40–60% fewer tokens)
+PHP, Dart, Vue SFC language support
+Graph export: SVG + interactive D3.js HTML formats
+Real benchmark numbers: 92% on 5 real repos

v0.5.0

+ctx_full_text_search, ctx_suggested_questions, ctx_detect_changes
+ctx_apply_refactor (dry_run supported)
+ctx_get_workflow (5 workflow templates)
+ctx_graph_snapshot, ctx_graph_diff
+Jupyter notebook support

v0.4.0

+ctx_community_list, ctx_architecture_overview, ctx_knowledge_gaps
+ctx_surprising_connections, ctx_wiki_generate, ctx_graph_export
+ctx_git_diff_review, ctx_refactor_preview, ctx_execution_flow
+ctx_cross_repo_search, go.mod module-path resolution

ctxloom Documentation

Quick Start

Install

Configure AI tools

Index project

CLI Commands

MCP Tools32

Git Risk Overlay

New tools

Enriched tools

Architecture Rules Engine

Quick start

Config — .ctxloom/rules.yml

Rule fields

Exit codes

CI integration

MCP tool — ctx_rules_check

ctxloom-botBeta

Config via .ctxloom.yml

Web Dashboard

Launch

Views

Interactivity

Risk Tiers

Language Support

Architecture

How search works

Token Reduction Benchmarks

Security

Environment Variables

Build from Source

Changelog

Config — `.ctxloom/rules.yml`

MCP tool — `ctx_rules_check`

Config via `.ctxloom.yml`