preflight

English | 简体中文

Know what a task will cost before your agent starts it.

Pre-flight cost estimation for coding agents. Reads your local agent logs, learns what your tasks actually consume, and tells you the P50/P90 cost of a task before you let the agent run it — in your terminal, or directly inside the agent via MCP.

$ preflight estimate "refactor the auth module, add JWT refresh"

起飞前预估
  "refactor the auth module, add JWT refresh"

  周额度占比  6% ~ 12%
  Tokens      310K ~ 620K  (P50 / P90)
  花费        $1.55 ~ $3.10
  模型        gpt-5
  依据        同类任务历史  · refactor · 样本 14
  置信度      中

  建议
   · 换成 claude-sonnet-4 大约能降到 2.4%（P50），代价是复杂推理的成功率下降。

  官方额度剩余 24.0% (codex:primary) · 9 天后重置

The problem

Every tool in this space tells you what you already spent. ccusage gives you a beautiful daily report. CodexBar puts remaining quota in your menu bar. tokentop draws a budget bar. All useful — and all thermometers. They measure the fever you already have.

None of them answer the question that actually changes behavior:

If I let the agent do this refactor, how much of my weekly quota will it eat — and should I scope it down first?

That question lives in the empty quadrant: before the work (not after), at task granularity (not account granularity).

Three things it does

1. Estimates before you commit. Task fingerprint → historical distribution → P50/P90 range, expressed as a share of your quota.

2. Reads the vendor's own quota instead of guessing. Codex writes used_percent, window_minutes, and resets_at into its session logs. preflight surfaces that directly. Then it does one better — see below.

3. Turns a percentage into a token budget. Codex tells you "80% used" but never the absolute size. preflight knows how many tokens you burned in that same window from local logs. Divide one by the other and the total falls out:

total = local_tokens_in_window / (used_percent / 100)

Neither source yields remaining tokens alone. Together they do. This is what makes can_afford trustworthy.

Privacy

preflight never uploads anything. All analysis runs against local log files on your machine, and the only data it writes is ~/.preflight/ — session aggregates and one config file. Nothing leaves the machine. Uninstall = delete the directory.

The git repository contains source code only. No user data, no telemetry, no crash reporting. Example outputs in this README are illustrative, not real.

Install

git clone https://github.com/<you>/preflight.git
cd preflight
npm install
npm run build
npm link          # optional, gives you a global `preflight`

Quick start

preflight ingest                 # scan local agent logs, build your baseline
preflight now                    # quota: official + locally reconstructed
preflight estimate "fix the 500 error in the login endpoint"
preflight can-attempts --attempts 3 --task "generate a 10s product video"
preflight sessions --limit 20

ingest is idempotent. Run it from cron or a Stop hook — it's cheap and it keeps the official quota snapshot fresh.

Per-task budget guard

A dashboard tells you what you spent. A guard asks whether you should.

Set a budget for this specific task before you start:

preflight estimate "refactor the auth module" --limit 10

The verdict is three-valued, not boolean — because "over budget" means two very different things:

• [OK] — P90 fits inside the limit. Go.
• [!] — P50 fits but P90 doesn't. The task probably fits; set a mid-task checkpoint or downgrade the model first.
• [X] — P50 alone exceeds the limit. Starting as-is is burning quota on hope — narrow the scope or split the task.

Add --strict and the verdict becomes an exit code (0 = within, 1 = over). That turns a warning you might scroll past into something a script can enforce:

# e.g. wire into a PreToolUse-style hook — block the expensive work
# until the user confirms
preflight estimate "$TASK" --limit 10 --strict || ask_user_to_confirm

Inside the agent, the MCP estimate tool takes the same limit and returns the same verdict, with instructions telling the model what to propose in each case.

Use it inside your agent (MCP)

This is the point. Not a dashboard you glance at, but a tool the agent calls before doing expensive work.

Claude Code — ~/.claude/settings.json:

