Clean-CTX

Clean-CTX - Local-first context compiler for AI coding agents

Compiles large codebases into compact, semantically rich, task-relevant context for LLMs - with language-aware IR, workspace semantic indexing, and MCP integration.

Clean-CTX is not a source-code minifier or token compressor. It builds a semantic model of a workspace and compiles the information an AI agent needs into a compact, structured context representation.

The goal is not merely fewer tokens. The goal is better context per token.

Understand the codebase
        ↓
Extract semantic structure
        ↓
Index relationships and provenance
        ↓
Resolve and filter relevant context
        ↓
Compile it into a compact representation
        ↓
Give the AI less noise and more signal

Currently supports TypeScript, C#, Rust, Java language layers with Angular, Spring Boot, .NET (see below for full current meta-layer support) semantic intelligence, IR-level delta transport, workspace semantic indexing, and a multi-platform MCP server.

---

Features

Semantic code intelligence

Clean-CTX understands code as more than text:

• Language-aware parsing - tree-sitter grammars extract structure, not just tokens, for TypeScript, C#, Rust, and Java.
• Semantic Intermediate Representation (SIR) - source compiles into a typed compiler IR (DefClass, DefMethod, DefField, patterns, scopes), from which meta-layers extract a semantic model of entities with identity, provenance, and relationships.
• Entity identity - every class, service, component, action, and selector is identified by (domain, entity_type, name) with file provenance, so the same entity referenced from multiple files compares equal.
• Semantic relationships - typed edges between entities: Injects, HasSelector, Dispatches, Selects, HandlesAction, RouteMapsTo, Autowired, ControllerAction, HasEntity, and 20+ more, each with confidence 1.0 and layer provenance.
• Provenance tracking - every semantic edge records which meta-layer discovered it.

Workspace semantic indexing

A cross-file semantic graph that survives beyond single-file compression:

• WorkspaceIndex - framework-agnostic index of entities and semantic edges across an entire workspace.
• Identity-based lookup - (domain, entity_type, name) is the canonical identity; a separate convenience lookup finds entity occurrences by bare name across all domains and types.
• Forward/reverse relationship traversal - follow Injects, Dispatches, Selects, and other edges in either direction.
• Selector resolution - resolve a CSS selector (app-widget, [app-widget], .app-widget) to the component that exposes it.
• Injection discovery - resolve an injected type to all workspace entities referenced as Injects/Autowired targets (reference occurrences; ambiguity preserved).
• Transitive dependencies - BFS traversal through DI and routing relationships, with cycle detection.

Context compilation

Task-relevant context rather than indiscriminate source dumping:

• Compiles source into LLM-optimized representations - three fidelity levels (Low/Medium/High) plus Edit and Verbatim, each preserving the semantics appropriate to the task.
• Semantic compression - reduces representation size while preserving the relationships downstream consumers depend on.
• Single-pass framework evaluation - one compilation-scoped lexical/capture context is reused across applicability, markers, and semantic-edge extraction, eliminating redundant tree-sitter parses and repeated prefix scans.
• Layered cache reuse - unchanged files reuse canonical IR and tokenizer counts, while CBM graph entries and disk partitions remain isolated by canonical project identity.
• Explicit IR-level delta transport - delta_code_context computes an instruction-level transition and apply_delta acknowledges it through a code-side protocol (up to 53% CPU/latency savings in measured delta workflows). Ordinary context reads remain complete and never silently switch to deltas.
• Structural edits - apply_edit performs byte-exact edits on previously-seen files using the semantic model. The exact physical source precondition is revalidated at commit, so an externally superseded file is never overwritten merely because replacement itself would be atomic.

MCP integration

Exposes code intelligence and context capabilities to AI coding agents through the Model Context Protocol:

• provide_code_context - complete model-facing context for either one filePath or a failure-isolated files batch of 1–8 items; batch callers may choose safe mirrored, structured-only, or indexed content placement. The tool auto-detects file type, selects per-item fidelity, and filters low-importance symbols. Structured delta transport remains explicit through delta_code_context / apply_delta.
• workspace_query - single or heterogeneous batched semantic queries: entity lookup, forward/reverse edges, file entities/calls, transitive dependencies, and cycle detection.
• compress_code_context / restore_context - direct compression control and compatible durable reuse. Restore admits the path and validates current source plus scoped canonical/semantic compatibility before persisted state can become live authority.
• diff_code_context / diff_commits - AST-level change-sets, single-file and git ref-range.
• delta_code_context / apply_delta - explicit, code-side IR delta generation and acknowledgement. Clean-CTX exposes both server tools; the repository does not ship an automatic host consumer.
• apply_edit - structural edits on previously-seen files.
• Structured responses - canonical CallToolResult envelope (content + structuredContent + _meta) with declared outputSchema.

