token-forecast

Token Forecast

Estimate the token cost of something before it enters your context window. Help the user make an informed decision about whether to load it.

What to forecast

The user may provide:

• A file path (e.g., src/api/routes.ts)
• A directory (e.g., src/components/)
• A glob pattern (e.g., **/*.test.ts)
• A URL they plan to fetch
• Pasted content (code block or text they've included in the message)
• A description (e.g., "my node_modules folder")

If the user provided a file path or directory and you can see the file contents or directory listing in context, use actual character counts. Otherwise, use reasonable estimates based on file type and typical sizes.

Estimation method

• Prose / markdown: 1 token ≈ 4 characters
• Dense code (JS, TS, Python, etc.): 1 token ≈ 3.5 characters
• Minified / compiled code: 1 token ≈ 2.5 characters
• JSON / config: 1 token ≈ 3 characters
• Binary / images: not tokenizable — flag as "not readable"

For directories, estimate per file then sum. If the directory is large, sample a few representative files and extrapolate.

Output format

Start with a forecast headline:

📦 Forecast: {name} — ~{N} tokens ({size_label})

Size labels:

Token range	Label
< 1,000	Tiny
1,000–5,000	Small
5,000–20,000	Medium
20,000–60,000	Large
60,000–150,000	Very large
> 150,000	Massive — likely too big

Then a budget impact line showing how this fits into the current context:

📊 Budget impact: {current}% used + {forecast}% more = {total}% total (~{remaining_after} tokens remaining after load)

Then a recommendation:

{emoji} {recommendation}

Recommendation rules:

• If total after load < 60%: ✅ Safe to load — plenty of budget remaining.
• If total after load 60–75%: ⚠️ Loadable but context will be getting full. Consider closing other files first.
• If total after load 75–90%: 🟠 Risky — you'll have limited room for responses. Load only if essential.
• If total after load > 90%: 🔴 Do not load — this will critically fill your context. Use a subsection or start a new conversation.