# Show HN: CtxWise – Stop 8MB MCP crashes, schema bloat, and cache misses

> Source: <https://github.com/FramY2/ctxwise>
> Published: 2026-11-13 18:12:50+00:00

**Stop burning 30,000+ startup tokens on bloated MCP tool schemas, diverging `CLAUDE.md` / `AGENTS.md` files, and hidden prompt leaks.**

  The local-first AI Context Firewall, MCP Schema Tree-Shaker, and Token Profiler for **Claude Code**, **OpenAI Codex**, and **Cursor**.

[**⚡ 30s Quickstart**](#30-second-quickstart) ·
  [**📊 Before vs. After**](#before-vs-after-ctxwise) ·
  [**🌳 MCP Tree-Shaker**](#mcp-schema-tree-shaking) ·
  [**🛡️ Security Shield**](#context-security-shield) ·
  [**🤖 GitHub Action**](#github-action-ci-guard) ·
  **🤝 5-Min PRs**

**💡 Using Claude Code, OpenAI Codex, or Cursor?** Drop a **⭐ Star** on GitHub so you can find CtxWise whenever your MCP servers or `CLAUDE.md` / `AGENTS.md` files start bloating your context window!

Zero config, zero API keys, zero model calls. Run directly with `npx` in any repository:

```
# 1. Profile MCP servers & find bloated tool schemas silently eating your context window
npx @framy2/ctxwise mcp-xray --probe-stdio

# 2. Audit startup tokens & parity across Claude Code (CLAUDE.md), Codex (AGENTS.md), and Cursor
npx @framy2/ctxwise agents

# 3. Scan context files & skills for leaked API keys, prompt injection, and hidden Trojan Unicode
npx @framy2/ctxwise shield --fail-on-risk

# 4. Sync CLAUDE.md <-> AGENTS.md <-> Cursor rules and apply lossless Token Diet compression
npx @framy2/ctxwise sync --compress --cursor
```

Modern coding agents (**Claude Code**, **OpenAI Codex CLI**, **Cursor**) load `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, skill catalogs, and **every connected MCP server's JSON schema** on every turn:

| Problem Surface | ❌ Without CtxWise | ✅ With CtxWise v1.0 | 
|---|---|---|
| **Idle MCP Tool Schemas** | 4–5 MCP servers silently burn **15,000–35,000 tokens/turn** | `ctxwise mcp-xray` ranks every tool schema & flags`[BLOATED]` tools | 
| **Multi-Agent Rule Drift** | `CLAUDE.md` ,`AGENTS.md` , and`.cursor/rules` diverge fast | `ctxwise sync --compress` keeps all 3 synced + strips 25–40% boilerplate | 
| **Leaked API Keys in Context** | `sk-ant-*` ,`sk-proj-*` ,`ghp_*` inside`.mcp.json` or skills | `ctxwise shield` blocks secrets before they enter git or model prompts | 
| **Prompt Injection & Trojan Source** | Hidden `<!-- curl ... -->` comments or zero-width Unicode | `ctxwise shield --fail-on-risk` fails CI (`exit 2` ) in`<20ms` | 
| **Measured Prompt Overhead** | Unbounded context growth across PRs | **-73.3% model-visible prompt** &**-29.1% turn tokens** (20/20 pass) | 

```
flowchart LR
    subgraph Sources["Active Agent Context Surface"]
        C["Claude Code\nCLAUDE.md · .mcp.json · .claude/skills"]
        O["OpenAI Codex\nAGENTS.md · config.toml · .codex/skills"]
        U["Cursor\n.cursorrules · .cursor/rules/*.mdc"]
    end

    subgraph Engine["CtxWise Local Engine (0 API Calls · <50ms)"]
        A["ctxwise agents & sync\nCross-Agent Parity + Token Diet"]
        M["ctxwise mcp-xray\nMCP Tool Schema Tree-Shaker"]
        S["ctxwise shield\nSecret & Prompt-Injection Firewall"]
        B["ctxwise budget & drift\nDeterministic Lock & CI Gate"]
    end

    Sources --> Engine
    Engine --> Out1["Lean, Synced Context\n(-29% to -73% Token Overhead)"]
    Engine --> Out2["GitHub Action CI Gate\nuses: FramY2/ctxwise@v1"]
```

Discover all MCP servers declared across `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json` (VS Code's top-level `"servers"` key), `~/.claude.json`, and `~/.codex/config.toml`. Measure exact token weights per tool schema (from a saved `tools/list` JSON file or by probing local stdio servers live) and spot `[BLOATED]` tools (`>= 250` tokens or `>= 12` input properties):

```
npx @framy2/ctxwise mcp-xray --probe-stdio
CtxWise mcp-xray · 3 MCP servers declared · 18 tool schemas analyzed · ~6,420 schema tokens (estimated)

Heaviest MCP tool schemas:
- ~890 tokens · github/create_or_update_pull_request (16 params, 3,560 chars) [BLOATED]
- ~640 tokens · postgres/execute_migration_plan (14 params, 2,560 chars) [BLOATED]

Tree-shaking potential: ~1,530 tokens/turn savable by pruning bloated tools.
```

Keep **Claude Code** (`CLAUDE.md`, `.claude/rules/`, `.claude/skills`, `.claude/commands`, `.mcp.json`), **OpenAI Codex** (` AGENTS.md`, `.codex/skills`), and **Cursor** (`.cursor/rules/*.mdc`) 100% aligned while stripping markdown bloat (HTML comments, duplicate bullet rules, blank padding) without touching fenced code blocks. In CI, `ctxwise agents --fail-on-divergence` exits `1` when `CLAUDE.md` and `AGENTS.md` drift apart:

```
npx @framy2/ctxwise agents
npx @framy2/ctxwise agents --fail-on-divergence
npx @framy2/ctxwise sync --compress --cursor
```

Protect your repository before an agent reads your workspace or before a PR merges:

- **Secret Exposure Detection:** Catches hardcoded Anthropic (`sk-ant-...` ), OpenAI (`sk-proj-...` ), GitHub (`ghp_...` ), AWS (`AKIA...` ), and private key blocks inside`CLAUDE.md` ,`AGENTS.md` ,`.mcp.json` , and skills.
- **Prompt Injection & Trojan Unicode Guard:** Detects override directives (`ignore all previous instructions` ), covert HTML comment payloads (`<!-- curl ... -->` ), and hidden bidirectional/zero-width Unicode characters.
- **Claude Settings Hygiene & SARIF 2.1.0 Output:** Flags misplaced`"mcpServers"` blocks inside`.claude/settings.json` (`anthropics/claude-code#105885` ) and emits SARIF 2.1.0 (`--sarif ctxwise.sarif` ) for GitHub Code Scanning.
- **Unpinned MCP Launchers (`unpinned-mcp-exec`):** Flags MCP servers that run an unpinned or`@latest` package through`npx` /`uvx` style launchers, so a compromised upstream release cannot silently enter your agent's tool surface.

```
npx @framy2/ctxwise shield --fail-on-risk --sarif ctxwise.sarif
```

Bootstrap a reviewable token budget (`ctxwise.budget.yaml`) and lean starter `AGENTS.md` + `CLAUDE.md` files tailored to your stack in one command:

```
npx @framy2/ctxwise preset
npx @framy2/ctxwise preset nextjs-typescript --with-guidance
npx @framy2/ctxwise budget --fail-on-exceed   # auto-loads ./ctxwise.budget.yaml
```

`ctxwise budget` covers Claude Code, Codex, and Cursor startup files. By default (`--agent all`) the limit applies to the heaviest single agent session, so a synced `CLAUDE.md` + `AGENTS.md` pair is never double-counted; use `--agent codex|claude|cursor` to budget one agent.

Built-in presets include:

- `nextjs-typescript` (Next.js + TypeScript + Tailwind)
- `sveltekit` /`sveltekit-typescript` (SvelteKit 2 + Svelte 5 Runes + TypeScript)
- `python-fastapi` (Python 3.12 + FastAPI + Pydantic v2)
- `rust-cargo` (Rust + Cargo Workspace)
- `go-microservice` (Go 1.23+ Service)
- `mcp-server-dev` (Model Context Protocol Server)
- `monorepo-turbo` (Turborepo / pnpm Monorepo)

Add **CtxWise** to `.github/workflows/ci.yml` in 5 lines to automatically block secret leaks, prompt injection, and context token bloat on every Pull Request:

```
- name: AI Context Firewall & Token Budget Guard
  uses: FramY2/ctxwise@v1
  with:
    max-known-tokens: "4000"
    fail-on-secrets: "true"
    check-agent-parity: "true"
    sarif-file: "ctxwise-shield.sarif"
```

When `./ctxwise.budget.yaml` exists (or `budget-policy` points at a policy file), the Action uses it instead of `max-known-tokens`. `check-agent-parity: "true"` runs `ctxwise agents --fail-on-divergence`, and every run appends a Markdown report (shield status, per-agent token breakdown, budget status) to the job summary.

CtxWise ships a native Claude Code plugin manifest (`.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json`) that installs the `ctxwise` skill:

```
/plugin marketplace add FramY2/ctxwise
/plugin install ctxwise@ctxwise
```

- **[`FramY2/mcp-diet`](https://github.com/FramY2/mcp-diet) (`@framy2/mcp-diet`)** : Zero-dependency stdio MCP proxy & runtime firewall — deterministic`tools/list` tree-shaking (`--allow` ,`--deny` ,`--read-only` ,`--max-desc` ), oversized`tools/call` crash guard (`--max-result-kb` for`anthropics/claude-code#105703` ), and live credential redaction (`--redact-secrets` ).
- **[`FramY2/agent-wire-tap`](https://github.com/FramY2/agent-wire-tap) (`@framy2/agent-wire-tap`)** : Zero-cost local loopback HTTP interceptor & CI contract tester for coding agents (`codex` ,`claude` ) — captures exact outbound wire payloads and verifies system prompt, tool count, and byte budget contracts with**$0.00 API cost** .
- **[Interactive Context & MCP Token Tax Calculator](https://framy2.github.io/ctxwise/)** : 100% client-side web app to measure per-turn MCP schema tax, 50-turn session cost across Claude Opus 4.7 / Opus 5.5 / Sonnet 5.5 / GPT-6.1-Sol / GPT-6-Luna (2026-11-11 list prices), Codex`32 KiB` truncation status, and leaked secrets. Accepts`.mcp.json` and`.vscode/mcp.json` .
- **[`ctxwise-vscode` (`editors/vscode`)](https://github.com/FramY2/ctxwise/blob/main/editors/vscode)** : Lightweight VS Code & Cursor status-bar extension displaying live workspace token tax, Context Grade (`A` –`F` ), Codex`32 KiB` cap percentage, and secret alerts.

The public microbenchmark ran 10 paired tasks across requested GPT-5.6 Luna, Terra, and Sol profiles: **20/20 answers passed the same exact validator**. Removing irrelevant discovered context reduced the estimated model-visible prompt by **73.3%** and exact aggregate turn tokens by **29.1%** (with a second maintainer repeat measuring **28.5%** across nine comparable pairs).

Read the [method and limitations](https://github.com/FramY2/ctxwise/blob/main/benchmarks/results/2026-08-09-v1/report.md) or inspect the [machine-readable summary](https://github.com/FramY2/ctxwise/blob/main/benchmarks/results/2026-08-09-v1/summary.json).

| Command | What it does | Network / Model Call | 
|---|---|---|
| `ctxwise agents` | Audits startup tokens and parity across **Claude Code** ,**OpenAI Codex** , and**Cursor** | None | 
| `ctxwise sync` | Synchronizes `AGENTS.md` ↔`CLAUDE.md` ↔`.cursor/rules` with optional`--compress` Token Diet | None | 
| `ctxwise codex-doctor` | Audits `AGENTS.override.md` /`AGENTS.md` hierarchy against Codex's`32 KiB` truncation limit | None | 
| `ctxwise mcp-xray` | Profiles MCP server tool-schema token weights and flags bloated tools for tree-shaking | None (or local stdio probe) | 
| `ctxwise mcp-prune` | Disables bloated or unused MCP servers in `.mcp.json` /`.codex/config.toml` with`.bak` save | None (or local stdio probe) | 
| `ctxwise shield` | Scans agent context files & skills for leaked API keys, prompt injection, and hidden Unicode | None | 
| `ctxwise preset` | Lists or applies curated stack budgets and `AGENTS.md` /`CLAUDE.md` templates | None | 
| `ctxwise snapshot` | Ranks known Codex context contributors, coverage gaps, and safe next actions | None | 
| `ctxwise budget` | Checks Claude Code / Codex / Cursor startup context against CLI or YAML limits (auto-loads `ctxwise.budget.yaml` ); exits`2` in CI | None | 
| `ctxwise audit` | Inventories config plus active root-to-CWD guidance, skills, plugins, agents, and MCPs | None | 
| `ctxwise map` | Renders a bounded Mermaid map of context sources and discovery overhead | None | 
| `ctxwise xray` | Summarizes model-visible prompt JSON without echoing its text | None | 
| `ctxwise profile` | Compiles YAML into native `~/.codex/<name>.config.toml` , with dry-run and backups | None | 
| `ctxwise lock` | Hashes a redacted capability surface ( `ctxwise.lock.json` ) for reproducibility | None | 
| `ctxwise drift` | Compares a capability lock with a file or live setup; can fail CI on drift | None | 
| `ctxwise quota` | Reads the current plan and quota window through local Codex app-server | Codex account read only | 
| `ctxwise receipt` | Calculates an honest receipt from saved `codex exec --json` usage | None | 
| `ctxwise run` | Runs Codex and appends exact usage plus an optional pre-turn prompt X-Ray | Requested Codex turn | 

New to profiles? Follow the [lean-profile walkthrough](https://github.com/FramY2/ctxwise/blob/main/docs/tutorials/lean-profile.md): it turns a real `audit` finding into a reviewable lean profile, end to end.

Want to make your first open-source contribution to an AI developer tool? Adding a new stack preset in [`presets/`](https://github.com/FramY2/ctxwise/blob/main/presets) takes **less than 5 minutes** (just 1 YAML file, validated automatically by `npm test`):

- 🟢 [**Issue #23**](https://github.com/FramY2/ctxwise/issues/23) — Add`sveltekit-typescript` preset (SvelteKit 2 + Svelte 5 Runes)
- 🟢 [**Issue #24**](https://github.com/FramY2/ctxwise/issues/24) — Add`astro-content` preset (Astro 5 + Content Layer)
- 🟢 [**Issue #25**](https://github.com/FramY2/ctxwise/issues/25) — Add`django-ninja` preset (Python + Django 5 + Django Ninja)
- 🟢 [**Issue #26**](https://github.com/FramY2/ctxwise/issues/26) — Add`laravel-inertia` preset (Laravel 11 + Inertia.js + PHP 8.3)
- 🟢 [**Issue #27**](https://github.com/FramY2/ctxwise/issues/27) — Add`kotlin-spring-boot` preset (Kotlin + Spring Boot 3)
- 🟢 [**Issue #28**](https://github.com/FramY2/ctxwise/issues/28) — Add`cloudflare-workers-hono` preset (Cloudflare Workers + Hono)

See [`CONTRIBUTING.md`](https://github.com/FramY2/ctxwise/blob/main/CONTRIBUTING.md) for the 3-step guide!

| Authentication | Default display | Dollar meaning | 
|---|---|---|
| OpenAI API key | Exact runtime tokens + dated API estimate | Estimated billable API charge | 
| ChatGPT Plus/Pro/Business | Tokens + credit equivalent + quota snapshot | No dollar amount | 
| Subscription with `--api-equivalent` | Same data + API comparison | Comparison only; **not charged** | 

See [Architecture](https://github.com/FramY2/ctxwise/blob/main/docs/architecture.md), [Cost semantics](https://github.com/FramY2/ctxwise/blob/main/docs/cost-semantics.md), and [Privacy and security](https://github.com/FramY2/ctxwise/blob/main/docs/privacy-security.md).

Apache-2.0. See [LICENSE](https://github.com/FramY2/ctxwise/blob/main/LICENSE) and [NOTICE](https://github.com/FramY2/ctxwise/blob/main/NOTICE).

**If CtxWise saved you tokens or caught a bloated MCP schema, please give the repo a ⭐ Star on GitHub!**

[⭐ Star FramY2/ctxwise on GitHub](https://github.com/FramY2/ctxwise/stargazers)