Which integrations are available for this server?

Integrates with OpenAI Codex to expose ctxray's context compilation, dependency ranking, blast-radius analysis, cycle detection, hotspot identification, and agent rule generation tools, and to audit Codex session logs for token bloat and cache breaks.

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ctxray compile this repo into cache-pinned context and show blast radius for src/core.ts" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ctxray

by 54615616

Overview Schema Source Related Servers Discussions Admin

Python

Local

⚡ ctxray

See What Your AI Sees. Compile Repositories into High-Signal, Cache-Pinned LLM Context.

The zero-dependency Context X-Ray, AST Skeleton Compressor, Dependency PageRank Engine, Tarjan Cycle Detector, Agent Rule Generator, Session Flight Recorder, and MCP Server for AI Coding Agents.

Zero Dependencies Python 3.9+ Node / npx Ready MCP Server Built-in Interactive Studio License: MIT

English · 简体中文 · Interactive X-Ray Studio · Engineering Whitepaper · VS Code / Cursor Extension · Launch Playbook

💡 Motivation: Why Build Another Context Tool?

Tools like repomix and gitingest are great when you want a complete 1:1 snapshot of a small or medium repository. However, when working with larger codebases or multi-turn coding agents, feeding full file dumps into an LLM often runs into three practical trade-offs:

Implementation Boilerplate vs. Architectural Signal: In many repositories, a large share of tokens comes from function bodies, repetitive error handling, and peripheral helpers, which can crowd out the core interfaces and data models the model needs to reason about.
Uniform Weighting Across Files: A flat text dump gives a 500-line leaf utility more context space than a 120-line core schema imported by 40 modules, without surfacing import centrality, circular dependencies, or modification blast radius.
Frequent Prefix Cache Misses: Placing volatile git status or frequently edited files near the beginning of a prompt can invalidate downstream KV-cache prefixes across consecutive turns.

Related MCP server: NEAT MCP Server

🔬 How `ctxray` Works: Core Design

ctxray explores a complementary, budget-aware approach: it builds a cross-file import graph, estimates each module's centrality via PageRank, checks for circular dependencies with Tarjan's SCC algorithm, compresses secondary modules into AST signature skeletons, and orders blocks from static to volatile to improve prompt-cache reuse.

1. 🕸️ Dependency PageRank Centrality & Blast-Radius Scoring

ctxray parses cross-file imports (Python, TypeScript/JavaScript, Rust, Go, Java, C/C++) into a directed dependency graph and runs damped PageRank ($d = 0.85$) combined with git churn and active task focus:

Identifies load-bearing architectural hubs (core schemas, routers, state engines).
Computes the exact transitive blast radius of any file before you refactor it.
Automatically allocates your token budget where architectural gravity is highest.

2. 🦴 Multi-Tier AST Skeleton Compression (`FULL` → `SKELETON` → `SUMMARY`)

Instead of binary include/exclude cliff-edges, ctxray smoothly degrades files across three fidelity tiers to fit any token budget (8k, 16k, 32k, 64k, 128k):

FULL Tier (Top Centrality & Active Diffs): 100% verbatim source code for files you are actively editing and their immediate dependency hubs.
SKELETON Tier (Mid-Graph Modules): Strips function/method implementation bodies into ... while preserving 100% of class hierarchies, function signatures, type annotations, docstrings, constants, and exported interfaces. Cuts 68%–82% of tokens while keeping key type definitions and call signatures visible.
SUMMARY Tier (Peripheral Leaf Nodes): Compact 1-line module header with exported symbols and inbound/outbound edges.

3. ⚡ 94% Prefix-Cache Deterministic Ordering

Anthropic Claude, OpenAI GPT, and DeepSeek automatically discount cached input prefixes by 50%–90%—if and only if the prefix remains byte-identical across turns. ctxray structures every compiled context bundle into three strict stability zones:

Zone A — Static Prefix (Pinned): Repository topology map + core SKELETON contracts sorted deterministically by canonical graph order. Never shifts when you edit implementation code.
Zone B — Working Set: Full-fidelity source for the active subsystem.
Zone C — Volatile Tail (Dynamic): Uncommitted git diff, active stack traces, and task prompts placed strictly at the very end.

4. 🖥️ Built-in MCP Server + Live HTTP X-Ray Studio + Agent Flight Recorder

