{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"ai-context-kit\" width=\"120\" height=\"120\" />\n</p>\n\n<h1 align=\"center\">ai-context-kit</h1>\n\n<p align=\"center\">\n  <strong>How do you measure the token cost of your context?</strong>\n</p>\n\n<p align=\"center\">\n  You spent hours writing the perfect .md context file, just to find out that your agent got <em>worse</em>.<br>\n  That's not a bug. That's what happens when nobody measures the cost of context.\n</p>\n\n<p align=\"center\">\n  <a href=\"#quick-start\"><img src=\"https://img.shields.io/badge/Try_It_Now-22c55e?style=for-the-badge&logoColor=white\" alt=\"Try It Now\" /></a>\n  &nbsp;\n  <a href=\"#quick-start\"><img src=\"https://img.shields.io/badge/Install-3b82f6?style=for-the-badge&logoColor=white\" alt=\"Install\" /></a>\n  &nbsp;\n  <a href=\"#quick-start\"><img src=\"https://img.shields.io/badge/See_Example_Output-8b5cf6?style=for-the-badge&logoColor=white\" alt=\"See Example Output\" /></a>\n  &nbsp;\n  <a href=\"https://github.com/ofershap/ai-context-kit/discussions/1\"><img src=\"https://img.shields.io/badge/Vote_on_Next_Features-f97316?style=for-the-badge&logoColor=white\" alt=\"Vote on Next Features\" /></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/ofershap/ai-context-kit/stargazers\"><img src=\"https://img.shields.io/github/stars/ofershap/ai-context-kit?style=social\" alt=\"GitHub stars\" /></a>\n  &nbsp;\n  <a href=\"https://www.npmjs.com/package/ai-context-kit\"><img src=\"https://img.shields.io/npm/v/ai-context-kit.svg\" alt=\"npm version\" /></a>\n  <a href=\"https://www.npmjs.com/package/ai-context-kit\"><img src=\"https://img.shields.io/npm/dm/ai-context-kit.svg\" alt=\"npm downloads\" /></a>\n  <a href=\"https://github.com/ofershap/ai-context-kit/actions/workflows/ci.yml\"><img src=\"https://github.com/ofershap/ai-context-kit/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /></a>\n  <a href=\"https://www.typescriptlang.org/\"><img src=\"https://img.shields.io/badge/TypeScript-strict-blue\" alt=\"TypeScript\" /></a>\n  <a href=\"https://opensource.org/licenses/MIT\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /></a>\n  <a href=\"https://makeapullrequest.com\"><img src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\" alt=\"PRs Welcome\" /></a>\n</p>\n\n---\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"Demo\" />\n</p>\n\nYou write a CLAUDE.md. Then someone adds `.cursor/rules/`. Then a teammate drops in an AGENTS.md. Then someone copies in a `.cursorrules` file from a blog post. Nobody removes the old ones.\n\nSix months later your project has four context files that overlap, contradict each other, and dump 8,000 tokens of directory listings and \"follow best practices\" into every conversation. Your agent follows all of it. It gets slower. It gets confused. You blame the model.\n\nAn [ETH Zurich study](https://www.sri.inf.ethz.ch/publications/gloaguen2026agentsmd) (February 2026) measured what actually happens when you give agents context files:\n\n- Auto-generated context files **reduced** task success compared to providing nothing\n- Human-written ones only improved accuracy by **4%**\n- Inference costs jumped **20%+** from wasted tokens\n- Performance dropped on some models because agents got **too obedient** - following unnecessary instructions instead of solving the actual problem\n\nI kept hitting this in my own projects, so I built `ai-context-kit` - a toolkit to treat context like a budget. Measure it, trim it, inject only what the current task needs.\n\n```typescript\nimport { loadRules, measure, lint, select } from \"ai-context-kit\";\n\nconst rules = await loadRules(\"./\");\n\nmeasure(rules, 4000); // what does your context cost?\nlint(rules); // conflicts? duplicates? dead weight?\nselect(rules, {\n  task: \"fix auth bug\", // only inject what matters\n  budget: 2000, // stay within token budget\n});\n```\n\n---\n\n## Quick Start\n\n```bash\nnpm install ai-context-kit\n```\n\nRun the CLI on any project to see what you're actually injecting:\n\n```bash\nnpx ai-context-kit measure\n```\n\n```\nai-context-kit measure - 6 rule file(s)\n\n  Total: 4,821 tokens\n\n  ############ 2,100 tokens (44%) - .cursor/rules/conventions.mdc\n  ######## 1,200 tokens (25%) - CLAUDE.md\n  ##### 890 tokens (18%) - .cursor/rules/api-patterns.mdc\n  ## 340 tokens (7%) - AGENTS.md\n  ## 180 tokens (4%) - .cursor/rules/testing.mdc\n  # 111 tokens (2%) - .github/copilot-instructions.md\n```\n\nThen lint it:\n\n```bash\nnpx ai-context-kit lint\n```\n\n```\nai-context-kit lint - 6 rule file(s)\n\n  [!] .cursor/rules/conventions.mdc\n      Rule is 2100 tokens. Consider splitting to keep each file under 2000 tokens.\n\n  [x] CLAUDE.md\n      Conflicts with AGENTS.md: \"always use semicolons\" vs \"never use semicolons\"\n\n  [!] CLAUDE.md\n      Duplicated line also found in .cursor/rules/conventions.mdc. Duplicates waste tokens.\n\n  [i] AGENTS.md\n      Contains vague instruction matching \"follow best practices\".\n      Specific instructions produce better results than general advice.\n\n  Score: 70/100 (FAILED)\n```\n\nThat's the difference between guessing and knowing.\n\n---\n\n## What's Different\n\n|                | Other approaches                                 | ai-context-kit                                               |\n| -------------- | ------------------------------------------------ | ------------------------------------------------------------ |\n| Context cost   | Nobody measures it                               | Token count per file with budget check                       |\n| Conflicts      | You find out when the agent does something weird | Detects contradictions across all files automatically        |\n| Duplicates     | Same rule in 3 files, 3x the tokens              | Flagged and scored                                           |\n| Task relevance | Every rule injected every time                   | `select()` picks only what matters for the current task      |\n| Multi-tool     | Locked to one IDE's format                       | Works across Cursor, Claude Code, Copilot, Windsurf, Cline   |\n| CI             | Hope for the best                                | `lint` exits with code 1 on errors. Drop it in your pipeline |\n\n---\n\n## What This Answers\n\n1. **How much context am I injecting?** Token count per file, percentage breakdown, budget check\n2. **Are my rules fighting each other?** Conflict detection across all files and formats\n3. **What's wasting tokens?** Directory listings, duplicate content, vague advice\n4. **Which rules matter for this task?** Task-relevant selection with token budget\n\n---\n\n## How It Works\n\nai-context-kit reads every context file format in the ecosystem, parses frontmatter, estimates token cost, and gives you tools to analyze and manage them.\n\n|               |                                                                                                                                     |\n| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `loadRules()` | Auto-detects `.cursor/rules/`, `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, `copilot-instructions.md`, `.windsurfrules`, `.clinerules` |\n| `measure()`   | Token cost per rule, percentage of total, budget check                                                                              |\n| `lint()`      | Conflicts, duplicates, bloat, vague instructions, useless directory trees. Scores 0-100                                             |\n| `select()`    | Picks rules relevant to the current task. Respects a token budget. `alwaysApply` rules first, then by relevance                     |\n| `sync()`      | Single source of truth. Write once in `.cursor/rules/`, sync to CLAUDE.md, AGENTS.md, and the rest                                  |\n| `init()`      | Starter template with tips from the research                                                                                        |\n\n---\n\n## API\n\n### `loadRules(rootDir?)`\n\n```typescript\nconst rules = await loadRules(\"./\");\n// Finds every context file in the project\n\nconst rules = await loadRules(\".cursor/rules/\");\n// Or load from a specific directory\n```\n\nReturns `RuleFile[]` with parsed frontmatter, body, format, path, and token count.\n\n### `measure(rules, budget?)`\n\n```typescript\nconst report = measure(rules, 4000);\n\nreport.totalTokens; // 3847\nreport.overBudget; // false\nreport.rules; // sorted by size, each with tokens + percentage\n```\n\n### `lint(rules)`\n\n```typescript\nconst report = lint(rules);\n\nreport.score; // 85/100\nreport.passed; // true (no errors, warnings don't fail)\nreport.issues; // array of { rule, path, severity, message }\n```\n\nWhat the linter catches:\n\n| Rule                | Severity      | What it finds                                                |\n| ------------------- | ------------- | ------------------------------------------------------------ |\n| `token-budget`      | warning/error | Files over 2,000 tokens (warning) or 5,000 (error)           |\n| `empty-rule`        | warning       | Files too short to do anything                               |\n| `duplicate-content` | warning       | Same instruction repeated across files                       |\n| `conflict`          | error         | \"always use X\" in one file, \"never use X\" in another         |\n| `directory-listing` | warning       | 10+ line directory trees that agents don't need              |\n| `vague-instruction` | info          | \"follow best practices\", \"write clean code\", \"be consistent\" |\n\n### `select(rules, options)`\n\nThe core insight from the research: don't inject everything. Pick what matters.\n\n```typescript\nconst relevant = select(rules, {\n  task: \"fix auth bug in /api/auth\",\n  budget: 2000,\n  tags: [\"security\", \"api\"],\n  exclude: [\"style\"],\n});\n```\n\nScoring: `alwaysApply: true` in frontmatter gets highest priority. Then task words matched against file paths and content. Then tag matches. Budget is respected - highest-scored rules are included first until the budget runs out.\n\n### `sync(options)`\n\nWrite rules once, sync everywhere.\n\n```typescript\nawait sync({\n  source: \".cursor/rules/\",\n  targets: [\"CLAUDE.md\", \"AGENTS.md\", \".github/copilot-instructions.md\"],\n});\n```\n\nSupports `dryRun: true` to preview changes without writing.\n\n### `init(options?)`\n\n```typescript\nawait init({ format: \"cursor-rules\" });\n// Creates .cursor/rules/conventions.mdc with research-backed starter template\n```\n\n---\n\n## CLI\n\n```bash\nnpx ai-context-kit lint                    # find issues\nnpx ai-context-kit lint --json             # machine-readable output\nnpx ai-context-kit measure                 # token cost breakdown\nnpx ai-context-kit measure --budget 4000   # check against budget\nnpx ai-context-kit sync --source .cursor/rules/ --target CLAUDE.md,AGENTS.md\nnpx ai-context-kit init                    # scaffold starter rules\nnpx ai-context-kit init --format claude-md\n```\n\nAll commands support `--path <dir>` to point at a different project root. `lint` exits with code 1 on errors (warnings pass).\n\n---\n\n## Use with Vercel AI SDK / LangChain / Custom Agents\n\nThis isn't just for Cursor. If you're building agents with Vercel AI SDK, LangChain, or your own framework, ai-context-kit solves the same problem: how much context are you stuffing into the system prompt, and is it helping or hurting?\n\n```typescript\nimport { loadRules, select } from \"ai-context-kit\";\nimport { generateText } from \"ai\";\n\nconst allRules = await loadRules(\"./rules\");\n\nconst relevant = select(allRules, {\n  task: userMessage,\n  budget: 3000,\n});\n\nconst systemPrompt = relevant.map((r) => r.body).join(\"\\n\\n\");\n\nconst { text } = await generateText({\n  model: openai(\"gpt-4o\"),\n  system: systemPrompt,\n  prompt: userMessage,\n});\n```\n\nAny framework that takes a system prompt string. Any rules stored as markdown files.\n\n---\n\n## Supported Formats\n\n| Format          | File                              | Used by              |\n| --------------- | --------------------------------- | -------------------- |\n| Cursor (modern) | `.cursor/rules/*.mdc`             | Cursor IDE           |\n| Cursor (legacy) | `.cursorrules`                    | Cursor IDE           |\n| Claude Code     | `CLAUDE.md`                       | Claude Code          |\n| AGENTS.md       | `AGENTS.md`                       | Cross-agent standard |\n| GitHub Copilot  | `.github/copilot-instructions.md` | GitHub Copilot       |\n| Windsurf        | `.windsurfrules`                  | Windsurf             |\n| Cline           | `.clinerules`                     | Cline                |\n\nai-context-kit detects the format from the file path. No configuration needed.\n\n---\n\n<details>\n<summary><strong>Why not just write better rules?</strong></summary>\n\nThe ETH Zurich study tested both human-written and LLM-generated context files. Human-written ones were better, but only by 4%. The real problem isn't quality - it's volume. More context means more tokens consumed by instructions the agent doesn't need for the current task. The winning strategy is fewer, task-relevant rules, not better prose.\n\n</details>\n\n<details>\n<summary><strong>How accurate is the token estimation?</strong></summary>\n\nai-context-kit uses a 4-character-per-token approximation. This is intentionally simple and fast. It's accurate enough for budgeting and comparison (GPT-4 averages ~4 chars/token for English text). If you need exact counts, pipe the output through tiktoken or your model's tokenizer.\n\n</details>\n\n<details>\n<summary><strong>Does this work in CI?</strong></summary>\n\nYes. `npx ai-context-kit lint` returns exit code 1 on errors, 0 on pass. Add it to your CI pipeline the same way you'd add eslint. The `--json` flag gives machine-readable output for custom reporting.\n\n</details>\n\n---\n\n## Tech Stack\n\n| Component    | Technology                                                                                                                                           |\n| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Language     | [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://github.com/microsoft/TypeScript) strict mode |\n| Testing      | [![Vitest](https://img.shields.io/badge/Vitest-6E9F18?logo=vitest&logoColor=white)](https://github.com/vitest-dev/vitest)                            |\n| Bundler      | [![tsup](https://img.shields.io/badge/tsup-000?logo=esbuild&logoColor=white)](https://github.com/egoist/tsup) ESM + CJS                              |\n| Dependencies | Zero runtime dependencies                                                                                                                            |\n\n---\n\n## Contributing\n\nPRs welcome. Whether it's a new lint rule, a format detector, or a bug fix - check out the [contributing guide](CONTRIBUTING.md).\n\n---\n\n## Author\n\n[![Made by ofershap](https://gitshow.dev/api/card/ofershap)](https://gitshow.dev/ofershap)\n\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0A66C2?style=flat&logo=linkedin&logoColor=white)](https://linkedin.com/in/ofershap)\n[![GitHub](https://img.shields.io/badge/GitHub-Follow-181717?style=flat&logo=github&logoColor=white)](https://github.com/ofershap)\n\n---\n\n<sub>README built with [README Builder](https://ofershap.github.io/readme-builder/)</sub>\n\n## License\n\n[MIT](LICENSE) &copy; [Ofer Shapira](https://github.com/ofershap)\n\n---\n\n<p align=\"center\">\n  <a href=\"https://github.com/ofershap/ai-context-kit\">Star this repo</a> · <a href=\"https://github.com/ofershap/ai-context-kit/fork\">Fork it</a> · <a href=\"https://github.com/ofershap/ai-context-kit/issues\">Report a bug</a> · <a href=\"https://github.com/ofershap/ai-context-kit/discussions\">Join the discussion</a>\n</p>\n",
  "bytes": 15778,
  "sha": "2122c9627f981c7e277c69ceea5c132bba3dbeef8e71aac171fdcdc5b58a91b0",
  "repo_slug": "ofershap/ai-context-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ofershap_ai_context_kit_48adce9e/readme"
}