RepoDiet

See what is eating your AI coding context.

RepoDiet is a zero-dependency, local-first CLI that audits the files an AI coding agent can encounter in a repository. It estimates context cost, exposes generated and task-dependent noise, and produces a private interactive report without embedding source code.

● RepoDiet — see what is eating your AI context
────────────────────────────────────────────────────────────────────────────

  29/100  F · Context sink   noisy-repo

Potential context 126k tok   Files scanned 9   Repository size 469 KB

  Diet opportunity
  Safe to trim       34.4k tok  generated or reproducible noise
  Review first       91.9k tok  task-dependent context
  Possible saving          100%  126k tok → 103 tok

  Largest context traps
  ◆ Always-on instruction bloat   21.8k tok  1 file
  ◆ Minified bundles              21.1k tok  1 file
  ◆ Source maps in context        13.3k tok  1 file
  ◆ Large structured data         33.6k tok  1 file

中文说明

The idea

Coding agents spend a large part of their work discovering what to read. More available context is not automatically better context: generated bundles, source maps, snapshots, lockfiles, fixtures, vendored code, and oversized instructions can bury the few files that matter.

RepoDiet turns that invisible surface area into three useful answers:

1. What could enter context? A deterministic, file-by-file token estimate.
2. What is probably noise? Explainable findings split into safe, review, and refactor actions.
3. What should change? A proposed .repodietignore, a CI score, and a self-contained report suitable for review or sharing.

The timing matters: recent research reports that structural repository views can reduce agent input tokens while preserving or improving task accuracy (arXiv:2606.14061). RepoDiet is the simple, transparent diagnostic layer before indexing, retrieval, or model calls.

Why it has a chance to spread

• One-command reveal: every repository gets a surprising before/after number and visual context map.
• Screenshot-native: the report is designed as a project “nutrition label.”
• Useful without an API key: no model, account, daemon, or cloud service.
• Private enough for real repos: HTML contains paths and statistics, never source content, absolute roots, or file hashes.
• Agent-agnostic: useful with Codex, Claude Code, Cursor, Copilot, Gemini CLI, local agents, and future tools.

Quick start

Run directly from npm:

npx repo-diet .
npx repo-diet . --report

From this repository:

node ./bin/repodiet.js /path/to/repository
node ./bin/repodiet.js /path/to/repository --report=context-report.html

The HTML report is one file. Open it directly in any modern browser; it makes no network requests.

To generate the intentionally noisy demo:

npm run demo

Then open examples/repodiet-report.html.

What it detects

| Signal | Default action | Why | | --- | --- | --- | | Source maps | Safe to trim | Machine-generated and extremely token-dense | | Minified bundles | Safe to trim | Hard to reason about; original source is better | | Coverage / build output | Safe to trim | Reproducible artifact that mirrors source | | Lockfiles | Review | Important for dependency tasks, noisy otherwise | | Test snapshots | Review | Valuable only near tests that consume them | | Vendored code | Review | Usually outside the repository's ownership | | Large structured data | Review | A schema and sample are normally more useful | | Oversized source | Refactor | Must stay available, but should become navigable | | Oversized agent instructions | Refactor | Often paid at the start of every session | | Exact duplicate text | Review | Repeated context without new information |

Files are classified as source, tests, docs, config, generated, vendor, data, other text, or binary assets. Binary assets count toward repository size but not estimated text tokens.

CLI

Usage:
  repodiet [path] [options]

Options:
  --report[=FILE]       Write a self-contained interactive HTML report
  --json                Emit the complete machine-readable result
  -o, --output FILE     Write JSON to a file (requires --json)
  --ci                  Exit 2 when the score is below the threshold
  --threshold N         CI score threshold (default: 75)
  --max-files N         Maximum files to scan (default: 50000)
  --ignore GLOB         Add an ignore pattern (repeatable)
  --tracked-only        Do not include untracked, non-ignored files
  --write-ignore        Create .repodietignore with safe suggestions
  --force               Overwrite .repodietignore with --write-ignore
  --no-color            Disable terminal colors

Examples:

# Human-readable audit
repodiet .

# Interactive artifact for a design or architecture review
repodiet . --report=artifacts/context.html

# Machine-readable output
repodiet . --json --output=repodiet.json

# CI gate
repodiet . --ci --threshold=80

# Write safe suggestions only; review-level patterns remain advisory
repodiet . --write-ignore

Exit codes are 0 for a successful scan, 1 for an operational or argument error, and 2 when a CI threshold fails.

.repodietignore

RepoDiet reads an optional root file with gitignore-style glob patterns:

# Generated artifacts
**/*.map
**/coverage/**
**/dist/**

# Keep one important generated manifest
!dist/manifest.json

This file affects RepoDiet only. It does not change Git, editor, or agent behavior by itself. That separation makes the proposed diet reviewable before you copy patterns into tool-specific ignore files.

Scoring model

The score is deliberately boring and inspectable:

100
− safe-noise percentage
− 60% of review-noise percentage
− up to 10 points for oversized source/instruction structure

Grades are A (90+), B (75+), C (60+), D (40+), and F. Token counts are estimates—not billing numbers—using ASCII and Unicode character weights. The same repository produces the same result without a model or network call.

Privacy and safety

RepoDiet:

• prefers git ls-files and falls back to a local filesystem walk;
• respects .gitignore through Git and applies .repodietignore afterward;
• reads a bounded sample for very large files and extrapolates deterministically;
• never executes repository files;
• retains metadata, categories, flags, and hashes only long enough to find exact duplicates;
• strips absolute roots and hashes from HTML reports;
• makes no network requests or telemetry calls;
• writes nothing unless --report, --output, or --write-ignore is used.

See SECURITY.md for the security contract.

Library API

import { scanRepository, writeHtmlReport } from 'repo-diet';

const report = await scanRepository('/path/to/repo', {
  maxFiles: 50_000,
  ignore: ['**/fixtures/private/**'],
});

await writeHtmlReport(report, './context-report.html');

The JSON result is versioned with schemaVersion.

Architecture

Git-aware listing / filesystem fallback
                  │
                  ▼
        bounded local file sampling
                  │
                  ▼
 binary check → token estimate → classification
                  │
                  ▼
 findings + duplicate groups + tiered suggestions
                  │
          ┌───────┼────────┐
          ▼       ▼        ▼
       terminal  JSON   private HTML

There are no runtime dependencies. The browser report uses embedded CSS and vanilla JavaScript with a restrictive Content Security Policy.

Development

Requires Node.js 20 or newer.

npm test
npm run test:coverage
npm run check
npm run demo
npm pack --dry-run

The test suite covers classifier false positives, ignore semantics, scoring, duplicate detection, non-Git scanning, CLI validation, and HTML privacy.

Roadmap

• Task-aware diets: compare a declared task against repository surfaces.
• Import graphs for JavaScript/TypeScript, Python, Go, and Rust.
• GitHub Action summary and pull-request comment renderer.
• Baseline files so CI can block context regressions instead of absolute size.
• Tool-specific export for common coding-agent ignore formats.
• Optional precise tokenizer adapters that preserve the zero-dependency core.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md. Classifier changes should include true-positive and false-positive tests.

License

MIT