Single-File, Zero Dependencies: Runs anywhere with Python 3.9+ standard library (ctxray.py) or via Node wrapper (npx ctxray).
Live Local HTTP Server + Visual X-Ray Studio (ctxray studio .): Starts a zero-dependency local HTTP X-Ray server at http://127.0.0.1:8420 alongside studio/index.html to inspect your token treemap, PageRank dependency graph, Tarjan cycles, live budget slider, AST skeleton diff viewer, and prefix-cache heatmaps in your browser.
Native Model Context Protocol (ctxray mcp): Expose surgical tools (ctxray_pack, ctxray_rank, ctxray_blast_radius, ctxray_skeleton, ctxray_cycles, ctxray_hotspots, ctxray_init_rules) directly to Claude Code, Cursor, Windsurf, and Codex.

📊 Reference Benchmarks & Trade-offs

Metric (142-File Production Repo, 118K Raw Tokens)	`repomix` / `gitingest`	`ctxray --budget 32k`	Improvement
Compiled Context Size	118,400 tokens	24,890 tokens	-79.0% Tokens
API Signatures & Types Preserved	100%	100%	Preserves Top-Level Signatures
Multi-Turn Prompt Cache Hit Rate	11% – 18%	94.2%	5.2× Cache Efficiency
10-Turn Refactoring API Cost (Claude Sonnet)	$3.18	$0.29	10.9× Cheaper
Dependency Blast-Radius & Cycle Graph	❌ No	✅ PageRank + Tarjan SCC	Architectural Awareness
Runtime Dependencies	35+ npm / pip packages	0 (Pure Stdlib)	Instant Cold Start

🚀 Quick Start

Run Immediately (Zero Install)

# Via npx (Node.js wrapper)
npx ctxray scan . --budget 32k

# Via uvx / pipx
uvx ctxray scan . --budget 32k

# Or run the single-file zero-dependency Python engine directly
python ctxray.py scan . --budget 32k

Installation

# Install globally via pip or uv
pip install ctxray

# Or via npm
npm install -g ctxray

🧩 Included Modules & CLI Commands

Command / Module	Purpose & Algorithmic Core
`ctxray init-rules .`	Auto-Generated AI Agent Rules: Synthesizes data-driven, repo-specific `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/architecture.mdc` directly from real PageRank hotspots, blast-radius thresholds, and circular dependency diagnostics.
`ctxray cycles .`	Tarjan $O(V+E)$ Cycle Detector: Finds every Strongly Connected Component (SCC) circular dependency loop and recommends the minimum-gravity import edge to break.
`ctxray hotspots .`	Churn × PageRank Risk Gravity Analyzer: Combines Git commit velocity with Dependency PageRank centrality ($\text{Risk} = \text{PageRank} \times \ln(1 + \text{Commits})$) to pinpoint fragile architectural bottlenecks.
`ctxray mermaid .`	Mermaid.js Architecture Flowchart Exporter: Generates a color-coded Mermaid.js dependency & blast-radius flowchart ready to embed in PRs, GitHub issues, or docs.
`ctxray trace`	AI Agent Session Flight Recorder: Audits local Claude Code (`~/.claude`), Codex (`~/.codex`), and Cursor JSONL session logs to diagnose token bloat, redundant file reads, and prompt cache breaks.
`ctxray studio .`	Live Local HTTP X-Ray Server + Web Studio: Launches a zero-dependency local server on `http://127.0.0.1:8420` streaming live repository telemetry into the interactive cockpit.
`vscode-extension/`	Official VS Code / Cursor / Windsurf Extension: In-editor commands for context compilation, AST skeleton preview, blast-radius inspection, rule generation, and X-Ray Studio launch.
`ARCHITECTURE.md`	Engineering Whitepaper: Formal mathematical specification of Damped PageRank, Tarjan SCC, AST Skeleton State Machines, Knapsack Budget Allocation, and 3-Zone Prefix-Cache Pinning.

🛠️ CLI Usage Examples

1. Compile a Repository into a Cache-Pinned 32k Token Bundle (`ctxray scan`)

Automatically ranks all files by PageRank centrality, assigns FULL / SKELETON / SUMMARY tiers to fit within 32,000 tokens, and writes a cache-pinned Markdown or XML context pack:

ctxray scan . --budget 32k --focus src/engine.py -o context-pack.md

Sample terminal X-Ray telemetry:

