Task Cost Estimator

Estimate the cost, runtime, and token footprint of AI coding-agent tasks before you run them.

Task Cost Estimator (tce) is a small CLI for developers who use agentic coding tools such as Codex, Claude Code, Cursor, Copilot, and similar assistants. It asks a low-cost estimator model to predict how expensive a task may be on a target model, then formats the result as a readable terminal report or machine-readable JSON.

It is designed for solo developers, maintainers, and teams who want a quick "should I run this now?" signal before starting a large refactor, debugging session, research task, or repository-wide change.

Features

• Estimate task cost, runtime, token usage, complexity, and confidence.
• Compare target models using local pricing data.
• Track actual task history and calibrate future estimates.
• Run a network benchmark to improve time estimates.
• Output compact text for hooks or JSON for automation.
• Keep secrets local through environment variables or ~/.tce/config.json.

Install

git clone https://github.com/359392475-blue-sky/task-cost-estimator.git
cd task-cost-estimator
npm install
npm link

You need Node.js 18 or newer.

Configure

Use an API key through the environment:

export ANTHROPIC_API_KEY="..."
# or
export OPENROUTER_API_KEY="..."

Or store it locally:

tce config --anthropic-key "..."
tce config --openrouter-key "..."

Local configuration is written to ~/.tce/config.json, not to this repository.

Usage

tce "refactor the auth module to use JWT"
tce "fix the mobile login bug" --model claude-sonnet-4-6
echo "add dark mode to the dashboard" | tce estimate

JSON output:

tce "add unit tests for the billing service" --json

Strict mode for automation:

tce "migrate the database schema" --strict

Record actual task results for calibration:

tce record \
  --query "fix the mobile login bug" \
  --input-tokens 42000 \
  --output-tokens 9000 \
  --time 480 \
  --rounds 7 \
  --cost 0.74

tce calibrate

Commands

Command	Purpose
tce "task"	Estimate a task directly.
tce estimate "task"	Explicit estimate command.
tce record --query "..."	Save actual task data.
tce calibrate	Adjust estimates from history.
tce benchmark	Measure provider latency and token speed.
tce config	View or update local config.
tce models	List supported target models and prices.
tce history	View recent task records.

Roadmap

• v0.1 CLI proof of concept.
• Local pricing table and model listing.
• History-based calibration.
• More estimator providers.
• Better built-in pricing update workflow.
• Shell hook examples for Codex and Claude Code.
• Confidence bands from historical error rates.

Contributing

Contributions are welcome, especially:

• Pricing updates.
• Provider integrations.
• More tests for formatting, pricing, and calibration.
• Better docs for shell integration.
• Real-world calibration examples with private details removed.

See CONTRIBUTING.md.

Security

Do not commit API keys. Prefer environment variables or local ~/.tce/config.json. See SECURITY.md for vulnerability reporting.

License

MIT License. See LICENSE.

Maintainer

Maintained by Wang Junjie.