# preflight

English | [简体中文](README.zh-CN.md)

**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

```bash
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

```bash
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:

```bash
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:

```bash
# 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`:

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

**Codex** — `~/.codex/config.toml`:

```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`:

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

```bash
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:

```bash
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