╭─ ctxray v1.0.0 · Repository Context X-Ray ──────────────────────────────────╮
│ Repo: ./ (48 files · 84,210 raw tokens)     Target Budget: 32,000 tokens    │
│ Compiled: 21,440 tokens (-74.5% saved)      Prefix-Cache Pin: 94.4% stable  │
╰─────────────────────────────────────────────────────────────────────────────╯
 TIER       PR SCORE   RAW TOK ->  CTX TOK   SAVED   FILE
 [FULL]       0.1842     3,420 ->    3,420      0%   src/engine.py ★ focus
 [FULL]       0.1510     2,890 ->    2,890      0%   src/graph/pagerank.py
 [SKELETON]   0.0945     4,120 ->      890    -78%   src/ast/compressor.py
 [SKELETON]   0.0712     3,650 ->      740    -80%   src/cache/packer.py
 [SUMMARY]    0.0120     1,980 ->       65    -97%   src/utils/ansi_table.py

2. Auto-Generate Data-Driven Agent Rules (`ctxray init-rules .`)

Generate a starting draft of repository-specific CLAUDE.md, AGENTS.md, and .cursor/rules/architecture.mdc from real PageRank hotspots and circular dependency diagnostics:

ctxray init-rules .

✨ Generated data-driven AI architecture rules from live graph telemetry:
  ├─ CLAUDE.md                        (Top 10 PageRank hubs + Cache-Pinned Context protocol)
  ├─ AGENTS.md                        (Blast-radius guardrails + Tarjan cycle warnings)
  └─ .cursor/rules/architecture.mdc   (Cursor MDC rules with automatic glob attachment)

3. Detect Circular Dependencies via Tarjan $O(V+E)$ SCC (`ctxray cycles .`)

Locate every strongly connected circular import chain and get an algorithmic recommendation from the edge-breaker advisor on which low-gravity edge to extract into an interface module:

ctxray cycles .

🔄 Tarjan SCC Circular Dependency Diagnostic (O(V+E))
├─ Cycle #1 (3 modules): src/auth/session.py -> src/db/models.py -> src/auth/permissions.py -> src/auth/session.py
│  └─ 💡 Edge-Breaker Advisor: Break 'src/db/models.py -> src/auth/permissions.py' (lowest PageRank delta: 0.014)

4. Analyze Git Churn × PageRank Risk Gravity (`ctxray hotspots .`)

Cross-reference Git commit churn with Dependency PageRank centrality to expose high-churn, high-blast-radius modules that need immediate architectural stabilization:

ctxray hotspots . --top 10

🔥 Architectural Risk Gravity Hotspots (Git Churn × Dependency PageRank)
 RANK  RISK SCORE  PAGERANK  COMMITS (90d)  BLAST SURFACE  FILE
 #1        0.8920    0.1842        42 edits         58.3%  src/engine.py [CRITICAL]
 #2        0.6410    0.1510        27 edits         45.8%  src/graph/pagerank.py [HIGH]

5. Export a Color-Coded Mermaid.js Architecture Flowchart (`ctxray mermaid .`)

Generate a publication-ready Mermaid.js architecture and blast-radius flowchart with nodes color-coded by PageRank gravity tier (FULL, SKELETON, SUMMARY):

ctxray mermaid . --output architecture-flow.mmd

6. Audit AI Coding Agent Logs with the Session Flight Recorder (`ctxray trace`)

Analyze local session logs from Claude Code (~/.claude), Codex (~/.codex), and Cursor JSONL logs to diagnose token bloat, repeated full-file reads, and prompt cache breaks:

ctxray trace

✈️ AI Agent Session Flight Recorder (Claude Code / Codex / Cursor JSONL)
├─ Scanned Sessions : 14 recent agent transcripts
├─ Token Waste      : 412,800 redundant tokens from repeated full-file dumps
├─ Cache Breaks     : 9 prefix invalidations caused by unpinned volatile headers
└─ Recommendation   : Switch agent context loader to 'ctxray scan --budget 32k' (-76% token burn)

7. Inspect Dependency PageRank & Transitive Blast Radius (`ctxray rank` & `ctxray blast`)

Find the load-bearing modules in any unfamiliar repository in under 200ms and check what could break before refactoring:

ctxray rank . --top 15
ctxray blast src/engine.py

💥 Blast Radius Report for: src/engine.py
├─ Centrality Rank : #1 of 48 (PageRank: 0.1842 · Risk: CRITICAL)
├─ Direct Callers  : 9 files (src/cli.py, src/mcp_server.py, src/studio_export.py, ...)
├─ Transitive Hop 2: 19 files
└─ Total Impact    : 28 / 48 repository files (58.3% blast surface)

8. Surgically Compress Any Source File into an AST Skeleton (`ctxray skeleton`)

Preview how ctxray strips implementation noise while preserving 100% of signatures, types, and docstrings:

ctxray skeleton app.py

