ctxcap

ctxcap

Offline token-budget linter for agent context files. It measures CLAUDE.md, AGENTS.md, prompts/**, and .cursor/rules/**, finds references that no longer resolve, and hands your agent a ranked, verifiable plan to get back under budget.

No config, API key, network, or telemetry. Node >= 20. Two runtime dependencies: fast-glob and gpt-tokenizer.

npx ctxcap --json

The loop

Context files get trimmed by agents badly: the agent rewrites the file from memory, drops the ## Never rules, hits the budget, and ships a worse file. ctxcap closes that loop with line ranges, safety flags, and verification.

npx ctxcap --plan --budget 40000              # ranked plan, JSON

npx ctxcap --plan --budget 40000 --apply # splice atomically npx ctxcap --verify # catch drift and violations

Three rules for the agent:

1. Splice by startLine/endLine. Never rewrite a file from scratch.
2. Never cut a span listed in preserve.
3. If satisfiable is false, report minAchievable and stop.

Where plans live

CLI plans are written to .ctxcap/plans/ .json. Add .ctxcap/ to .gitignore; plans are local working state, not source. Plans expire after 24 hours. If a plan is missing or expired, verification returns the structured PLAN_EXPIRED error and you should generate a new plan. Run --apply on a clean tree, then review with git diff before committing. Do not run --apply in CI.

Agents can fetch the five-line loop from llms.txt.

Before and after

This is a real measurement from the ctxcap repository itself:

$ npx ctxcap --json

total: 476 baseline: 363 delta: +113 files: 2

$ npx ctxcap --plan --budget 400 satisfiable: false current: 476 minAchievable: 476 tokensRemaining: 76 plan: [] preserve: AGENTS.md:19-20, llms.txt:17-30

The result correctly stops instead of cutting load-bearing instructions. For a successful before/after case study, use a public repository with a larger context file and publish the commit, JSON reports, plan, and verification result together.

To publish a reproducible case study, include the repository commit, the ctxcap --json report before and after, the plan JSON, and the verification result. This makes the reclaim measurable and lets readers reproduce it.

Context can be stale as well as large. Run the dead-reference pass to find paths, commands, globs, and @path/#path references that no longer resolve:

npx -y ctxcap --stale --json

It reports reclaimable tokens and emits inline SARIF annotations with --sarif. Use --fail-on stale to gate CI, or --stale-fix to print a deletion diff without modifying files.

The stale pass skips fenced code blocks and suspicious tokens containing ~, $, ://, or <. Add to a line to suppress that line. --stale-fix prints a deletion diff; there is deliberately no --stale --apply mode.

Why

Agent context files — CLAUDE.md, AGENTS.md, prompts/**, .cursor/rules/ — grow every sprint. They get pasted into every request and silently burn your context window. Nothing gates them at the repo level.

ctxcap fixes that: it measures context files, tracks token deltas against a committed baseline, finds stale references, produces ranked plans, verifies edits, fails CI when you define a budget, and exposes an MCP server so agents can check themselves.

How this differs from tokenlint

tokenlint hooks your editor and reminds you per turn about wasteful habits. ctxcap gates the repo: it measures context files against a committed baseline, reports the delta on every PR, and fails only when you ask it to. Different layer — CI and review, not keystrokes.

No baseline, stale-reference pass, ranked plan, verify step, SARIF, or MCP surface there. If you want per-turn nudges inside Claude Code, use theirs; if you want a gate on prompts/**, use this.

Install

npm i -D ctxcap

npx ctxcap --update-baseline

Or run without installing:

npx -y ctxcap --json

Test another repository

Run the unpinned latest ctxcap from the repository you want to inspect. It reads the current working directory, so no files need to be copied into the ctxcap repository:

cd path/to/your-repo

npx ctxcap --json npx ctxcap --stale --json npx ctxcap --plan --budget 40000

Use the pinned version in release checks or reproducible CI. For a real edit loop, review the plan, apply it, then verify the saved plan:

npx -y ctxcap@1.2.0 --plan --budget 40000

npx -y ctxcap@1.2.0 --plan --budget 40000 --apply npx -y ctxcap@1.2.0 --verify

Start with a baseline when you want pull requests to report growth:

npx -y ctxcap@1.2.0 --update-baseline

git add ctxcap-baseline.json git commit -m "Add ctxcap baseline"

Add a .ctxcap.json file to customize included paths, ignored paths, or budgets. The default scan is intentionally limited to common agent context files.

CLI

Exit codes: 0 clean, 1 breach under --fail-on, 2 internal error.

Config

.ctxcap.json — all fields optional:

{

"include": ["AGENTS.md", "prompts/", ".cursor/rules/"], "ignore": ["prompts/archive/**"], "budgets": { "total": 40000, "AGENTS.md": 500, "prompts/system.md": 8000 }, "failOn": "budget" }

Defaults (when no config exists): scans CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, prompts/**, *.prompt, .cursor/rules/**.

GitHub Action

permissions:

contents: read pull-requests: write security-events: write # for SARIF upload; drop if you set upload-sarif: false

steps:

• uses: actions/checkout@v4 with: { fetch-depth: 0 }
• uses: Naeha-S/ctxcap@v1 with: { fail-on: increase }

Pinned form for reproducibility: uses: Naeha-S/ctxcap@v1.2.0

Inputs:

What you get on every run:

• Workflow annotations on over-budget files
• Job step summary with token table and delta

When the token can write (non-fork PRs):

• Sticky PR comment, updated in place (one comment, not a new one each run)
• SARIF upload to GitHub code scanning

Fork PRs

With plain pull_request, fork PRs get a read-only token: annotations and job summary only. For the full experience on forks, use pull_request_target as shown in examples/pull-request-target.yml.

Code scanning requires GitHub Advanced Security on private repos; SARIF upload silently no-ops without it.

MCP

Run the MCP server directly — no config needed:

npx -y ctxcap-mcp

Configure in your MCP client:

{

"mcpServers": { "ctxcap": { "command": "npx", "args": ["-y", "ctxcap-mcp"] } } }

The same stdio command works with Claude Code, Codex, and Cursor. See the MCP package guide for client-specific setup. The server reads the MCP client's current working directory and makes no network calls. Registry metadata is prepared in server.json; publication is manual and intentionally not performed by this repository workflow.

Tools exposed:

The agent loop is also available as the five-line llms.txt contract. The standalone MCP wrapper keeps plan verification in the same server process; the CLI persists plans under .ctxcap/plans/.

Output schema

{

"schema": "ctxcap/v1", "approximate": true, "tokenizer": "gpt-tokenizer@3.0.1", "total": 1247, "totalBudget": 40000, "delta": +82, "over": false, "baselineFound": true, "files": [ { "path": "AGENTS.md", "tokens": 420, "delta": +12, "budget": 500 } ], "suggestions": [] }

Full report schema: schema/report.schema.json. Plan schema: schema/plan.schema.json. Plan responses include ranked plan entries, preserve spans, and a diff summary.

Accuracy

Counts, tokensFreed, and confidence use heuristics and are approximate against Claude and Gemini (±5% for token counts). Every report carries "approximate": true and the tokenizer ID. Compare deltas, not absolutes; review the plan before applying it.

Packages

Publish and share

The packages are published on npm:

npm view ctxcap version       # 1.2.0

npm view ctxcap-mcp version # 0.1.2

Share the npm packages, the GitHub repository, or the pinned GitHub Action:

• CLI: npx -y ctxcap@1.2.0
• MCP: npx -y ctxcap-mcp@0.1.2
• Action: Naeha-S/ctxcap@v1.2.0
• Repository: https://github.com/Naeha-S/ctxcap

For a release post, show a real before/after from another repository, include the plan and verification loop, and link to the cold-install results. Ask early users to report false positives from their context-file layouts.

MIT.