Language / framework awareness

Meaningful semantic intelligence, not generic text processing:

Language	Framework intelligence
TypeScript	Angular - Components, Services, DI, Pipes, Directives, Modules, @Input/@Output, NgRx, RxJS, Signals, Routing, PrimeNG, bundle graph
C#	.NET - Controllers, Actions, Routes, EF Core, SignalR, AutoMapper, DI, validation
Java	Spring Boot - Controllers, RequestMappings, Services, Repositories, @Autowired, @ConfigurationProperties, beans
Rust	Semantic extraction for structs, enums, traits, impls

Plain files (no framework) are indexed through the BuiltinMetaLayer fallback.

Semantics-preserving compression

This is the key differentiator. Clean-CTX is not doing textual minification:

• Architectural invariant (IRPAT-001) - consumptive IR transformations must never consume a DefMethod while leaving surviving operations that reference it orphaned. The compiler validates every transformation so compression does not silently destroy relationships.
• Deterministic, validated - the IR validator (E001-E011) catches dangling references, orphaned methods/callers, and inconsistent annotations before output reaches the consumer.
• Identity survives transformation - entity identity and semantic edges persist through compression, delta transport, and edits.

Token and context efficiency

A major benefit - but a consequence of better context compilation, not the whole product:

Mechanism	What it affects
Semantic compression (Low/Medium/High/Edit/Verbatim)	61-97% smaller representations vs raw source
Delta transport	Up to 53% CPU/latency savings on repeat calls
CBM symbol filtering	Queries the separate CBM (codebase-memory-mcp) server for symbol-importance scores and filters its output before it reaches the LLM
Tool output filtering (26 filters)	Compresses build/lint/test CLI output
Prompt caching (proxy)	~90% API cost savings on repeated turns

---

How it works

Source file
    ↓
CoreIRPass → LanguageLayerPass → MetaLayerPass → PatternRecognitionPass → ValidationPass
    ↓                    ↓                ↓
Compact IR      Semantic edges      Φ markers
    ↓                    ↓
    └──── WorkspaceIndex ────┘
              ↓
    ┌─────────────────────────┐
    │  workspace_query (MCP)  │
    │  provide_code_context   │
    │  compress_code_context  │
    └─────────────────────────┘

1. Parse - tree-sitter grammars produce a concrete syntax tree.
2. Compile to IR - CoreIRPass emits a typed instruction stream; LanguageLayerPass adds behavioral annotations; MetaLayerPass extracts framework-specific semantic edges.
3. Compress - PatternRecognitionPass collapses recognized patterns into compact opcodes; ValidationPass enforces IRPAT-001 and structural validity.
4. Index - semantic edges flow into WorkspaceIndex for cross-file queries. An authoritative source refresh retracts evidence owned by sources no longer present; CBM assists discovery but does not determine semantic truth.
5. Serve - MCP tools expose context compilation and semantic queries to AI agents.

---

Quick Start

Prerequisites

• Rust 1.85+ (edition 2024)

Install

# Clone and build (release binary)
git clone https://github.com/codeliftsleep2/Clean-CTX.git
cd Clean-CTX
cargo build --release

# The binary is at: target/release/clean-ctx.exe (Windows) or target/release/clean-ctx (Linux/Mac)

Language & Feature Selection

Clean-CTX uses Cargo feature flags to control which languages and meta-layers are compiled into the binary.

Category	Feature	Implies	Includes	Build With	Default
Language	typescript	-	Base TypeScript/JavaScript grammar	--features typescript	Yes
Language	csharp	-	Base C# grammar	--features csharp	Yes
Language	rust	-	Base Rust grammar	--features rust	No
Language	java	-	Base Java grammar	--features java	No
Meta-Layer	angular	typescript	Components, Services, DI, Pipes, Directives, Modules, @Input/@Output, NgRx, RxJS, Signals, Routing, PrimeNG, template/style extraction, bundle graph	--features angular	Yes
Meta-Layer	spring_boot	java	Controllers, Services, Repositories, @Autowired, @ConfigurationProperties, beans	--features spring_boot	No
Meta-Layer	dotnet	csharp	ASP.NET Core, EF Core, SignalR, AutoMapper, DI, validation	--features dotnet	Yes

Default features give you TypeScript with Angular meta-layer, C#, and .NET enrichment - the most common full-stack combination. Everything else is opt-in:

# Default build: TypeScript + Angular + C# + .NET
cargo build --release

# TypeScript + Angular only (no C#)
cargo build --release --no-default-features --features typescript,angular

