Skip to main content

yardstick-predict

Know how long a coding-agent task will take and what it will cost, before it runs.

License: Apache 2.0 Python 3.12+

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

  1. Get a Voyage API key. Voyage turns each prompt into numbers that capture what it means. Every account gets 200 million free tokens.

  2. Run yardstick-predict and 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
    
  3. Before you start a task, ask what it will take:

    yardstick-predict predict "Add a login page with tests"
    
  4. Every week or so, run yardstick-predict and 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

Apache License 2.0.

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)

Source distribution for yardstick-predict 0.7.0
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)

Table of built distributions (wheels) for yardstick-predict 0.7.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page