yardstick-predict
Know how long a coding-agent task will take and what it will cost, before it runs.
yardstick-predict learns from your own past Claude Code and Codex runs. Give it a task and it forecasts the time, tokens and dollars on each AI model you use. It's built for orchestrators: programs that run many coding agents and pick an AI model, a time limit or a budget for each task.
$ yardstick-predict predict "Add a login page with tests"
Add a login page with tests
AI model effort time tokens cost
claude-opus-5-5 max expected 4 min 1.8M $0.92
25% 3 min 1.1M $0.60
median 4 min 1.6M $0.84
75% 5 min 2.2M $1.19
gpt-6.1-sol ⚠ xhigh expected 5 min 950k $0.41
25% 3 min 531k $0.23
median 5 min 862k $0.37
75% 7 min 1.4M $0.60
⚠ Not enough data: gpt-6.1-sol.
Those are a rough guide. Plan with a wider margin there.
The expected line is what to expect on average. A quarter of real results
come in under the 25% line, half under the median and three quarters under
the 75% line. Costs are at API prices.
Learned from your own runs · model main, updated 2 days ago · add --json for
details
The numbers above are an example. Yours come from your own history.
- Nothing to label. Claude Code and Codex already keep a record of every run. yardstick-predict learns from those.
- It checks itself first. It replays your newest tasks as if they hadn't happened yet. Programs get forecasts only for the AI models it forecast well.
- Your prompts go to Voyage. So does the end of the conversation before each one, as the Context feature is on by default. Voyage turns them into numbers that capture what they mean. With LLM analysis on, both also go to the AI model you pick. Before anything is sent, text shaped like a key, token or password is replaced with
[hidden]. Training and forecasts run on your computer. - It shows the cost before it spends anything.
- Programs get JSON in a fixed, versioned format.
Install
uv tool install yardstick-predict
You need uv, a tool that installs Python programs. It works on macOS, Linux and Windows. It needs Python 3.12 or newer, which uv fetches if you don't have it. To update later, run uv tool upgrade yardstick-predict.
Quick start
-
Get a Voyage API key. Voyage turns each prompt into numbers that capture what it means. Every account gets 200 million free tokens.
-
Run
yardstick-predictand choose Add New. It finds your past runs, asks for your key when it has none, shows the cost and trains a model, which makes your forecasts. A key you paste is kept in your computer's password store. To take every default and agree to the cost in one line instead:export VOYAGE_API_KEY=your-key yardstick-predict create --express
-
Before you start a task, ask what it will take:
yardstick-predict predict "Add a login page with tests"
-
Every week or so, run
yardstick-predictand choose Update. It reads your new runs and trains again.
See forecasts in Claude Code
yardstick-predict claude-code install
Claude Code's status line then shows a forecast for each prompt you send. It counts up while the agent works:
yardstick · 1:12 of ~4 min · ~$1.23
On a Claude subscription, it shows shares of your weekly limit in place of dollars. First comes what the task has used so far. Then the brackets hold the forecast's time and its share of the week:
yardstick · 1:12 · 0.0236% (~4 min · ~0.0789%)
Each prompt goes to Voyage to be embedded, with the end of the conversation before it when Context is on. That costs a tiny fraction of a cent each time. yardstick-predict claude-code remove turns it off.
Use it from a program
predict reads a JSON request on standard input and writes a JSON answer. It never asks questions.
echo '{"version": 1, "tasks": [
{"id": "a", "prompt": "Fix the flaky test", "models": ["claude-opus-5-5", "gpt-6.1-sol"]}
]}' | yardstick-predict predict
Each forecast has seconds, tokens and usd. They are averages. Ten tasks' forecasts add up to their expected total. When a forecast isn't given, its numbers are null and reason says why. The format explains every field. Setup and refresh answer in JSON too, with --json.
Commands
| Command | What it does |
|---|---|
yardstick-predict |
Opens the home screen: Estimate, Update, Models and Add New. |
yardstick-predict create [NAME] |
Sets up a new model. |
yardstick-predict refresh |
Reads your new runs and trains again. |
yardstick-predict predict "TASK" |
Forecasts a task. |
yardstick-predict status |
Shows how close each model came on your newest tasks. |
yardstick-predict list |
Lists your models. |
yardstick-predict check [NAME] |
Says which features help a model's forecasts. |
yardstick-predict features |
Lists the features each model uses and what's stored. |
yardstick-predict default [NAME] |
Shows or sets the model commands use when they name none. |
yardstick-predict rename OLD NEW |
Renames a model. |
yardstick-predict delete NAME |
Deletes a model. Your records stay. |
yardstick-predict claude-code install |
Shows forecasts in Claude Code's status line. |
yardstick-predict uninstall |
Removes yardstick-predict: takes it out of Claude Code and deletes your models. |
Most commands take --json for programs. yardstick-predict COMMAND --help lists every flag of a command. The guide says more about each one.
Remove it
yardstick-predict uninstall
It takes the forecasts out of Claude Code, everywhere you added them. Then it deletes the Voyage key it kept and your models. It says what goes and asks first. Add --keep-data to keep your models and the key. Last, it shows the command that removes the program itself, such as uv tool uninstall yardstick-predict.
Learn more
- The guide: the home screen, the features a model learns from, LLM analysis, costs, settings for experts, plugins, privacy and how to update or remove it.
- How it works: the data, the model and how it tests itself.
- The format: every field programs send and get back.
- What's next: what's planned.
Contributing
Bug reports, ideas and pull requests are welcome. See the contributing guide and the security policy.
License
Metadata
Release files for yardstick-predict 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| yardstick_predict-0.7.0.tar.gz | 833.1 kB | With provenance | Details for yardstick_predict-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| yardstick_predict-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for yardstick_predict-0.7.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / yardstick_predict-0.7.0.tar.gz
| Download URL | yardstick_predict-0.7.0.tar.gz |
|---|---|
| Size | 833.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
20d6a74031ffeec85c7e7cc9335863a9478d144e40affd5879ae353b885f192f
|
|
BLAKE2b-256 checksum How to use checksums |
e5c065dabbecc8c83dbdeaa4f4f19105ff95fd85f4a12c4adc1167b66ead336a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / yardstick_predict-0.7.0-py3-none-any.whl
| Download URL | yardstick_predict-0.7.0-py3-none-any.whl |
|---|---|
| Size | 272.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e0f4dcb92f1a9cc088767cb283ebfdf0760d7662b731f40127771fdad6584d87
|
|
BLAKE2b-256 checksum How to use checksums |
e93bd76511203e979317ee5ad7ea8153f876d1f7692d6ae6c6d3d511eaf1742c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for yardstick-predict 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for yardstick_predict-0.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.