{"id":51362258,"url":"https://github.com/gonzaloperiane/ctxweight","last_synced_at":"2026-07-03T00:01:25.581Z","repository":{"id":368941900,"uuid":"1287604426","full_name":"GonzaloPeriane/ctxweight","owner":"GonzaloPeriane","description":"Static, pre-flight audit of your AI agent's context cost — know what CLAUDE.md, AGENTS.md, skills and MCP schemas cost per turn, before you run the agent.","archived":false,"fork":false,"pushed_at":"2026-07-02T22:27:02.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T23:25:02.974Z","etag":null,"topics":["agents","agents-md","ai","claude","claude-code","cli","context-engineering","developer-tools","mcp","token-optimization"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ctxweight","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GonzaloPeriane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-02T21:01:15.000Z","updated_at":"2026-07-02T22:31:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GonzaloPeriane/ctxweight","commit_stats":null,"previous_names":["gonzaloperiane/ctxaudit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/GonzaloPeriane/ctxweight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GonzaloPeriane%2Fctxweight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GonzaloPeriane%2Fctxweight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GonzaloPeriane%2Fctxweight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GonzaloPeriane%2Fctxweight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GonzaloPeriane","download_url":"https://codeload.github.com/GonzaloPeriane/ctxweight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GonzaloPeriane%2Fctxweight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35067032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","agents-md","ai","claude","claude-code","cli","context-engineering","developer-tools","mcp","token-optimization"],"created_at":"2026-07-03T00:01:11.862Z","updated_at":"2026-07-03T00:01:25.562Z","avatar_url":"https://github.com/GonzaloPeriane.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ctxweight\n\n**X-ray your AI agent's context — health and token cost in one command.**\n\n`ctxweight` is an offline, developer-first auditor for the context files that drive AI coding agents (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `copilot-instructions.md`, skills, and connected MCP servers). It tells you two things most teams are flying blind on:\n\n1. **Is my context healthy?** — oversized, truncated files and leaked secrets (redundancy, drift, and contradiction checks are on the [roadmap](#roadmap)).\n2. **What is my context costing me?** — how many tokens (and dollars) each piece eats on every single agent run.\n\n\u003e Think `npm audit`, but for the context window. No config leaves your machine.\n\n---\n\n## Example output\n\n\u003c!-- SCREENSHOT: replace with a color screenshot --\u003e\n\nRunning `ctxweight` on a real repo (`browser-use/browser-use`):\n\n```\n  ctxweight · browser-use\n  GRADE D  ·  always-on 11,647 tok/turn (5.8%)  ·  on-demand 11,720 tok\n  always-on = read on every message · on-demand = only loaded when a skill/rule runs\n\n  2 files too long · 1 truncated (\u003e32 KiB) · 1 email in context\n  truncated = too big; the agent cuts it off and won't read all of it\n\n  Suggestions\n    → Trim AGENTS.md to the essentials, or split it via @imports and move task-specific guidance into on-demand skills.\n    → Split AGENTS.md (38.4 KiB): move stable, rarely-read sections into @imported files or on-demand skills so the always-on core stays under 32 KiB.\n    → Remove or redact this — context files are committed and sent to the agent on every run.\n\n  AGENTS.md                                           9,141 (39%) ██████·········· [always-on]\n  CLAUDE.md                                           2,506 (11%) ██·············· [always-on]\n  skills/x402/SKILL.md                                4,123 (18%) ███············· [on-demand]\n  skills/qa/SKILL.md                                  2,250 (10%) ██·············· [on-demand]\n  skills/remote-browser/SKILL.md                      1,839 ( 8%) █··············· [on-demand]\n  browser_use/skills/browser-use/SKILL.md             1,145 ( 5%) █··············· [on-demand]\n  skills/browser-use/SKILL.md                         1,145 ( 5%) █··············· [on-demand]\n  … and 2 more (1,218 tokens, --full)\n```\n\nIn a real terminal the grade badge and bars are colored (green A/B · amber C/D · red F). Add `--full` for every finding and every file.\n\n---\n\n## Why this exists\n\nEvery AI coding agent reads a context file before it does anything. The instinct is to make that file bigger — and that's exactly the trap.\n\nA 2026 ETH Zürich study found that auto-generated, redundant context files *reduced* task success rates and *increased* inference cost by over 20%, mostly by duplicating what the agent could already read from the code and README. The failure modes are always the same:\n\n- **Bloat** — files grow past the model's effective instruction budget; the rest is silently ignored (\"lost in the middle\").\n- **Redundancy** — rules that restate the README or things a linter already enforces.\n- **Drift** — `CLAUDE.md` and `AGENTS.md` and `.cursorrules` slowly disagree.\n- **Leaked secrets** — these files are committed *and* end up in the agent's logged context, so an API key or internal hostname in there is a real exposure.\n- **Invisible token cost** — config files, skills, and every connected MCP server's tool schema all consume the window on every run, and nobody is measuring it.\n\nThe market is full of *generators* for these files. `ctxweight` is the opposite: an **auditor**. It doesn't write your context for you — it tells you what's wrong with the context you have and what it's costing you.\n\n---\n\n## What it does\n\n### `ctxweight health` — context quality\n\nScans every agent-context source in the repo and reports:\n\n| Check | What it flags |\n|---|---|\n| **Budget / length** | Files over the recommended size (200 lines) or past the 32 KiB hard-truncation limit some agents enforce |\n| **Secrets \u0026 PII** | API keys, tokens, private IPs and emails committed into context — with placeholder + entropy awareness, so it won't flag `your_api_key_here`, `m0-your-api-key`, or RFC 2606 `example.com` |\n\nOutput is a single **Context Health score** (A–F) plus an itemized, fixable list. A repo with no agent-context files at all scores **N/A** — \"nothing to audit\", not a perfect A.\n\n**Planned (roadmap — not yet implemented):**\n\n- **Redundancy** — content duplicated from the README, the code, or another context file\n- **Drift** — the same rule present in one context file but missing or reworded in another\n- **Contradictions** — conflicting rules (heuristic; optional semantic pass)\n- **Linter overlap** — rules a formatter/linter already enforces deterministically\n\n### `ctxweight budget` — token cost\n\nNot all context is loaded the same way, so `budget` reports **two** numbers instead of one — and this split is the whole point:\n\n- **Always-on** — your root context files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, …) **plus every connected MCP server's tool schemas**. This is loaded on *every single turn*: it's your fixed per-turn token cost (and the only part that's really competing for the context window).\n- **On-demand** — `SKILL.md` files and `.cursor/rules/*.mdc`, which load **only when that skill or rule is invoked**. A 600-line skill isn't bloat — you pay for it when you use it, not every turn.\n\nThis matters because tools that sum everything into one \"tokens/run\" number lie to you: 40k tokens of skills you rarely trigger is fine, while 40k tokens in `AGENTS.md` is a tax on every request. Real example — running on a repo with 39 skills and Cursor rules reports **~1,559 always-on tokens/turn** but **~41,000 on-demand** across those 39 files: the headline \"43k\" would be alarming and wrong.\n\nFor each source `budget` shows its token weight and whether it's **always-on** or **on-demand**, the always-on share of the context window, and (with `--model`) the estimated always-on input cost per turn.\n\nMCP tool-schema accounting is the part no other tool gives you: connecting ten MCP servers can quietly burn thousands of *always-on* tokens on every turn before your prompt is even read. ctxweight counts the schemas a server declares statically and — staying offline-first — flags servers that only expose tools at runtime instead of connecting to them.\n\n---\n\n## Quickstart\n\nNo install required:\n\n```bash\nnpx ctxweight .        # health + budget for the current directory\n```\n\nOr install it and use the short `ctxweight` command:\n\n```bash\nnpm i -g ctxweight\nctxweight health .                                      # quality checks only\nctxweight budget . --model claude-opus --mcp .mcp.json  # token cost only\nctxweight . --json                                      # machine-readable\nctxweight . --sarif \u003e ctxweight.sarif                    # GitHub code scanning\nctxweight . --md                                        # writes ctxweight-report.md\nctxweight . --fail-on secrets/aws-key,error             # CI exit gate (see below)\n```\n\n**Commands:** `ctxweight [path]` (health + budget), `ctxweight health [path]`, `ctxweight budget [path]`.\n**Flags:** `--model \u003cname\u003e`, `--mcp \u003cfile\u003e`, `--json`, `--sarif`, `--md`, `--fail-on \u003clist\u003e`.\n\n### Detecting problems\n\nPoint it at a `CLAUDE.md` that committed an AWS key, a real contact email, and a doc example (`user@example.com`):\n\n```\n  ctxweight · my-repo\n  GRADE D\n\n  1 AWS key in context · 1 email in context\n\n  Suggestions\n    → Remove this value and inject it at runtime instead — context files are committed AND logged.\n    → Remove or redact this — context files are committed and sent to the agent on every run.\n```\n\nThe AWS key and the real contact email are flagged; the `user@example.com` doc example is **not** (RFC 2606 placeholder). Every finding carries a stable code (`secrets/aws-key`, `secrets/email`, …) you can target with `--fail-on` to gate CI. Add `--full` for per-finding detail with `file:line`.\n\n---\n\n## Output formats\n\n- **Terminal** — human-readable summary (default)\n- **`--json`** — machine-readable, for scripts\n- **`--sarif`** — drops findings straight into the GitHub Security tab\n- **`--md`** — a shareable `ctxweight-report.md`\n\n## CI / GitHub Actions\n\nThis repo dogfoods itself — see [`.github/workflows/ci.yml`](.github/workflows/ci.yml). The pattern is **CI-safe in two halves**: a self-scan step writes the SARIF with `continue-on-error` so findings never fail *that* step, while a separate gate step uses `--fail-on` on secret codes to actually break the build. The SARIF upload runs with `if: always()`, so findings always reach the GitHub Security tab even when the gate fails.\n\n```yaml\n- name: Context audit (self) — generate SARIF\n  continue-on-error: true\n  run: node dist/cli.js . --sarif \u003e ctxweight.sarif\n\n- name: Context audit gate — fail on leaked secrets\n  run: node dist/cli.js . --fail-on secrets/private-key,secrets/aws-key,secrets/openai-key,secrets/generic-token\n\n- name: Upload SARIF\n  if: always()\n  uses: github/codeql-action/upload-sarif@v3\n  with:\n    sarif_file: ctxweight.sarif\n```\n\n---\n\n## Philosophy\n\n- **Offline-first.** Your context never leaves your machine. No telemetry, ever. (Every cloud scanner asks you to upload the very config you're trying to keep private — `ctxweight` doesn't.)\n- **Auditor, not generator.** It measures and explains; it never silently rewrites your files.\n- **GDPR-aware by default.** Secrets and PII detection is a first-class check, not an afterthought, because committed-and-logged context is a real data-exposure path.\n\n---\n\n## Limitations — what ctxweight doesn't see\n\nctxweight measures the **static** context on disk: `CLAUDE.md`, `AGENTS.md`, skills, `.cursorrules`, and the MCP tool schemas declared in your config. That's the part you can audit before a single turn runs.\n\nIt does **not** see context injected at **runtime**:\n\n- **Dynamic memory systems** (MemPalace, mem0, and friends) that retrieve and inject content per query.\n- **Runtime RAG** that pulls documents into the prompt on the fly.\n- **MCP servers that only expose their tools on connect** — their schemas aren't in the static config, so ctxweight reports them as `0` rather than guessing.\n\nA one-line `CLAUDE.md` that points at a memory system will score **light** even though it injects thousands of tokens on every turn.\n\n**Read the result as the cost of your _static_ context — not the real total if you rely on dynamic memory or runtime RAG.**\n\n---\n\n## Study — 33 popular repos\n\nWe scanned the agent context of 33 widely-used AI dev tools (Codex, Cline, Continue, crewAI, mem0, LibreChat, …). Always-on cost — the tokens loaded on **every** turn — ranged from **0 to ~31,700 tokens**, with **30% over 8,000 tokens/turn**. And the honest headline on security: **zero real leaked credentials**. What naive scanners flag as \"secrets\" is almost always documentation — contact emails, example IPs, and env-var references.\n\nFull aggregate report (offline, reproducible with `npm run study`): [`scripts/study/STUDY.md`](scripts/study/STUDY.md).\n\n---\n\n## Roadmap\n\n- [x] `health` checks: budget/length + secrets \u0026 PII\n- [x] `budget` real tokenizer (`gpt-tokenizer`, `o200k_base`)\n- [x] `budget` MCP tool-schema accounting (static schemas, offline)\n- [x] SARIF + Markdown reporters\n- [x] `--fail-on` CI exit gate\n- [x] Follow `@import` references (Claude Code's `@AGENTS.md` / `@docs/x.md`) and count imported files transitively\n- [x] Actionable fix suggestions per finding (split the file, move it to on-demand, fix the broken import, …)\n- [x] Placeholder + entropy awareness for secret detection (skips `your_api_key_here`, `m0-your-api-key`, RFC 2606 `example.com`)\n- [ ] `health` redundancy + drift checks (duplication vs. README / cross-file, `CLAUDE.md` ↔ `AGENTS.md` drift)\n- [ ] Treat `process.env.*` references and env-var names as non-secrets (placeholder awareness v2)\n- [ ] Memory-system awareness — estimate per-turn token injection from MemPalace / mem0-style stores and runtime RAG (today only static context is measured)\n- [ ] Target budgets — \"always-on uses X of Y recommended tokens\", with a configurable per-turn ceiling\n- [ ] `--mcp-connect`: measure real MCP schemas by launching each server in a sandbox and calling `tools/list` (opt-in)\n- [ ] Optional `--llm` semantic pass for contradictions (local model supported)\n- [ ] Shareable **Context Health badge** + web report card\n\n## Contributing\n\nIssues and PRs welcome. If `ctxweight` should catch something it doesn't, open an issue with a minimal repro.\n\n## License\n\nApache-2.0.\n\n---\n\n_Author: **[GonzaloPeriane](https://github.com/GonzaloPeriane)**._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgonzaloperiane%2Fctxweight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgonzaloperiane%2Fctxweight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgonzaloperiane%2Fctxweight/lists"}