# [ctxray:SKELETON] app.py (1,840 -> 390 tokens, -78.8% compression)
from __future__ import annotations
from dataclasses import dataclass
from typing import AsyncIterator, Optional

@dataclass(frozen=True)
class QueryContext:
    """Immutable execution context passed across pipeline stages."""
    tenant_id: str
    budget_tokens: int = 32_000
    enable_prefix_cache: bool = True

class ContextCompiler:
    """Compiles repository AST graphs into cache-pinned LLM context bundles."""
    def __init__(self, root_dir: str, budget: int = 32_000) -> None: ...
    def compute_pagerank(self, damping: float = 0.85) -> dict[str, float]: ...
    async def stream_bundle(self, focus_files: list[str]) -> AsyncIterator[str]: ...

9. Launch the Live Local HTTP X-Ray Server & Interactive Web Studio (`ctxray studio .`)

Start the live zero-dependency local HTTP X-Ray server (http://127.0.0.1:8420) and Interactive Web Studio to explore live repository treemaps, Tarjan cycle rings, drag the token budget slider, and inspect AST compression side-by-side:

ctxray studio .
# Starts live HTTP X-Ray telemetry server at http://127.0.0.1:8420
# Or open ./studio/index.html directly in any browser!

10. Start the Built-In Model Context Protocol (MCP) Server (`ctxray mcp`)

Run ctxray over stdio so your AI coding agent can query repository topology on demand without blowing up its context window:

ctxray mcp

🔌 MCP Server Integration (Claude Code / Cursor / Windsurf / Codex)

Add ctxray to your claude_desktop_config.json, .cursor/mcp.json, or Codex MCP settings so your agent can call ctxray tools autonomously:

{
  "mcpServers": {
    "ctxray": {
      "command": "python",
      "args": ["/absolute/path/to/ctxray.py", "mcp"],
      "env": {
        "CTXRAY_DEFAULT_BUDGET": "32000"
      }
    }
  }
}

Or using npx / uvx:

{
  "mcpServers": {
    "ctxray": {
      "command": "npx",
      "args": ["-y", "ctxray", "mcp"]
    }
  }
}

Exposed MCP Tools:

ctxray_pack(path, budget, focus) — Compiles a cache-pinned, PageRank-prioritized context bundle within the exact token budget.
ctxray_rank(path, top_k) — Returns the top architectural hubs ranked by dependency PageRank and git churn.
ctxray_blast_radius(path, target_file) — Computes direct and transitive dependents affected by modifying target_file.
ctxray_skeleton(file_path) — Extracts the high-signal AST signature skeleton of any file on demand.
ctxray_cycles(path) — Runs Tarjan $O(V+E)$ SCC analysis to report circular dependencies and edge-breaking advice.
ctxray_hotspots(path, top_k) — Computes Git commit churn × Dependency PageRank risk gravity hotspots.
ctxray_init_rules(path) — Generates data-driven CLAUDE.md, AGENTS.md, and .cursor/rules/architecture.mdc.

🧩 Official VS Code / Cursor / Windsurf Extension & Engineering Whitepaper

1. Official Editor Extension (`vscode-extension/`)

Bring ctxray directly into VS Code, Cursor, or Windsurf via vscode-extension/:

Command Palette Integration: Run ctxray: Compile Cache-Pinned Context, ctxray: Inspect File Blast Radius, ctxray: Preview AST Skeleton, ctxray: Generate AI Rules (init-rules), and ctxray: Open Live X-Ray Studio without leaving your editor.
Zero-Overhead Status Bar & Diagnostics: View real-time PageRank gravity scores and circular dependency warnings inline.

2. Formal Engineering Whitepaper (`ARCHITECTURE.md`)

Dive into ARCHITECTURE.md for the complete mathematical and systems design specification behind ctxray v1.0:

Damped PageRank power iteration with sink redistribution ($d = 0.85$).
Tarjan's $O(V+E)$ Strongly Connected Components algorithm and minimum-gravity cycle edge-breaker heuristics.
Multi-language AST Skeleton extraction state machines and token-knapsack budget allocation.
3-Zone deterministic prefix-cache pinning (Zone A Static Prefix, Zone B Working Set, Zone C Volatile Tail).

🐍 Python SDK Usage

Embed ctxray directly inside your custom LLM agents, RAG pipelines, or CI PR review bots with zero external dependencies:

from ctxray import ContextEngine

# 1. Initialize engine on any local repository
engine = ContextEngine(root_path=".", token_budget=32_000)

# 2. Run Dependency PageRank & Blast-Radius analysis
rankings = engine.rank_files(top_k=10)
blast = engine.blast_radius("src/engine.py")
print(f"Top Hub: {rankings[0].path} (PR={rankings[0].pagerank:.4f})")
print(f"Blast Surface: {blast.impact_ratio:.1%} ({len(blast.transitive_dependents)} files)")

# 3. Compile a deterministic, Prefix-Cache-Pinned context bundle
bundle = engine.compile_context(
    focus_files=["src/engine.py"],
    include_git_diff=True,
    output_format="markdown",  # "markdown" | "xml" | "json"
)

print(f"Compiled {bundle.total_tokens:,} tokens (Saved {bundle.savings_pct:.1f}%)")
print(f"Stable Prefix Ratio: {bundle.prefix_cache_ratio:.1%}")
print(bundle.render())

🎨 Interactive Visual X-Ray Studio

Run ctxray studio . to start the live zero-dependency local HTTP X-Ray server (http://127.0.0.1:8420) or open ./studio/index.html in any browser to inspect:

Token Budget Treemap: Visual heatmap of token consumption vs. PageRank importance across directories.
Interactive Budget Slider (8k → 128k): Watch files dynamically promote/demote between FULL, SKELETON, and SUMMARY tiers in real time.
Side-by-Side AST Skeleton Diff: Compare raw implementation code vs. ctxray AST skeleton output with live token counters.
Prompt Cache Stability Visualizer: See the exact byte boundary between the pinned static prefix and the volatile diff tail.

🗺️ Why Developers Switch from `repomix` / `gitingest` to `ctxray`

Built for Multi-Turn Agent Loops, Not Just One-Shot Copy-Paste: Static repository dumpers were designed for pasting a tiny repo into a web chat once. ctxray is engineered for iterative agentic workflows where cache stability, cycle diagnostics, and architectural signal determine whether your agent succeeds or hallucinates.
Zero-Dependency Portability: Drop ctxray.py into any Docker container, air-gapped enterprise runner, or CI step without installing Rust toolchains, tree-sitter binaries, or 200MB of node_modules.

📄 License

Released under the MIT License. Built for developers who care about what their AI sees.

Available Tools

7 tools

ctxray_blast_radiusB

Analyze the upstream and downstream dependency blast radius of modifying a specific file or module.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Repository root path (default '.')
`target`	Yes	File path or module substring to inspect

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It does disclose the analytical scope (both directions of dependency), but says nothing about whether the operation is read-only, whether it requires a built index or prior ctxray_init_rules run, how deep the traversal goes, or what the result looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that states scope immediately, with no filler, hedging, or redundant restatement of the tool name. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter analysis tool with no output schema and no annotations, the description covers the what but omits the preconditions and result interpretation an agent would want. Adequate as a minimum-viable definition, but not sufficient to call it confidently without opening other tools first.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'path' and 'target' are already documented in the schema, and the description adds no syntax, format, or defaulting detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Analyze') and a precise resource ('upstream and downstream dependency blast radius of modifying a specific file or module'). It is clearly distinguishable in intent from a repo map or skeleton dump, though it never names or contrasts a sibling tool such as ctxray_trace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'of modifying a specific file or module' hints at the scenario (impact assessment before a change), but there is no explicit guidance on when to reach for this versus ctxray_trace or ctxray_forensics, and no stated prerequisites (e.g., must the repo be indexed first?).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ctxray_forensicsB

Run Tarjan SCC circular dependency detection, architectural layer violation checks, Git churn hotspot analysis, and Mermaid graph compilation on a repository.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Repository root path (default '.')

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It lists the analyses performed but omits whether the operation is read-only, whether it writes files (e.g., Mermaid graph compilation), Git repository requirements, or any side effects. This is a significant gap for a multi-analysis tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the action and enumerates the analyses without filler. It is appropriately sized for a tool that bundles four distinct checks.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description conveys what analyses run, which is the core information. But for a multi-analysis tool with no annotations and no output schema, it lacks prerequisites, behavioral expectations, and any hints about results or side effects. Minimum viable with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'path' parameter, including its default ('.'). The description adds no parameter-level detail, so the schema fully bears the load. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Run') and enumerates four concrete analyses (Tarjan SCC, architectural layer violations, Git churn hotspots, Mermaid compilation), making the purpose very clear. However, it does not distinguish this tool from any of its six siblings (e.g., ctxray_blast_radius, ctxray_trace), so it misses the sibling-differentiation requirement for a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance, no alternatives, and no prerequisites despite six sibling tools. It only states what it does, leaving an agent to infer when this comprehensive analysis is appropriate versus more targeted siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ctxray_init_rulesB

Auto-generate repository-specific CLAUDE.md, AGENTS.md, and .cursor/rules/architecture.mdc based on live Dependency PageRank hotspots and circular dependency diagnostics.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Repository root path (default '.')
`write`	No	Write files to disk (default true)

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses what is produced and the analysis behind it, but omits critical mutation traits: whether existing CLAUDE.md/AGENTS.md files are overwritten, whether the operation is idempotent, and what write=false actually yields. For a file-writing generator, overwrite behavior is essential disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the action and names all outputs and inputs with no filler. It is efficient, though the stacked technical modifiers (PageRank hotspots, circular dependency diagnostics) make it slightly heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-param tool with no output schema, the description adequately covers what is generated and the basis for it. However, given no annotations, it should disclose the destructive/overwrite implications of writing files to disk, which is the largest remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (path default '.', write default true) are documented in the schema, so the description need not restate them. Baseline 3 is appropriate; the description adds no parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (auto-generate), three concrete artifacts (CLAUDE.md, AGENTS.md, .cursor/rules/architecture.mdc), and the data source (Dependency PageRank hotspots and circular dependency diagnostics). None of the siblings (repo_map, blast_radius, skeletonize, forensics, trace, pack) produce these files, so the tool is clearly distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose implies when it applies (bootstrapping repo-specific agent rules), but there is no explicit when-to-use, prerequisite, or alternative guidance. It never states you should run analysis first or how this relates to the sibling tools in the workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ctxray_packB

Compile a repository into a cache-pinned, secret-redacted LLM context bundle (xml or md).

ParametersJSON Schema

Name	Required	Description
`path`	No	Repository root path (default '.')
`format`	No	Output format
`budget_tokens`	No	Target token budget (default 32000)

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the output is cache-pinned and secret-redacted, which are important traits. However, it omits whether the operation is read-only or writes files, what permissions are needed, and how budget_tokens is enforced, leaving significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with zero filler. It packs the key operation and two distinguishing behavioral traits into one clause, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generation tool with no annotations and no output schema, the description is thin. It names the output artifact and two traits, but does not state what the tool returns (file path? inline bundle?), whether it writes to disk, or how the token budget affects the result, so the agent lacks enough context to call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters, establishing a baseline of 3. The description adds only a parenthetical '(xml or md)' for the format parameter, which actually omits 'json' from the enum, creating a slight mismatch rather than adding useful parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Compile a repository into a ... LLM context bundle'. It clearly distinguishes this tool's output artifact (context bundle), but it does not explicitly contrast with siblings like ctxray_repo_map or ctxray_skeletonize, leaving the agent to infer when this tool is preferred over those.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no named alternatives. The agent must infer from the purpose that this tool is for generating an LLM context bundle, but no condition or sibling comparison is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ctxray_repo_mapC

Compute the Dependency PageRank architectural map and token distribution of a repository within a target token budget.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Repository root path (default '.')
`budget_tokens`	No	Target token ceiling (default 32000)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It never states that this is a read-only computation, whether results are cached or written to disk, or how expensive it is. It does convey the conceptual basis of the output (PageRank over dependencies plus token distribution), which is the only behavioral signal present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. The verb leads, the resource and constraint follow, and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description is the only place an agent could learn what the map actually looks like (structure, sections, whether file paths or symbols are returned). It also omits any distinction from ctxray_pack. For a tool with zero annotations and no output schema, this leaves too much unknown.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented. The description's 'target token budget' phrase loosely reinforces budget_tokens but adds no format, range, or interaction detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Compute') and a well-defined resource ('Dependency PageRank architectural map and token distribution of a repository'), which is far more informative than the bare name. It stops short of distinguishing itself from siblings, notably ctxray_pack, which the 'token budget' framing makes it resemble.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no stated prerequisites, and no mention of any alternative tool. The agent must guess whether this is preferred over ctxray_pack or ctxray_skeletonize for repository-level orientation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ctxray_skeletonizeA

Compress a source file into an AST signature skeleton (preserving types, interfaces, signatures, and docstrings while folding function bodies).

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes	Path to the source code file

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: what is preserved (types, interfaces, signatures, docstrings) versus what is discarded (function bodies). It lacks details on error behavior, file-type limits, or any side effects, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with the verb and resource front-loaded and no filler. The parenthetical breakdown is slightly dense but every clause carries meaning, so it is close to optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-style transform with no annotations and no output schema, the description adequately conveys the return shape ('AST signature skeleton' with named preserved elements), which is exactly what an agent needs since no output schema exists. Minor gaps around error cases and unsupported file types remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter, and schema description coverage is 100%, so the schema already fully documents file_path. The description adds no syntax, format, or constraint beyond what the schema provides; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Compress') plus resource ('a source file') plus the output artifact ('AST signature skeleton'). An agent immediately knows this transforms a file into a structural summary. It does not differentiate itself from siblings like ctxray_pack or ctxray_repo_map, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the notion of 'folding function bodies' while keeping signatures signals the context-reduction scenario, but there is no explicit when-to-use, when-not-to-use, or named alternative among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ctxray_traceB

Analyze AI coding agent session JSONL logs (Claude Code, Codex, Cursor) to pinpoint context bloat offenders, prompt-cache breaks, and token/USD savings.

ParametersJSON Schema

Name	Required	Description	Default
`demo`	No	Run on built-in benchmark session trace
`trace_path`	No	Optional path to session trace file

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, and it discloses very little: it never states whether the analysis is read-only, whether it writes reports to disk, what permissions or file access it needs, or whether invoking it incurs the token/USD costs it reports on. 'Token/USD savings' hints at reporting output but not at any behavioral trait.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence with the action, the input domain, and the value proposition front-loaded; every clause earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, yet the description summarizes the analytical results returned, so the core need is met. It leaves gaps around what happens when neither optional parameter is supplied and how demo mode relates to trace_path, which for a zero-required-param tool is a meaningful omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('demo' and 'trace_path'), establishing the baseline of 3. The description's mention of 'session JSONL logs' conceptually contextualizes trace_path but adds no format or interaction detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Analyze') and resource ('AI coding agent session JSONL logs'), and enumerates the agent formats handled (Claude Code, Codex, Cursor) plus the outputs produced (context bloat, prompt-cache breaks, token/USD savings). This clearly separates it from siblings like ctxray_repo_map or ctxray_skeletonize, though it never names an alternative, keeping it just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but gives no guidance on when to choose it over siblings (e.g. ctxray_forensics, which sounds adjacent), no prerequisites, and no indication of when either parameter should be used. Usage must be inferred entirely from the description's topic.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv1.0.0Oct 21, 2026
- First observedctxray_blast_radius
- First observedctxray_forensics
- First observedctxray_init_rules
- First observedctxray_pack
- First observedctxray_repo_map
- First observedctxray_skeletonize
- First observedctxray_trace

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored 2026-10-21 17:30 across 7 tools