# .NET/C# only (no TypeScript, Angular)
cargo build --release --no-default-features --features csharp,dotnet

# All languages + all meta-layers
cargo build --release --features rust,java,spring_boot

Configure VS Code

Add to your MCP settings (see IDE Configuration below for all options):

{
  "mcpServers": {
    "clean-ctx": {
      "command": "C:\\path\\to\\clean-ctx.exe",
      "args": []
    }
  }
}

Restart your editor. The tools provide_code_context, compress_code_context, diff_code_context, diff_commits, delta_code_context, apply_delta, apply_edit, restore_context, context_stats, context_history, save_context, list_sessions, replay_history, purge_old_deltas, and workspace_query will be available.

---

Usage Examples

Quick context (recommended)

{
  "name": "provide_code_context",
  "arguments": {
    "filePath": "/path/to/MyService.ts"
  }
}

Every call returns complete current context. Incremental IR transport is an explicit delta_code_context / apply_delta workflow and is never selected automatically by provide_code_context.

Query the workspace semantic graph

{
  "name": "workspace_query",
  "arguments": {
    "type": "find_entities",
    "name": "UserCardComponent",
    "workspaceRoot": "/path/to/workspace"
  }
}

The tool accepts two mutually exclusive request forms: singular filePath for one file, or top-level files for 1–8 files (normally two or more). A batch keeps workspaceRoot and tokenizer at the top level; each item has a unique id, its own filePath, and optional intent, fidelity, and focusMethods. Inspect every item status. Batch-only responseMode controls where exact code is placed: prefer structured for a verified structured-result consumer, omit it for safe mirrored when host capability is unknown, or use indexed only for a verified top-level content consumer. Never guess a compact mode; response_mode reports the projection used.

{
  "name": "provide_code_context",
  "arguments": {
    "workspaceRoot": "/path/to/repo",
    "responseMode": "structured",
    "files": [
      { "id": "overview", "filePath": "src/service.ts", "intent": "overview" },
      { "id": "target", "filePath": "src/controller.ts", "intent": "edit", "focusMethods": ["Controller.update"] }
    ]
  }
}

Several independent questions sharing one workspace scope can be sent together:

{
  "name": "workspace_query",
  "arguments": {
    "workspaceRoot": "/path/to/workspace",
    "queries": [
      { "id": "entity", "type": "find_entities", "name": "UserCardComponent" },
      { "id": "callers", "type": "reverse_edges", "name": "UserCardComponent" },
      { "id": "cycles", "type": "has_cycle" }
    ]
  }
}

Batch results preserve input order and isolate failures per item. Other query types include forward_edges, entities_in_file, transitive_dependencies, and calls_in_file.

Compress a file (Low fidelity)

{
  "name": "compress_code_context",
  "arguments": {
    "filePath": "/path/to/MyService.ts",
    "fidelity": "low"
  }
}

Structural output (SCHEMA vNext):

// SCHEMA vNext  @=meta C=class X=extends I=implements F=field M=method $=import p:=params →=return mod:=method-modifiers cmod:=class-modifiers ctl:=control-summary pf:=pattern-facts fl:=legacy-flags cl:=class-metadata P=pattern T=type-alias
C SampleService
M doWork p:payload:$s[] → $b

AST-level diff (track changes over time)

{
  "name": "diff_code_context",
  "arguments": {
    "filePath": "/path/to/MyService.ts"
  }
}

View compression dashboard

{
  "name": "context_stats",
  "arguments": {}
}

---

Response Notation (SCHEMA vNext)

Structural provide_code_context, compress_code_context, and restore_context presentations start with this legend. Byte-exact raw fallbacks, Angular-template output, and delta acknowledgements use their own explicit content kinds instead.

// SCHEMA vNext  @=meta C=class X=extends I=implements F=field M=method $=import p:=params →=return mod:=method-modifiers cmod:=class-modifiers ctl:=control-summary pf:=pattern-facts fl:=legacy-flags cl:=class-metadata P=pattern T=type-alias

Symbol	Meaning
C Name	opens a class scope
cmod:	class modifiers
cl:	additional class metadata
X <Parent>	extends
I <Iface...>	implements
F name:type	field
M name	method; visible signatures distinguish overloads
p:name:type ... / → type	parameters / return type
mod:	method modifiers such as ASYNC, STATIC, or visibility
ctl: / pf:	control summary and typed pattern facts
fl:	compatibility-only legacy flags when present
$ alias module [names]	import
T alias = Type	type alias
P NAME [args]	structural pattern (CTOR, OBSERVABLE, GETTER, SETTER...)

