Executive Abstract

Autonomous coding agents (Claude, Gemini, Cursor, Antigravity) consume massive context windows with bloated peripheral dependencies, triggering token exhaustion, context drift, and security degradation.

CTXFW is an open-core context firewall and Model Context Protocol (MCP) gatekeeper. It combines an in-memory polyglot AST pruner with a deterministic axiomatic intake sieve:

1. Compacts Peripheral Code (72.4% token reduction): Replaces distance-1 and distance-2+ module implementations with clean interface signatures, type definitions, and functional stubs.
2. Enforces Axiomatic Integrity (ACI $\ge$ 0.9000): Rejects ungrounded or deficient architecture briefs missing negative invariants ($N \ge 5$), bounded variable domains, deterministic state machines, or formal error taxonomies.
3. Zero Telemetry Egress: Guaranteed local execution with zero network telemetry leakage on standard operating mode.

AST Pruning Benchmarks

CTXFW operates directly at the syntax tree layer using native polyglot grammars:

Empirical Case Study: ctxfw/cli.py Core Dependency Graph

Empirical context reduction metrics generated via ctxfw.resolve_context_bundle running against 16 internal dependencies:

Topological Hierarchy Breakdown:

• $D_0$ Target (ctxfw/cli.py): 100% Full Implementation preserved.
• $D_1$ Direct Deps (e.g. gatekeeper.py, mcp.py): Implementation truncated to typed stubs (...). Token savings: 73% – 86%.
• $D_2$ Transitive Deps (e.g. polyglot.py): Compact typed interface signatures. Token savings: 91.9%.
• $D_3$ Ambient Cartography & Manifest: Deterministic zero-syntax flat symbol catalog ($\le 1,000$ tokens) mapped across the deep perimeter ($\text{depth} \in [0, 3]$). Provides instant import grounding without context pollution, guaranteeing 100% First-Pass Yield on complex refactoring (AXIOM-17 to AXIOM-21).

The Empirical Validation Trilogy (Multi-Repository Destructive A/B)

Audited on remote Linux environments (root@217.21.78.30, Ubuntu 24.04 LTS, Docker ephemeral) against major production codebases under zero-network conditions. Full forensic dossier: docs/benchmarks/TRILOGY_EMPIRICAL_BENCHMARK.md.

Key Empirical Highlights:

• Compression Scaling ($43% \to 60% \to 67%$): Larger real-world codebases yield greater perimeter reduction ($60.4\text{k} \to 20.0\text{k}$ tokens in Airflow D1, eliminating 40,428 bloat tokens net).
• Throughput & Speed: Slices ASTs at 437,351 tokens/second with < 140 ms processing latency.
• Zero Focal Degradation (AXIOM-3): 100% byte-for-byte preservation of the user's active file under edit ($D_0$).
• Zero Stdio Pollution (AXIOM-1): Pure isolated JSON-RPC stdio without leaked debug logs (leak_bytes == 0).

Installation & Multi-Surface Setup

1. PyPI Installation

pip install --upgrade ctxfw
# or via pipx for dedicated binary isolation:
pipx install ctxfw

2. Multi-Surface MCP Auto-Configuration (v4.0.0)

Run ctxfw init or dedicated installation command ctxfw install --claude for automated zero-touch discovery and idempotent injection across your installed coding surfaces:

# Targeted Claude Code CLI & Claude Desktop auto-installation:
ctxfw install --claude

# Or full multi-surface discovery (Claude, Cursor, Windsurf):
ctxfw init

Auto-Detected Surfaces (Triple Surface Architecture):

1. Claude Code CLI: Injects directly into ~/.claude.json.
2. Claude Desktop: Dynamic cross-platform detection:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
   • Linux / POSIX: ~/.config/Claude/claude_desktop_config.json
3. Cursor IDE: Injects into .cursor/mcp.json in workspace scope.
4. Windsurf IDE: Injects into ~/.codeium/windsurf/mcp_config.json when the .codeium directory signature is present.

Inviolable Safety & Reliability Invariants:

• Atomic Backup Snapshot (.bak.<timestamp>): Before mutating any pre-existing configuration file, creates a timestamped immutable backup.
• Non-Destructive Merge: Preserves 100% of pre-existing third-party MCP servers, top-level settings, and custom keys.
• Zero-Failure Execution: Dynamically resolves the interpreter to sys.executable with ["-m", "ctxfw.mcp"] (or canonical absolute binary path if frozen via PyInstaller), completely eliminating ambient $PATH and virtualenv resolution failures.
• 3x Idempotency: Multiple runs produce zero configuration drift and zero duplicated keys.

3. Zero-MCP Interoperability Gateway (Aider, OpenCode, Continue, CLI)

For AI developer tools and terminal agents lacking native Model Context Protocol support:

# 1. Start the zero-egress local proxy server:
ctxfw proxy --port 8765

# 2. Point your tool's Anthropic or OpenAI endpoint to localhost:
export ANTHROPIC_BASE_URL="http://localhost:8765/v1"
export OPENAI_BASE_URL="http://localhost:8765/v1"

4. Verified MCP Registry (Glama)

CTXFW is indexed and verified with Grade A compliance on the official Glama MCP registry:

Direct access to tool inspection, schemas, and live diagnostic telemetry on Glama.

System Diagnostics

Validate local environment readiness, stdio isolation purity, SQLite WAL concurrency, and Tree-Sitter grammars with a single command:

ctxfw doctor

========================================================================
  CTXFW DOCTOR // HIGH-ASSURANCE HEALTH & ISOLATION DIAGNOSTIC
