Skip to main content
Glama

CTXFW

Deterministic Zero-Egress Prompt Injection Firewall (SARA), Polyglot AST Context Compactor, and MCP Governance Engine for AI Coding Agents.

PyPI Version Python Versions Test Suite OWASP DevSecOps Guideline License: Apache 2.0

Quickstart • How It Works • Empirical Benchmarks • MCP & CLI Reference • Architecture • Editions • Docs Index • Changelog


Quickstart

Install ctxfw (v4.2.1, Python 3.10–3.13) with zero cloud accounts or outbound telemetry:

# Core MCP server, SARA firewall, CLI & TraceKit SQLite WAL ledger
pip install ctxfw

# Or isolated CLI installation via pipx
pipx install ctxfw

# Optional: include Tree-sitter TypeScript/Go/Java grammars + local HTTP reverse proxy
pip install "ctxfw[polyglot,proxy]"

Standalone zero-Python executables for Linux, macOS, and Windows are published on GitHub Releases.

Configure Claude Code, Claude Desktop, Cursor, and Windsurf in one idempotent command (creating .bak.<timestamp> backups automatically):

# Auto-detect and wire installed IDEs
ctxfw init

# Targeted Claude setup, repository pre-commit sentry, and environment verification
ctxfw install --claude
ctxfw init --repo .
ctxfw doctor

For non-MCP agents (Aider, OpenCode Interpreter, Continue.dev), start the local loopback proxy:

ctxfw proxy --port 8765
export ANTHROPIC_BASE_URL="http://localhost:8765/v1"
export OPENAI_BASE_URL="http://localhost:8765/v1"

Related MCP server: redcon

How It Works

Autonomous coding agents suffer from three failure modes when reading unfiltered repositories and untrusted MCP tool outputs: peripheral token bloat, indirect prompt injection (IPI), and ungrounded code synthesis. ctxfw enforces a deterministic CPU perimeter before data leaves the workstation or CI runner (100% Zero-Egress):

  1. Topological AST Compaction (D0 -> D3 + TraceLite): Preserves the focal file under edit (D0) 100% byte-for-byte (AXIOM-3), strips peripheral dependencies (D1, D2) into typed interface contracts using Python ast and Tree-sitter CSTs (Python, TypeScript/JavaScript, Go, Java), emits a compact D3 symbol catalog (≤ 1,000 tokens), and compresses multi-step agent traces (TraceLite: -82.43% tokens).

  2. Pre-Ingestion MCP Security (SARA · mcp_guard · PASAC · Provenance): Screens tool observations in < 1 ms P50 across 7 languages (es, fr, de, pt, zh, ja, ko), Cyrillic/Greek/Armenian intra-token homoglyphs, Trojan-Source bidirectional Unicode escapes (U+202A–U+202E), 1..4-round percent-encoded path traversals (%XX), SHA-256 tool-schema rug-pulls, Gate 0d capability laundering, and multi-hop causal poisoning.

  3. Axiomatic Sieve, SWE-Gate & Hash-Chained Ledger: Enforces specification completeness (ACI ≥ 0.9000, ≥ 5 negative invariants, finite bounds, FSM transitions, 4-class error taxonomy), gates unified diffs on cyclomatic_delta ≤ 10 and zero # type: ignore suppressions, and seals every decision in a local SQLite WAL SHA-256 hash chain (tracekit.db).


Empirical Benchmarks

All security, OCR, and AST compaction suites are deterministically reproducible offline (network_egress_calls = 0).

1. Security, Wave 2 & Spanish Regulatory/OCR Suites (ctxfw v4.2.1)

Suite / Engine

Measured Scope

Recall / Reduction

False Positive Rate

P50 / P95 Latency

Dossier

run_sara_security_benchmark.py

24 vectors (16 adversarial OWASP AISVS C02-01 + 8 benign)

100.0% (16/16)

0.0% (0/8)

0.87 ms / 2.15 ms

Security Matrix

run_wave2_v42_benchmark.py (Block A)

mcp_guard: 5/5 rug-pull, 30 poison, 30 path confinement

100.0%

0.0%

0.051 ms / 1.267 ms

Wave 2 Dossier

run_wave2_v42_benchmark.py (Blocks B+C+D)