High fidelity adds cf: (control flow), df: (reads/writes), se: (side effect), and ec: (execution context). Edit fidelity appends the selected method bodies as byte-exact source. Types render exactly as captured.

The full SCHEMA-vNext notation reference is in docs/COMPILER_IR.md.

---

IDE Configuration

All clients register the same MCP server; only the config file location differs.

Client	Config file
Cline / Roo Code	~/.vscode/extensions/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Cursor	.cursor/mcp.json (project root)
Claude Code	~/.claude/settings.json or VS Code settings.json
Continue.dev	.continue/config.json (uses a JSON array of servers)
Zed	Zed settings.json under context_servers

Standard server block (Continue.dev adapts it to its array form):

{
  "mcpServers": {
    "clean-ctx": {
      "command": "C:\\path\\to\\clean-ctx.exe",
      "args": []
    }
  }
}

---

Project Status

Metric	Status
Build	OK: cargo check clean
Linting	OK: cargo clippy --all-targets -- -D warnings - 0 warnings, 0 errors
Tests	OK: All tests passing - includes live-CBM semantic probes and a self-contained multilingual fixture suite
Languages	OK: TypeScript, C#, Rust, Java with Angular/Spring Boot/.NET meta-layers
Semantic intelligence	OK: Typed SemanticEdge/EntityRef/SemanticRelation model; 30+ relation types; WorkspaceIndex with forward/reverse traversal, selector/injection resolution, transitive deps, cycle detection
Workspace queries	OK: single or ordered failure-isolated batch calls across find_entities, forward_edges, reverse_edges, entities_in_file, transitive_dependencies, has_cycle, and calls_in_file
Transport	OK: Explicit occurrence-aware dv:2 IR generation/application with complete ordinary context reads
Pass Architecture	OK: Composable IRPass pipeline (Core → Language → Meta → Pattern* → Validation), IR validator (E001–E011), query engine, semantic delta intents
CBM Integration	OK: CBM (codebase-memory-mcp) runs as a separate local server; Clean-CTX launches it as a subprocess, indexes the repo + additional roots, captures its graph output, and filters/compresses it (filter-first) before it reaches the LLM
Persistence	OK: SQLite cross-session persistence with three-tier reliability
Proxy	OK: Multi-platform proxy (Anthropic/OpenAI/Generic) with auto-cache + tool filters
Filters	OK: 26 built-in TOML filters - cargo, npm, eslint, docker, go, and more

Unsafe code is test-only (environment-variable manipulation).

---

Documentation

Document	Audience	Content
README.md	Users	What Clean-CTX is, features, quick start, usage
CONTRIBUTING.md	Contributors	Overview, process, quick links to detailed docs
docs/CONFIGURATION.md	Users	Configuration source of truth - .clean-ctx.json schema, env vars, precedence, resource limits, persistence, heuristics, meta-layers, cache, proxy lifecycle
docs/ARCHITECTURE_OVERVIEW.md	Architects	System design, module structure, pipeline stages, design decisions
docs/DEVELOPER_DOCUMENTATION.md	Contributors	Building, testing, adding languages/tools/opcodes, code quality gates
docs/COMPILER_IR.md	Architects	Compiler IR protocol, delta state transport, wire format, phase implementation
docs/ANGULAR_META_LAYER.md	Developers	Angular Meta-Layer design, marker vocabulary, template extraction, graph
docs/ANGULAR_ECOSYSTEM_DEEPENING.md	Developers	Angular Ecosystem Deepening - RxJS/NgRx/Signals/Routing meta-layers, cross-layer graph
docs/DOTNET_META_LAYER.md	Developers	.NET/C# Meta-Layer design, marker vocabulary, ASP.NET/EF Core/SignalR
docs/EDIT_TYPE.md	Developers	Edit categorization vocabulary for delta transport annotation
docs/DIFF_COMMITS_GUIDE.md	Users	diff_commits tool usage, ref validation, security posture
docs/PROXY.md	Users	Multi-platform proxy, tool output filtering, secret scrubbing, IDE integration
docs/TROUBLESHOOTING.md	Users	Common issues, error codes, diagnostic commands
docs/PERFORMANCE.md	Architects	Benchmarks, caching, memory profile, optimization checklist
docs/SECURITY.md	Administrators	Compliance checklist, hardening, SBOM, air-gap deployment
docs/README.md	All	Documentation map: current authority, guides, and historical records
docs/changelogs/CHANGELOG.md	All	Version history with all additions, fixes, and deferrals
docs/ROADMAP.md	Contributors	Future plans, prioritized items, carry-over from audit

---

License

CC0-1.0. See LICENSE.