{
  "mcpServers": {
    "preflight": {
      "command": "node",
      "args": ["/absolute/path/to/preflight/dist/index.js", "mcp"]
    }
  }
}

Codex — ~/.codex/config.toml:

[mcp_servers.preflight]
command = "node"
args = ["/absolute/path/to/preflight/dist/index.js", "mcp"]

Three tools:

Tool	What it's for
cost_now	Remaining quota, reset countdown, refill forecast
estimate	P50/P90 share of quota for a described task; pass limit for a per-task budget verdict
can_afford	Can the remaining quota cover N attempts?

The server ships with instructions telling the model to check cost before large reads, long refactors, and generation work, and to propose a cheaper plan when P90 exceeds your per-task limit. That instruction text is the product — tune it.

How the estimate works

No ML. Deliberately — a model you can't read can't be trusted with your budget.

1. Fingerprint the request: task type (refactor / feature / debug / test / docs / review / explain) × model family × prompt length bucket.
2. Look up sessions with that fingerprint. Need 5 to trust it.
3. Degrade if thin: drop the length bucket, then the model, then fall back to a community prior table.
4. Personalize the prior: rescale by how your past sessions compare to the priors, with shrinkage so 8 sessions of history can't produce a 3x outlier.
5. Report a range, never a number. P50 / P90. Plan against P90 when the task is risky.

Cold start is honest about itself: fewer than 5 samples and it says so, tells you the number is a prior, and gets out of the way. There is no step where it pretends to know something it doesn't.

Every estimate is a hypothesis. Run enough tasks and the history takes over from the priors on its own.

Whose data does it learn from?

Yours, and only yours. Each user's forecast engine consumes only the logs they ingest on their own machine:

• No other user's samples ship with the repo — the repo is source code only
• A new user runs preflight ingest once and immediately has a baseline built from their own history
• The only built-in numbers are the community prior table (anonymous anchors like "a refactor session has a median around 380K tokens"), which only bridges the gap until a task type has 5 local samples — then it's replaced by the user's own distribution

Accuracy rises monotonically with use: day one it's a prior, day thirty it's your habits.

Configuration

~/.preflight/config.json:

{
  "weeklyTokenQuota": 2000000,
  "currency": "USD",
  "maxSingleTaskPct": 15,
  "cheaperModel": "claude-sonnet-4",
  "priceOverrides": {},
  "dataDirs": {}
}

preflight config weeklyTokenQuota 5000000

If preflight now shows >100%, your quota is set too low and every percentage will be inflated. preflight tells you when it thinks that's happening.

Sources

Source	Path	Quota data
Claude Code	~/.claude/projects/**/*.jsonl	reconstructed from tokens
Codex	~/.codex/sessions/**/*.jsonl	official rate_limits

Override paths with dataDirs if your logs live elsewhere.

Roadmap

V1

• Budget planner: given a balance and a per-attempt cost, solve for the optimal number of attempts — including two-stage draft-then-final strategies, which roughly double output per unit of budget on generation tasks
• Estimate-vs-actual calibration loop, so accuracy compounds with use
• Gemini CLI + API balance endpoints

V2

• SQLite backing store
• TUI dashboard
• Mid-task circuit breaker: suspend and confirm when a running task blows past P90

Comparison

	ccusage	CodexBar	preflight
Historical reports	yes	basic	basic
Live remaining quota	5h blocks	yes	yes (vendor-reported)
Task-level forecast	—	—	yes
Affordability planning	—	guard threshold	yes
Runs inside the agent	MCP	—	MCP
Platform	any	macOS 14+	any

preflight is not a replacement for ccusage — run both. ccusage is the better historical report. preflight is the thing you consult before you type.

Contributing

Provider log formats shift between releases. If preflight starts reading 0 sessions, run the diagnostic first:

node scripts/diagnose.mjs

It dumps the actual shape of the files on disk so you can fix the parser against real data instead of guessing. Both parsers note the CLI version they were verified against.

License

MIT