========================================================================
[PASS]   Python Package & sys.path        ctxfw v4.0.0 loaded cleanly.
[PASS]   MCP stdio Stream Isolation       100% pure JSON-RPC on stdout. Diagnostic logs isolated to stderr.
[PASS]   Global CLI Executable (PATH)     Binary 'ctxfw' found in PATH.
[PASS]   Axiomatic Sieve Engine           Evaluation verified (ACI: 1.0000, Invariants: 5).
[PASS]   SQLite WAL Cache & Concurrency   Journal mode: WAL, Busy timeout: 5000ms.
[PASS]   Polyglot Tree-Sitter Grammars    Initialized language parsers (typescript, go, java).
[PASS]   TraceKit Ledger Audit            Chain status: INTACT. Anchor hash: 57372398d453b7e4...
------------------------------------------------------------------------
Overall Verdict:            [HEALTHY] [ATTESTED] Perimeter defense operational.
========================================================================
CTXFW // 72.4% AST Bloat Eliminated. Zero Telemetry Egress.
Need team-wide budget circuit breakers or multi-node proxy governance?
Control Plane & Enterprise Licensing: https://ctxfw.heuristicolab.com
========================================================================

Architecture

CTXFW enforces a strict deterministic perimeter dividing probabilistic agent code from the core codebase:

PROBABILISTIC DOMAIN                      DETERMINISTIC PERIMETER
┌───────────────────────┐                  ┌────────────────────────────────────────┐
│  Autonomous AI Agent  │                  │             CTXFW ENGINE               │
│  (Claude / Gemini /   │                  │                                        │
│   Cursor / Antigravity│                  │  ┌──────────────────────────────────┐  │
└───────────┬───────────┘                  │  │   Polyglot AST Topological Engine│  │
            │                              │  │  - Python (ast)                  │  │
            │  Target Context / Brief      │  │  - TypeScript / Go / Java (CST)  │  │
            ▼                              │  │  - Multi-Depth Interface Stubs   │  │
┌───────────────────────┐                  │  └────────────────┬─────────────────┘  │
│ MCP Stdio Interceptor ├─────────────────►│                   │                    │
└───────────────────────┘                  │  ┌────────────────┴─────────────────┐  │
                                           │  │  SQLite WAL High-Concurrency     │  │
                                           │  │  Semantic Cache (<5ms warm hit)  │  │
                                           │  └────────────────┬─────────────────┘  │
                                           │                   ▼                    │
                                           │         [ ACI >= 0.9000? ]             │
                                           │          /              \              │
                                           │       YES                NO            │
                                           │        │                  │            │
                                           │        ▼                  ▼            │
                                           │ ┌──────────────┐   ┌─────────────────┐ │
                                           │ │ VERIFIED     │   │ QUARANTINED     │ │
                                           │ │ SHA-256 Seal │   │ Execution Halt  │ │
                                           │ └──────┬───────┘   └────────┬────────┘ │
                                           └────────┼────────────────────┼──────────┘
                                                    │                    │
                                                    ▼                    ▼
                                           [ Code Generation ]   [ Forensic Report ]
                                           [ & Git Permitted ]   [ Pre-Commit Abort]

Key Subsystems (v4.0.0 Sovereign Pentad):

1. Polyglot Tree-Sitter Pruner & $D_3$ Ambient Cartography:
   • Compiles topological dependency trees ($D_0$ full, $D_1$ interface, $D_2$ nominal, $D_3$ flat symbol catalog $\le 1,000$ tokens) across Python, TypeScript/JavaScript, Go, and Java.
2. TraceKit Cryptographic Ledger (ctxfw.audit):
   • Append-only 283-byte canonical SHA-256 hash-chained audit ledger (tracekit.db) with tamper latch verification via ctxfw trace verify.
3. TokenCast Integer Forecaster & Circuit Breaker (ctxfw.budget):
   • Zero-float integer trajectory predictor and reactive circuit breaker (CLOSED $\to$ TRIPPED / FORCE_D3_PRUNING $\to$ HALTED / EMERGENCY_HALT).
4. Normative Rules Compiler & Enforcer (ctxfw.rules):
   • Compiles .cursorrules and CLAUDE.md negative directives into deterministic AST/path/command/import guards with 3-round iterative path-traversal normalization.
5. SARA Agent Induction Firewall (ctxfw.sara):
   • Inspects untrusted tool observations for indirect prompt injection, role overrides (<system>, [INST]), and Trojan-Source bidi escapes (ALLOW, STRIP_COMMANDS, QUARANTINE_TOOL).
6. SWE-Gate CI Verifier (ctxfw.swegate):
   • Deterministic unified-diff and architectural regression verifier enforcing cyclomatic complexity delta bounds, disallowed module imports, and # type: ignore bans via evaluate_patch.

Zero-Touch Provisioning

Inject perimeter rules, MCP server declarations, and pre-commit sentinels into your workspace:

Global IDE Integration

ctxfw init --global

Automatically configures Google Antigravity, Cursor, and Claude Desktop.

Repository Pre-Commit Sentry

ctxfw init --repo .

Deploys .git/hooks/pre-commit to prevent uncertified code commits lacking an attested specification brief.

Enterprise Governance

For distributed engineering teams requiring centralized policy controls:

• Team-wide LLM budget circuit breakers: Hard token and dollar thresholds with automatic killswitches.
• Multi-node reverse proxy governance: Centralized firewall gateways supporting OpenAI and Anthropic streaming SSE endpoints.
• FinOps Telemetry Ledger: Aggregate tokens saved, cost elusion analytics, and tamper-evident audit trails.

Control Plane & Enterprise Licensing: https://ctxfw.heuristicolab.com