PASAC (5/5), TaskAuth (5/5), Cadence AIMD, TraceLite (5.692x), Snapshots

82.43% trace cut

0.0%

2.30–13.84 ms

Wave 2 Dossier

run_wave2_v42_benchmark.py (Block E)

Causal Provenance #31, Containment #04, 7-lang + homoglyphs (45 adv / 35 ben)

100.0%

0.0%

0.426 ms / 1.505 ms

Wave 2 Dossier

run_regulatory_ocr_benchmark.py (SARA-RegDoc-60)

60 Spanish regulatory/financial noisy OCR docs (30 adv / 30 benign controls)

100.0% (-62.52% OCR noise)

0.0% (0/30, down from 16.67% in v4.2.0)

6.10 ms / 8.71 ms

RegDoc-60 Report

Reproduce offline from a repository checkout:

python benchmarks/run_sara_security_benchmark.py --json
python benchmarks/run_wave2_v42_benchmark.py --json
python benchmarks/run_regulatory_ocr_benchmark.py --json

2. Topological AST Context Compaction (D0–D3)

Measured offline (0 bytes stdout JSON-RPC leak, 100% PASS via ast.parse()). Full report: Trilogy Empirical Benchmark.

Target Repository

Focal D0 Module

Raw Tokens

Pruned Tokens

Peripheral D1 / D3 Savings

Latency / Throughput

zulip/zulip

zerver/models/users.py

29,689 (D0+D1)

22,481 (D0+D1*)

-42.96% Interface · -78.20% Nominal · -74.5% D3

44.1 ms (~380k tok/s)

PostHog/posthog

posthog/models/team/team.py

34,894 (D0+D1)

22,637 (D0+D1*)

-59.53% Interface · -48.9% D3

50.2 ms (~410k tok/s)

apache/airflow

airflow/models/dag.py

69,861 (D0+D1)

29,433 (D0+D1*)

-66.90% Interface · -90.26% Nominal · -68.9% D3

138.2 ms (437,351 tok/s)

ctxfw/src (80 modules, 500 cycles)

Internal core package

6,914,785

2,044,783

-70.4% aggregate (4.87M tok/cycle)

ctxfw benchmark ./src

