ctxwise MCP server

CtxWise

💡 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!

---

⚡ 30-Second Quickstart

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

---

📊 Before vs. After CtxWise

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)

---

🏗️ How It Works

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"]

---

🔥 Core Features

1. 🌳 MCP Schema Tree-Shaking (mcp-xray)

Discover all MCP servers declared across .mcp.json, ~/.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.

2. 🔄 Multi-Agent Context Audit & "Token Diet" Sync (agents & sync)

Keep Claude Code (CLAUDE.md, .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:

npx @framy2/ctxwise agents
npx @framy2/ctxwise sync --compress --cursor

3. 🛡️ Context Security Shield (shield)

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.

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

4. 📦 Curated Stack Presets (preset)

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

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)

---

🤖 GitHub Action (CI Guard)

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"

---

🧩 Companion Tools / Ecosystem

• 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 (@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: 100% client-side web app to measure per-turn MCP schema tax, 50-turn session cost across Claude Opus 4.7 / Sonnet 4.6 / GPT-6.1-Sol / GPT-6-Luna, Codex 32 KiB truncation status, and leaked secrets.
• ctxwise-vscode (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.

---

🎥 20-Second Live Demo & Benchmarks

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 or inspect the machine-readable summary.

---

🧰 Full CLI Reference

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 estimated known context against CLI or YAML limits; exits 2 on violation 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

---

🤝 Contribute a Stack Preset in 5 Minutes

Want to make your first open-source contribution to an AI developer tool? Adding a new stack preset in presets/ takes less than 5 minutes (just 1 YAML file, validated automatically by npm test):

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

See CONTRIBUTING.md for the 3-step guide!

---

Cost Honesty by Design

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, Cost semantics, and Privacy and security.

License

Apache-2.0. See LICENSE and NOTICE.

---