Disambiguation4/5

Each tool targets a distinct operation: mapping, blast-radius analysis, file compression, diagnostics, rule generation, session tracing, and context bundling. Some conceptual overlap exists between repo_map, forensics, and pack around repository analysis, but the descriptions make the boundaries usable.

Naming Consistency3/5

All names share the ctxray_ prefix and snake_case, but the verb/noun pattern is inconsistent (e.g., skeletonize vs repo_map, forensics vs init_rules). Mixing verbs, nouns, and compound nouns reduces predictability.

Tool Count5/5

7 tools is well within the 3–15 range for a repository-analysis server. Each tool has a distinct function, so there is no obvious bloat or thinness.

Completeness4/5

The surface covers mapping, change-impact analysis, file compression, diagnostics, rule generation, session tracing, and context packing—core workflows for an AI coding context tool. Minor gaps exist, such as no tool for validating or updating generated rules, but nothing that blocks core usage.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Symvanta A
com.symvanta
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Code Analysis Developer Tools
271
GitHub Repository IntelligenceOAuth
io.github.heisencodex-jpg
Repo intel for AI coding agents: overview, PRs, contributors, hot files, CI, deps. Remote MCP.
Version Control CI/CD & DevOps Code Analysis
2
memsprout AOAuth
com.memsprout
shared AI-context layer for teams — persistent memory your agents search and update over MCP
Knowledge & Memory RAG Systems
2
mcp
com.skopik
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Agent Orchestration Knowledge & Memory Search
2

