estimate

agent-estimate

Know before you build.

PERT estimates for AI-agent tasks — how long, which model's reliable enough, and the human-equivalent cost. In one command.

Website · Compare · PyPI

Why

AI agents can write the code — but how long will the task actually take? Manual estimation is slow and biased toward optimism; no estimate means scope creep and missed deadlines. The gap between "agents can do it" and "we know when it'll be done" is where projects break down.

agent-estimate closes that gap in one command: a three-point PERT timeline built from priors drawn from 33 internal coding dispatches and 6 brainstorm dispatches, plus a human-speed comparison so you see the compression before you spend the compute. It sizes the task, picks a tier, routes it to a model, and flags when the work exceeds that model's configured reliability policy — forecasts in seconds, not meetings.

Multi-model matters because the models aren't interchangeable. A measured p80 horizon is the human-expert task duration at which a model is estimated to succeed 80% of the time. The shipped limits below are instead provenance-labeled local policy (unmeasured), because current models such as Opus 5.5 and GPT-6 Astra do not have matching published measurements. agent-estimate models the whole fleet, not a single agent — so the number reflects who actually runs the work.

Quick Start

First estimate: 30 seconds to install. Every one after: instant.

With your agent (recommended)

Paste this into your Claude Code or Codex session:

Install the agent-estimate plugin (https://github.com/kiloloop/agent-estimate) and
estimate this task for me: "Implement OAuth 2.0 flow (Google + GitHub)". Tell me the
expected time, the human-speed equivalent, and the compression ratio.

Your agent installs the tool, runs the estimate, and reads back the numbers. Nothing to memorize — describe the task in plain English and let the agent translate to flags.

For a whole backlog:

Estimate every open issue in this repo with agent-estimate, group them into parallel
waves, and tell me the total wall-clock time for a 2-agent fleet versus doing them
sequentially myself.

Manual

pip install agent-estimate
agent-estimate estimate "your task description here"

No config required — sensible defaults for a 2-agent fleet (Claude, Codex). Point it at a file or GitHub issues when you're ready:

agent-estimate estimate --file tasks.txt
agent-estimate estimate --repo myorg/myrepo --issues 11,12,14
agent-estimate session --agents 3 --rounds 2 --type review

v0.8 forecast contract

The v0.8 source introduces a versioned request for callers that already know the task and executor. These features are not in the published v0.7.5 package; use an installation from this checkout until v0.8 is released. Bare task descriptions, text files, and GitHub issue input remain available.

The typed contracts are frozen, reject unknown fields and non-finite numbers, and require explicit schema versions. Model identity must be either a supplied identifier or an unknown_reason; selecting an agent does not establish its serving model. IDs are caller supplied. The library also exposes OutcomeObservation with nullable future actuals slots; it does not ingest actuals or persist binding receipts.

From the repository root, with the matching package installed, run the complete checked-in request example:

agent-estimate estimate --spec examples/estimate-request.yaml --format json

The JSON includes "schema_version": "agent-estimate/report/v1", assigns Add input validation to Codex, and reports forecast.basis: expected-wall. The example's 90-minute admission cap does not determine its expected minutes. --spec emits the versioned report; library callers can construct the separate ForecastRecord with forecast_from_report in agent_estimate.contract.duration.

--spec accepts one full EstimateRequest containing task_spec, execution_profile, and admission, plus an optional token_prior. It can be combined with --config, --format, --compact, and --title. Put task facts, scope, and modifiers in the request; alternate input sources and history flags cannot be combined with --spec. Conflicts and invalid fields exit 2. It does not read ambient data.json history. The named agent must exist in the selected fleet and satisfy every required capability. config_profile records provenance; --config selects the actual fleet file. This single-task CLI path requires empty dependency_task_ids and execution_profile.estimate_multiplier: 1.0; use the configured agent's estimate_multiplier for profile adjustments.

Context identity belongs to execution_profile.context.context_key. An explicit modifiers.warm_context takes precedence: pairing it with context.implicit_co_dispatch: true is rejected to prevent double counting. Review intent is additive: supported plans are no review, one or two standard or complex rounds, or three standard rounds. Unsupported plans exit 2.

Expected values and caps. Reports label duration expected-wall, with source and as_of provenance (an unknown date stays null). Expected wall minutes include work and additive review. Score matching actual wall minutes against independent expected minutes, never declared_cap_minutes or a cap divided by guessed headroom. File expectations likewise come from task scope, not file caps. The validate command uses actual_total_minutes for expected-wall observations and actual_work_minutes for expected-work; cap-only and cap-derived inputs are rejected. Wall scoring is report-only in the current calibration store. Legacy estimated_minutes means expected work only, and calibrate --basis expected-work is an explicit attestation that every stored estimate is expected work rather than a cap; inspect the rows before using it. Without that attestation, calibrate exits 2 with guidance on stderr.

Token honesty. Typed forecasts default to tokens.basis: unavailable, with null expected_tokens_total, expected_tokens_output and expected_tokens_cache_read. Total means processed tokens including cache carry; output and cache-read tokens are separate counts included in total. A caller-supplied prior uses basis: local-policy, a source, date, population, and a mandatory population mismatch warning. An absent count stays unavailable; zero is a supplied count. A caller can also pass its own observed tokens per closed leg with --token-observations; the request's task-type × execution-profile segment then reports basis: measured at five or more legs, as a shrunk log-median that names the segment, its n and the observation window. JSON includes forecast.tokens when a prior or obs