contextdiet

Your coding agent is only as good as the context you feed it.

contextdiet scans AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, Agent Skills, and MCP configs for stale, noisy, contradictory, or risky context.

Think Lighthouse for AI coding-agent context.

npx github:Tehlikeli107/contextdiet scan --root .
npx github:Tehlikeli107/contextdiet score --root .
npx github:Tehlikeli107/contextdiet badge --root .
npx github:Tehlikeli107/contextdiet init --root .
npx github:Tehlikeli107/contextdiet fix --safe --root .

After the npm package is published, the commands become:

npx contextdiet scan
npx contextdiet score
npx contextdiet badge
npx contextdiet init
npx contextdiet fix --safe

Why

AI coding agents are moving from demos into real repositories, but repo-level context can quietly make them worse:

• stale commands send agents down dead paths
• missing files waste tool calls
• repeated rules burn context
• conflicting instructions lower trust
• risky MCP commands expand blast radius
• bloated context increases token spend

contextdiet starts with deterministic local checks. No API keys, no network calls, no model judgment.

Quick Start

Scan the current repository:

node ./bin/contextdiet.js scan --root .

Fail CI when the score drops below 90:

node ./bin/contextdiet.js scan --root . --strict --threshold 90

Generate a README badge:

node ./bin/contextdiet.js badge --root .

Create a starter config:

node ./bin/contextdiet.js init --root .

Try the intentionally noisy demo fixture:

node ./bin/contextdiet.js scan --root examples/noisy-agent-context

Commands

| Command | Purpose | | --- | --- | | scan | Print a full human-readable report | | score | Print compact score output | | badge | Print a Shields.io markdown badge | | init | Create contextdiet.config.json if it does not exist | | fix --safe | Apply conservative whitespace-only cleanup | | --help | Print usage | | --version | Print package version |

Common options:

| Option | Purpose | | --- | --- | | --root <path> | Scan a specific repository root | | --json | Print machine-readable JSON for scan and score | | --sarif | Print SARIF 2.1.0 output for scan | | --strict | Exit 1 when score is below threshold | | --threshold <0-100> | Score threshold for strict mode, default 90 |

What It Checks

| Surface | Files | | --- | --- | | Agent instructions | AGENTS.md, CLAUDE.md | | IDE rules | .cursor/rules/*.md, .cursor/rules/*.mdc | | Copilot | .github/copilot-instructions.md | | Agent Skills | **/SKILL.md | | MCP | .mcp.json, .cursor/mcp.json |

Findings

The MVP detects:

• missing-entrypoint: no primary agent instruction surface
• stale-command: referenced npm run script does not exist
• stale-path: referenced local path does not exist
• repeated-instruction: exact repeated bullet instruction
• conflicting-instruction: simple positive/negative instruction conflict
• skill-metadata: missing name or description in SKILL.md
• risky-mcp-command: suspicious MCP command patterns
• invalid-mcp-json: invalid MCP JSON

Example

Contextdiet report
Score: 84/100
Files scanned: 1
Findings: 2

Findings:
- [warning] stale-command AGENTS.md: Referenced npm script "missing" is not defined in package.json.
- [warning] stale-path AGENTS.md: Referenced path "docs/missing.md" does not exist.

GitHub Actions

Use contextdiet as a reusable action:

name: Agent Context

on:
  pull_request:
  push:
    branches: [main]

jobs:
  contextdiet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: Tehlikeli107/[email protected]
        with:
          root: .
          threshold: 90
          format: text

Or run the CLI directly:

name: Agent Context

on:
  pull_request:
  push:
    branches: [main]

jobs:
  contextdiet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 24
      - run: npx github:Tehlikeli107/contextdiet scan --root . --strict --threshold 90

Machine Output

npx github:Tehlikeli107/contextdiet scan --root . --json
npx github:Tehlikeli107/contextdiet score --root . --json
npx github:Tehlikeli107/contextdiet scan --root . --sarif > contextdiet.sarif

Configuration

Create contextdiet.config.json in the repository root with contextdiet init, or write it manually:

{
  "$schema": "./schema/contextdiet.schema.json",
  "threshold": 90,
  "ignoredRules": [],
  "rules": {
    "stale-command": {
      "weight": 8
    },
    "risky-mcp-command": {
      "weight": 10
    }
  }
}

CLI --threshold overrides the config threshold. ignoredRules removes matching findings before scoring.

Safe Fixes

fix --safe only applies low-risk formatting cleanup:

• trims trailing whitespace
• collapses more than two consecutive blank lines

It does not delete instructions, rewrite MCP config, change permissions, or invent new agent docs.

Local Development

npm test
npm run scan
npm run score
npm run badge

Roadmap

• GitHub Action annotations
• SARIF upload workflow examples
• session-log analysis for Claude Code, Codex, Cursor, and Gemini CLI
• before/after context benchmarks
• safer skill and MCP lifecycle checks
• team policies for agent context drift

Contributing

See CONTRIBUTING.md. Keep rules deterministic, local-first, and covered by tests.

Security

See SECURITY.md. Please report suspected vulnerabilities privately.

License

MIT