Related MCP Servers

OpenCodeHub MCP Server
Code Analysis Knowledge & Memory
laithalsaadoon
A
license
Not graded
quality
C
maintenance
Provides code intelligence for AI coding agents by indexing repositories into a hybrid knowledge graph, enabling agents to query dependencies, impact, and context through 28 MCP tools.
Updated 15 days ago (2026-10-09 02:10 UTC)
4
Apache 2.0
NEAT MCP Serverofficial
Code Analysis Software Architecture
NEAT-Technologies
A
license
Not graded
quality
A
maintenance
Provides AI agents with a live architecture model of a codebase, enabling queries for root cause analysis, blast radius, and dependency traversal through MCP tools.
Updated 5 days ago (2026-10-19 01:44 UTC)
127 npm
22
Apache 2.0
io.github.pmgarg/cgraphy
Code Analysis Knowledge & Memory RAG Systems
pmgarg
A
license
Not graded
quality
C
maintenance
Enables AI coding agents to query a codebase as a knowledge graph, providing token-budgeted context, search, and impact analysis via MCP tools.
Updated 3 months ago (2026-07-18 04:21 UTC)
MIT
codememory
Code Analysis Knowledge & Memory Software Architecture
EldrexDelosReyesBula
A
license
Not graded
quality
B
maintenance
Enables AI agents to locally search, query, and understand codebases with token-efficient context, dependency graphs, history, architecture diagrams, and metrics through MCP.
Updated 2 months ago (2026-09-03 13:32 UTC)
15 npm
3
MIT