Cost Mechanics: Because stateless LLM APIs re-send conversation history on every turn, pruning ~72.4% of peripheral AST noise on Turn 1 yields 4.2x compounded cost savings across a 15-turn coding session (at a baseline reference of USD 3.00 per 1M tokens, roughly USD 87.70 saved per 1,000 calls on ctxfw/cli.py's dependency graph).

3. Pre-Ingestion Local Boundary vs. Cloud Runtime WAFs

Dimension

CTXFW (v4.2.1, Pre-Ingestion Local)

Cloud Runtime WAFs (Lakera, Prisma AIRS, Protect AI, Cloudflare AI)

Enforcement Point

Local AST, CLI, Git Hook, MCP stdio, loopback proxy

Cloud HTTP edge after payload assembly

Data Sovereignty

100% Zero-Egress (RAM + local SQLite WAL)

Outbound code/context transmission to third-party API

AST Token Compaction

-42.96% to -90.26% D1 bloat pruned (0% D0 loss)

0% token reduction

Latency

0.87 ms P50 (SARA) · < 0.8 ms warm WAL cache

15 ms – 150 ms network RTT + ML inference

Licensing & Packaging

Open-Core (Apache 2.0) · PyPI, 14.18 MB Windows / 24.9 MB Linux standalone EXEs

Proprietary enterprise cloud contracts

Entity Disambiguation: CTXFW (Context Firewall by Heurístico Lab) — github.com/heuristicolab/ctxfw, pypi.org/project/ctxfw, ctxfw.heuristicolab.com — is an open-core AST & MCP governance engine and is not affiliated with ContextWall (contextwall.io).


MCP Tools and CLI Reference

Exposed MCP stdio Tools (ctxfw mcp)

MCP Tool

Purpose

Key Parameters

prune_file

Prune target or dependency AST while keeping focal contracts

path, depth (full / interface / nominal), language

resolve_context_bundle

Build topological D0 -> D3 dependency context bundle

target_file, project_root

evaluate_spec_axioms

Score formal specification against ACI ≥ 0.9000 invariants

brief_text

evaluate_patch

Enforce SWE-Gate bounds on unified git diffs (ALLOW_MERGE / REJECT)

diff_text, max_cyclomatic_delta (10)

query_audit_ledger

Retrieve & verify TraceKit SHA-256 chains and EVL-* verdicts

evaluation_id, session_id

Core CLI Commands

Command

Role

ctxfw <target_file>

Compact D0 -> D3 dependency graph and copy prompt to clipboard (--no-clip --stdout)

ctxfw init [--claude | --global | --repo]

Configure Claude Code CLI, Claude Desktop, Cursor, Windsurf, or git pre-commit hook

ctxfw doctor

Verify Python runtime, stdio isolation, Tree-sitter grammars, SQLite WAL & TraceKit ledger

ctxfw mcp

Start pure JSON-RPC 2.0 MCP stdio server

ctxfw proxy [--port 8765]

Start loopback OpenAI/Anthropic reverse proxy

ctxfw gate [--diff pr.patch | --staged] [--github-summary]

Deterministic CI/CD PR gatekeeper (SWE-Gate)

ctxfw ci [--base ... --head ...]

Topological PR dependency & FinOps analyzer

ctxfw spec verify SPEC.axioms.md

Verify specification axioms, bounds, FSM, and error taxonomy (ACI ≥ 0.9000)

ctxfw trace verify

Verify append-only SHA-256 hash chain integrity across tracekit.db

ctxfw benchmark ./src [--format json]

Measure real AST token reduction and projected savings on a repository

ctxfw audit / ctxfw report / ctxfw service

Export local FinOps reports or manage background OS service

Agent Skills & Ecosystem Directories:

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

Architecture

UNTRUSTED / PROBABILISTIC DOMAIN           DETERMINISTIC LAYER-0 PERIMETER (LOCAL CPU)
+-------------------------------+          +--------------------------------------------------+
| Autonomous AI Coding Agent    |          | CTXFW ENGINE (Zero-Egress / Offline-Ready)       |
| Claude / Gemini / Cursor / CI |          |  1. LexicalSanitizer + SARA + mcp_guard + PASAC  |
+---------------+---------------+          |  2. Polyglot AST Compactor (D0 -> D3) + TraceLite|
                |                          |  3. Axiomatic Sieve (ACI >= 0.90) & SWE-Gate     |
                v                          |  4. TraceKit Append-Only SHA-256 SQLite WAL      |
+-------------------------------+          +-------------------+--------------------+---------+
| MCP stdio / Loopback Proxy    |----------------------------->|                    |
+-------------------------------+                              v                    v
                                                        [ VERIFIED ]         [ QUARANTINED ]
                                                     Allow & Hash Seal    Strip / Execution Halt

See the full User Manual and formal invariants in SPEC.axioms.md.


Editions and Enterprise

The entire single-developer CLI, 5-tool MCP server, SARA firewall, SWE-Gate, and TraceKit engine remain 100% open-source under Apache 2.0. Commercial editions fund multi-developer governance and enterprise infrastructure:

Edition

Scope

Reference

Community Open-Core (Apache 2.0)

Full 5-tool MCP stdio server, D0 -> D3 AST pruner, SARA, PASAC, SWE-Gate, local SQLite WAL audit ledger, standalone CLI binaries

Free · pip install ctxfw

Team Governance & CI Gate

Automated squad PR gates (ctxfw gate --github-summary), SHA-256 team FinOps rollup (ctxfw report --team-merge), unified policies

Pricing & Squad Plans

CTXFW Enterprise (Custom VPC / Air-Gapped)

Multi-vault /mcp/<vault_slug> isolation, federated JWKS/Ed25519, PostgreSQL/Redis HA, .sont cartridges, SIEM/NOM-151, Red Hat UBI9

Enterprise Inquiries

Official GitHub Action

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

Documentation & Governance

Available Tools

5 tools
evaluate_patchA

Verify a unified git diff patch (diff_text, with optional commit_sha, author_kind 'AGENT'|'HUMAN', pr_id, diff_size_bytes, repo_name, and repo_id) against SWE-Gate architectural constraints (max_cyclomatic_delta default 10, forbid_type_ignores default true, disallowed_import_modules) and functional test results (tests_passed default 1, tests_failed default 0, functional_verdict 'PASSED'|'FAILED') before allowing merge. Appends immutable audit records (EVL-...) in SweGateStore and seals cryptographic blocks in TraceKitStore; use query_audit_ledger to retrieve or verify persisted records.

Inputs: diff_text (required), pr_id, repo_id, repo_name, +9 more. Returns: content, isError

evaluate_spec_axiomsA
Read-onlyIdempotent

Evaluate an architectural specification brief (brief_text) against formal determinism rules, requiring at least 5 explicit negative invariants ('never' or 'shall never'), bounded variable domains, deterministic finite-state machine (FSM) transitions, and a 4-class error taxonomy to reach VERIFIED status (aci_score >= 0.9000 and SHA-256 manifest_hash; otherwise QUARANTINED with remediation notes). Use this during intake or planning phases before writing code; for verifying unified git diff patches, use evaluate_patch instead.

Inputs: brief_text (required). Returns: content, isError

prune_fileA
Read-onlyIdempotent

Extract semantic interfaces, types, pydantic models, sanitized raises, and signatures from a source file (path) at a given pruning depth ('full' retains full AST with sanitized raises, 'interface' replaces procedural bodies with ... stubs [default], or 'nominal' retains top-level symbol declarations only) and language ('python' [default], 'typescript', 'javascript', 'go', 'java'), optionally stripping docstrings (strip_docs, default false). Use this when you only need to inspect contracts or APIs of an individual dependency without ingesting raw implementation code; for multi-module dependency graphs, use resolve_context_bundle instead.

Inputs: path (required), depth, language, strip_docs. Returns: content, isError

query_audit_ledgerA
Read-onlyIdempotent

Retrieve persisted SWE-Gate patch evaluation records and violation findings by evaluation_id (EVL-<16 lowercase hex chars>), or verify cryptographic SHA-256 hash-chained audit sessions in TraceKitStore by session_id (SES-...) with optional block pagination (include_blocks default true, max_blocks 1..256 default 50); at least one of evaluation_id or session_id must be provided. Use this for forensic inspection and compliance verification after running evaluate_patch or context tools.

Inputs: max_blocks, session_id, evaluation_id, include_blocks. Returns: content, isError

resolve_context_bundleA
Read-onlyIdempotent

Calculate topological dependency graph distances (D0 full target_file, D1 interface stubs, D2 nominal symbols) within project_root (defaults to target_file's parent directory) and compile a token-pruned Markdown context bundle, with optional reactive degradation via breaker_state ('CLOSED', 'TRIPPED' strips D2+ modules, or 'HALTED' compacts D1 to nominal stubs) and session_id ('SES-...' linked to TokenCast budget tracking). Use this as your primary context builder before editing a file in a multi-module project; for inspecting isolated files, use prune_file instead.

Inputs: target_file (required), session_id, project_root, breaker_state. Returns: content, isError

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: single-file pruning, multi-module bundle compilation, spec evaluation, patch evaluation, and audit retrieval. Descriptions explicitly disambiguate boundaries, e.g. prune_file says 'for multi-module dependency graphs, use resolve_context_bundle instead' and evaluate_spec_axioms points to evaluate_patch for diffs.

    Naming Consistency5/5

    All five tools use snake_case with a leading verb (prune_file, resolve_context_bundle, evaluate_spec_axioms, evaluate_patch, query_audit_ledger). The verb_noun pattern is predictable and the two evaluate_* tools share a consistent prefix for their judgment family.

    Tool Count5/5

    Five tools is well-scoped for a context-bundling and verification framework: two for context generation, two for evaluation gates, one for audit. No tool looks redundant and none of the sub-capabilities appear padded.

    Completeness4/5

    The prune/bundle, spec-evaluate, patch-evaluate, and audit-query lifecycle forms a coherent closed loop, but session management is an implicit dependency: session_id (SES-...) is consumed as input with no tool to create or list sessions, and TokenCast budget state is referenced but never exposed.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Deterministic repository context packing for AI coding agents: selects, compresses, and budgets only the files a task needs. Measured 83% fewer input tokens at the same task coverage, fully local, no LLM in the loop.
      9
      24 PyPI
      9
      Functional Source , Version 1.1, MIT Future
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI coding agents to reduce token usage by condensing source code into AST skeletons, extracting specific symbols, compressing logs, and estimating token budgets.
      4
      MIT