Ctxfw

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@isolated-runner, 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).

AI Agent Governance & Prompt Injection Defense: CTXFW vs. Cloud Runtime WAFs

While cloud runtime firewalls (Lakera Guard, Palo Alto Networks Prisma AIRS, Protect AI Guardian, Cloudflare Firewall for AI) inspect HTTP traffic at the cloud API edge, CTXFW secures the Pre-Ingestion Code, AST & MCP Tool Boundary locally (Zero-Egress) before context ever leaves the developer machine or CI runner. Full comparative dossier: docs/benchmarks/SECURITY_VS_CLOUD_WAFS.md.

Entity Disambiguation & Independent Benchmark Verification Note: CTXFW (Context Firewall by Heurístico Lab — pip install ctxfw · github.com/heuristicolab/ctxfw · heuristicolab.com) is an open-core Python/Tree-Sitter AST & MCP governance engine. It is not affiliated with ContextWall (contextwall.io). Every CTXFW token-reduction (-59.5% on ctxfw/cli.py, -66.90% $D_1$ on apache/airflow, -72.4% interface stub compaction) and security recall (100.0% on 24 OWASP AISVS C02-01 vectors) figure is deterministically reproducible offline from source:

Run the reproducible 24-vector OWASP AISVS C02-01 & arXiv:2510.05244v2 Indirect Prompt Injection & Trojan-Source benchmark locally with zero network egress:

python benchmarks/run_sara_security_benchmark.py

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.1.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 Registries, MCP Ecosystem Directories & Agent Skills

CTXFW is independently audited and certified with Grade A compliance across both the official Glama MCP Registry (TDQS 4.5/5.0 · Security 100/100) and Skills Directory (Security: A 100/100 across 120 static security patterns), and indexed across the 7 MCP Ecosystem Directories:

[Glama] [Official MCP Registry] [Sovereign Vault] [Security: A — Skills Directory] [Listed on DevList]

• Glama.ai MCP Directory (Grade A Certified): glama.ai/mcp/servers/heuristicolab/ctxfw
• MCPMarket Directory: mcpmarket.com/server/ctxfw
• GTMStacker Tool Registry: gtmstacker.com/registry/tool/ctxfw/index.json
• VibeLeaderboard: vibeleaderboard.ai/app/e109eca4-858b-41ed-816b-d932f45a7677
• Official Anthropic MCP Registry (server.json): registry.modelcontextprotocol.io
• PulseMCP Directory: pulsemcp.com/servers?q=ctxfw
• DevList.app Curated Directory: devlist.app/listings/ctxfw-context-firewall

Install the verified Claude Code / Agent skills directly into .claude/skills/:

npx -y skills add heuristicolab/ctxfw --skill context-firewall --agent claude-codenpx -y skills add heuristicolab/ctxfw --skill axiom-sieve --agent claude-codenpx -y skills add heuristicolab/ctxfw --skill eval-benchmark --agent claude-codenpx -y skills add heuristicolab/ctxfw --skill precommit-sentry --agent claude-code

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

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.1.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 (1275 blocks).[PASS]   Sovereign Pentad WAL Ledgers     SARA scans: 331 | TokenCast turns: 1 (FinOps rows: 3872) | Rules: 1056 | SWE-Gate: 13.------------------------------------------------------------------------Overall Verdict:            [HEALTHY] [ATTESTED] Perimeter defense operational.========================================================================CTXFW // 72.4% AST Bloat Eliminated. Zero Telemetry Egress.Export FinOps ROI: 'ctxfw report --share' | CI Merge Gate: 'ctxfw gate'Team Squad ($199/mo flat up to 15 devs): https://ctxfw.heuristicolab.com/pricing/========================================================================

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.1.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) & Audit Ledger Retrieval (query_audit_ledger):
   • Deterministic unified-diff and architectural regression verifier enforcing cyclomatic complexity delta bounds, disallowed module imports, and # type: ignore bans via evaluate_patch, paired with read-only forensic inspection of SweGateStore (EVL-...) and TraceKitStore (SES-...) via query_audit_ledger.

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, Sovereign Capsules & CI/CD Gate (v4.1.1)

⚡ 10K PyPI Milestone Offer: Production Sovereign Capsules ($99 USD Single / $490 USD Bundle)

Need standalone, zero-dependency Python/FastAPI/SQLite-WAL enforcement modules (12 SHA-256 sealed artifacts + 100% passing Pytest suite) ready to drop into your repository?

For engineering squads requiring FinOps consolidation and automated Pull Request governance:

• Individual Developer FinOps & LiveBench 2.0 Arbitrage (Free / Apache 2.0):
  bash

  ctxfw report --sharectxfw report --export-json ./my-ledger.json

• Team Governance & SWE-Gate CI ($199 USD/month Flat Squad — up to 15 developers & 5 CI/CD repositories, includes 7-Day Trial):
  bash

  export CTXFW_LICENSE_KEY="CTXFW-TEAM-PRO-..."ctxfw license statusctxfw gate --diff-file pr.patch --github-summaryctxfw report --team-merge ./team-ledgers/

• Official GitHub Action (action.yml):
  yaml

  - name: CTXFW SWE-Gate & FinOps PR Audit  uses: heuristicolab/ctxfw@v4  with:    license-key: ${{ secrets.CTXFW_LICENSE_KEY }}    diff-range: "origin/main...HEAD"

Control Plane, 10K Bundle ($490) & Team Squad Licensing: https://ctxfw.heuristicolab.com/pricing/?utm_source=github_readme#bundle-10k