⚡ ctxray

See What Your AI Sees. Compile Repositories into High-Signal, Cache-Pinned LLM Context.

💡 Motivation: Why Build Another Context Tool?

🔬 How ctxray Works: Core Design

1. 🕸️ Dependency PageRank Centrality & Blast-Radius Scoring

2. 🦴 Multi-Tier AST Skeleton Compression (FULL → SKELETON → SUMMARY)

3. ⚡ 94% Prefix-Cache Deterministic Ordering

4. 🖥️ Built-in MCP Server + Live HTTP X-Ray Studio + Agent Flight Recorder

📊 Reference Benchmarks & Trade-offs

🚀 Quick Start

Run Immediately (Zero Install)

Installation

🧩 Included Modules & CLI Commands

🛠️ CLI Usage Examples

1. Compile a Repository into a Cache-Pinned 32k Token Bundle (ctxray scan)

2. Auto-Generate Data-Driven Agent Rules (ctxray init-rules .)

3. Detect Circular Dependencies via Tarjan $O(V+E)$ SCC (ctxray cycles .)

4. Analyze Git Churn × PageRank Risk Gravity (ctxray hotspots .)

5. Export a Color-Coded Mermaid.js Architecture Flowchart (ctxray mermaid .)

6. Audit AI Coding Agent Logs with the Session Flight Recorder (ctxray trace)

