Ai Context Kit

[ai-context-kit]

ai-context-kit

How do you measure the token cost of your context?

You spent hours writing the perfect .md context file, just to find out that your agent got worse.
That's not a bug. That's what happens when nobody measures the cost of context.

[Try It Now]   [Install]   [See Example Output]   [Vote on Next Features]

[GitHub stars]   [npm version] [npm downloads] [CI] [TypeScript] [License: MIT] [PRs Welcome]

[Demo]

You 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.

Six 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.

An ETH Zurich study (February 2026) measured what actually happens when you give agents context files:

• Auto-generated context files reduced task success compared to providing nothing
• Human-written ones only improved accuracy by 4%
• Inference costs jumped 20%+ from wasted tokens
• Performance dropped on some models because agents got too obedient - following unnecessary instructions instead of solving the actual problem

I 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.

import { loadRules, measure, lint, select } from "ai-context-kit";
const rules = await loadRules("./");
measure(rules, 4000); // what does your context cost?lint(rules); // conflicts? duplicates? dead weight?select(rules, {  task: "fix auth bug", // only inject what matters  budget: 2000, // stay within token budget});

Quick Start

npm install ai-context-kit

Run the CLI on any project to see what you're actually injecting:

npx ai-context-kit measure

ai-context-kit measure - 6 rule file(s)
  Total: 4,821 tokens
  ############ 2,100 tokens (44%) - .cursor/rules/conventions.mdc  ######## 1,200 tokens (25%) - CLAUDE.md  ##### 890 tokens (18%) - .cursor/rules/api-patterns.mdc  ## 340 tokens (7%) - AGENTS.md  ## 180 tokens (4%) - .cursor/rules/testing.mdc  # 111 tokens (2%) - .github/copilot-instructions.md

Then lint it:

npx ai-context-kit lint

ai-context-kit lint - 6 rule file(s)
  [!] .cursor/rules/conventions.mdc      Rule is 2100 tokens. Consider splitting to keep each file under 2000 tokens.
  [x] CLAUDE.md      Conflicts with AGENTS.md: "always use semicolons" vs "never use semicolons"
  [!] CLAUDE.md      Duplicated line also found in .cursor/rules/conventions.mdc. Duplicates waste tokens.
  [i] AGENTS.md      Contains vague instruction matching "follow best practices".      Specific instructions produce better results than general advice.
  Score: 70/100 (FAILED)

That's the difference between guessing and knowing.

What's Different

What This Answers

1. How much context am I injecting? Token count per file, percentage breakdown, budget check
2. Are my rules fighting each other? Conflict detection across all files and formats
3. What's wasting tokens? Directory listings, duplicate content, vague advice
4. Which rules matter for this task? Task-relevant selection with token budget

How It Works

ai-context-kit reads every context file format in the ecosystem, parses frontmatter, estimates token cost, and gives you tools to analyze and manage them.

API

loadRules(rootDir?)

const rules = await loadRules("./");// Finds every context file in the project
const rules = await loadRules(".cursor/rules/");// Or load from a specific directory

Returns RuleFile[] with parsed frontmatter, body, format, path, and token count.

measure(rules, budget?)

const report = measure(rules, 4000);
report.totalTokens; // 3847report.overBudget; // falsereport.rules; // sorted by size, each with tokens + percentage

lint(rules)

const report = lint(rules);
report.score; // 85/100report.passed; // true (no errors, warnings don't fail)report.issues; // array of { rule, path, severity, message }

What the linter catches:

select(rules, options)

The core insight from the research: don't inject everything. Pick what matters.

const relevant = select(rules, {  task: "fix auth bug in /api/auth",  budget: 2000,  tags: ["security", "api"],  exclude: ["style"],});

Scoring: 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.

sync(options)

Write rules once, sync everywhere.

await sync({  source: ".cursor/rules/",  targets: ["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md"],});

Supports dryRun: true to preview changes without writing.

init(options?)

await init({ format: "cursor-rules" });// Creates .cursor/rules/conventions.mdc with research-backed starter template

CLI

npx ai-context-kit lint                    # find issuesnpx ai-context-kit lint --json             # machine-readable outputnpx ai-context-kit measure                 # token cost breakdownnpx ai-context-kit measure --budget 4000   # check against budgetnpx ai-context-kit sync --source .cursor/rules/ --target CLAUDE.md,AGENTS.mdnpx ai-context-kit init                    # scaffold starter rulesnpx ai-context-kit init --format claude-md

All commands support --path <dir> to point at a different project root. lint exits with code 1 on errors (warnings pass).

Use with Vercel AI SDK / LangChain / Custom Agents

This 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?

import { loadRules, select } from "ai-context-kit";import { generateText } from "ai";
const allRules = await loadRules("./rules");
const relevant = select(allRules, {  task: userMessage,  budget: 3000,});
const systemPrompt = relevant.map((r) => r.body).join("\n\n");
const { text } = await generateText({  model: openai("gpt-4o"),  system: systemPrompt,  prompt: userMessage,});

Any framework that takes a system prompt string. Any rules stored as markdown files.

Supported Formats

ai-context-kit detects the format from the file path. No configuration needed.

Tech Stack

Contributing

PRs welcome. Whether it's a new lint rule, a format detector, or a bug fix - check out the contributing guide.

Author

[Made by ofershap]

[LinkedIn] [GitHub]

_{README built with README Builder}

License

MIT © Ofer Shapira

Star this repo · Fork it · Report a bug · Join the discussion