AI-Readability for VS Code

Know exactly what your codebase costs to feed an AI — and fix it in one click.

Most repos silently waste 80–98% of their token budget on generated files, lock files, and minified output that AI tools can't reason about anyway. AI-Readability scans your workspace, grades every file, and shows you which ones to cut — offline, no API keys, under a second.

Works with Claude Code, GitHub Copilot, Cursor, and any other AI coding tool that reads your files.

What you get

Grade badge in the status bar

Click the status bar item (bottom-right) to scan the workspace — a grade appears there once the scan finishes, e.g. 🪙 Grade B · 14.2K tok. Click it again any time to open the full report. Updates automatically on every file save after the first scan.

Colored file decorations in the Explorer

Every file in the Explorer gets a colored grade badge:

Full scan report (webview)

Run AI-Readability: Scan Folder from the Command Palette or right-click any folder in the Explorer. The report shows:

• Grade headline — overall repo score and token count
• Context fit per model — usage % and cost per run across 14 models (Claude, GPT-4, Gemini). Claude & Gemini figures are cross-tokenizer estimates; OpenAI figures are exact
• Top 10 worst offenders — token bar chart with grade and share per file
• Exclusion recommendation — exactly which files to cut, the grade improvement, and token savings
• Write .aiignore button — applies the fix in one click and refreshes the report immediately

Quick start

1. Install the extension — the status bar item appears within a few seconds
2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run AI-Readability: Scan Folder
3. Review the report — if flagged files are shown, click Write .aiignore
4. Done — the report re-scans immediately and shows your improved grade

Commands

Context Summaries

The files your AI re-reads most are the ones imported across your codebase. Generate Context Summaries ranks them (import-graph fan-in × size) and produces a compact API skeleton for each — doc comments, exports, signatures, and type/interface contracts, with implementation bodies elided.

• Preview each skeleton inline (click to expand), see the token savings per file, then click Generate to write .ai/summaries/<path>.md + a CONTEXT_MAP.md index.
• Point your AI tool at .ai/summaries/ for cheap context; it opens the full file only when it needs detail.
• Extraction is offline (no API keys), highest-fidelity for JS/TS. Each summary embeds a source-hash so you can spot staleness and regenerate.
• Stays fresh automatically — once a file has a summary, saving that file regenerates its summary in the background (only files you've already distilled are touched; nothing new is written on save).

Settings: aiReadability.distillMinFanIn (default 2), aiReadability.distillTop (default 30), aiReadability.autoRefreshSummaries (default on).

Session Intelligence (multi-tool)

Run AI-Readability: Session Intelligence to see what your local AI coding tools have cost you over the last 14 days — across tools, in one view:

The dashboard includes:

• Filters — switch the range (7 / 14 / 30 / 90 days) and filter by tool, instantly (the widest range is parsed once and filtered in memory).
• KPI insights — projected monthly spend, change vs. the previous period, average cost per session, and estimated Claude cache savings.
• Charts — daily spend/token bars, cost-by-model breakdown, and top projects by cost.
• Token composition bar (cache read / cache create / input / output).
• Sessions table — sticky header, searchable by project, current workspace highlighted, compact token counts (full numbers on hover).
• Export — copy all sessions as CSV or JSON.
• One-click navigation — jump between the Scan Report and Session Costs views; the status-bar tooltip points here too.

Adding a new tool is a single adapter file in src/sessions/ exporting { id, name, detect(), parse() } — the registry, filters, charts, and table pick it up automatically.

Settings

How scoring works

Each file is scored 0–100 across three dimensions, then token-weighted into a repo-wide score:

Files are also checked against known generated patterns — build directories, lock files, source maps, minified assets — and flagged as [generated] regardless of score.

The .aiignore file

AI-Readability writes patterns to .aiignore in your project root. This is the single source of truth for what your AI tools should skip:

# .aiignore
playwright-report/
test-results/
package-lock.json
dist/
*.min.js

Most AI editors respect equivalent files — copy the patterns into .cursorignore for Cursor or .copilotignore for GitHub Copilot as needed.

Privacy

100% local. No network requests. No API keys. Ever.

Token counting uses gpt-tokenizer — an offline, MIT-licensed tokenizer. Your source code never leaves your machine.

Also available as a CLI

npx ai-readability .
npx ai-readability . --fix
npx ai-readability . --json | jq '.score'

The CLI supports --cost (14-model cost table), --watch, --badge, and --json for CI pipelines. View the npm package →

Requirements

• VS Code 1.85 or later
• Node.js is not required — the extension bundles its own tokenizer

License

MIT © 2026 Samrat Das