Checks token counts per file and plans context budget. Shows which files consume the most tokens and how to optimize context window usage.

Token Budget

Name: token-budget
Author: kalpeshgamit

Analyze token distribution across your codebase and plan context usage.

Usage

Token breakdown (top files by size)

codebase-pilot tokens

Token breakdown for specific agent

codebase-pilot tokens --agent <name>

Dry run to preview pack budget

codebase-pilot pack --compress --dry-run

Usage history and savings

codebase-pilot stats
codebase-pilot stats --global

Usage Scenarios

Before packing — know your token budget
Choosing --agent scope — see which agent contexts are leanest
Deciding whether to use --compress — see the potential savings
Tracking savings over time — stats shows daily/weekly/monthly

Output Example

Savings estimate (per session):
  Without codebase-pilot:   ~98,798 tokens
  With pack --compress:      ~29,274 tokens
  Pilot saves:              ~69,524 tokens per session

Your savings (from pack runs):
  Today:      3 sessions  — ~92,232 tokens saved
  This week:  5 sessions  — ~147,498 tokens saved

Tips

Web dashboard: http://localhost:7456 shows live token stats
Files page: http://localhost:7456/files shows per-file token breakdown
Prompts page: http://localhost:7456/prompts shows all session history