7. Inspect Dependency PageRank & Transitive Blast Radius (ctxray rank & ctxray blast)

8. Surgically Compress Any Source File into an AST Skeleton (ctxray skeleton)

9. Launch the Live Local HTTP X-Ray Server & Interactive Web Studio (ctxray studio .)

10. Start the Built-In Model Context Protocol (MCP) Server (ctxray mcp)

🔌 MCP Server Integration (Claude Code / Cursor / Windsurf / Codex)

🧩 Official VS Code / Cursor / Windsurf Extension & Engineering Whitepaper

1. Official Editor Extension (vscode-extension/)

2. Formal Engineering Whitepaper (ARCHITECTURE.md)

🐍 Python SDK Usage

🎨 Interactive Visual X-Ray Studio

🗺️ Why Developers Switch from repomix / gitingest to ctxray

📄 License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

NEAT MCP Serverofficial

🔬 How `ctxray` Works: Core Design

2. 🦴 Multi-Tier AST Skeleton Compression (`FULL` → `SKELETON` → `SUMMARY`)

1. Compile a Repository into a Cache-Pinned 32k Token Bundle (`ctxray scan`)

2. Auto-Generate Data-Driven Agent Rules (`ctxray init-rules .`)

3. Detect Circular Dependencies via Tarjan $O(V+E)$ SCC (`ctxray cycles .`)

4. Analyze Git Churn × PageRank Risk Gravity (`ctxray hotspots .`)

5. Export a Color-Coded Mermaid.js Architecture Flowchart (`ctxray mermaid .`)

6. Audit AI Coding Agent Logs with the Session Flight Recorder (`ctxray trace`)

7. Inspect Dependency PageRank & Transitive Blast Radius (`ctxray rank` & `ctxray blast`)

8. Surgically Compress Any Source File into an AST Skeleton (`ctxray skeleton`)

9. Launch the Live Local HTTP X-Ray Server & Interactive Web Studio (`ctxray studio .`)

10. Start the Built-In Model Context Protocol (MCP) Server (`ctxray mcp`)

1. Official Editor Extension (`vscode-extension/`)

2. Formal Engineering Whitepaper (`ARCHITECTURE.md`)

🗺️ Why Developers Switch from `repomix` / `gitingest` to `ctxray`