read-budget

Estimates token cost of files and directories before reading them into context.

Updated Jul 28, 2026
One-click install
npx skills add https://github.com/vinzenz/workflows --skill read-budget-vinzenz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: read-budget
Source: https://github.com/vinzenz/workflows/tree/main/.agents/skills/read-budget
Command: npx skills add https://github.com/vinzenz/workflows --skill read-budget-vinzenz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? AI coding agents waste context window budget by blindly reading large, generated, or vendored files — like a 900KB minified bundle or a node_modules tree — and only discovering the cost after the bytes are already loaded. This Skill answers "what will this read cost, and is it worth it?" before any file is opened. ## Core Features & Use Cases - Pre-read cost estimation: Get per-path estimates of bytes, estimated tokens, classification (source, vendored, minified, lockfile, etc.), and a read/skim/skip verdict for any file or directory. - Directory orientation and ranking: Run a bare scan to see a directory's total cost split into worth-reading vs. noise, or rank the most expensive paths with the top command. - Budget-aware read planning: Pass multiple candidate paths and receive a cheapest-first reading order with a running cumulative token total, so you know where to stop within a fixed budget. - Use Case: Before exploring an unfamiliar repository, run a scan to learn that node_modules and a lockfile account for 80% of the cost, then read only the source files that fit your remaining context budget. ## Quick Start Ask the agent to estimate the token cost of a file or directory with read-budget before reading it, for example by running read-budget path src/index.ts.

Frequently Asked Questions about read-budget

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I estimate token cost before reading a file?▼

Run read-budget path followed by the file path to get bytes, estimated tokens, a classification, and a read/skim/skip verdict. The estimate uses a calibrated bytes-per-token ratio per file class, not a real tokenizer.

How to decide which files to read within a token budget?▼

Use read-budget plan with multiple candidate paths. It returns a total cost plus a cheapest-first reading order with a running cumulative_tokens value, so you can stop reading when your budget is exhausted.

Does read-budget work outside a git repository?▼

Yes, it works outside git repositories. The .gitignore filtering simply does not apply, and the response reports this via the git_repo and gitignore_applied fields.

Are the token estimates from read-budget accurate?▼

They are calibrated heuristic estimates, never real tokenizer counts. Ratios were derived from a proxy tokenizer run against real files and biased toward the cheaper end so estimates never dangerously understate cost.

What happens when scanning huge directories like node_modules?▼

Vendored, generated, or git-ignored directories collapse to a single stat-only byte sum and are never walked file-by-file. Scans are also bounded by a max depth of 20 and 50,000 entries, with any bound hit reported explicitly.