agent-estimate 0.2.0
Effort estimation for AI coding agents — PERT + METR + wave planning
Requires Python: >=3.10
Keywords: agents, ai, estimation, pert, planning

# agent-estimate

[![PyPI Version](https://img.shields.io/pypi/v/agent-estimate)](https://pypi.org/project/agent-estimate/)
[![Python Versions](https://img.shields.io/pypi/pyversions/agent-estimate)](https://pypi.org/project/agent-estimate/)
[![License](https://img.shields.io/pypi/l/agent-estimate)](https://github.com/haoranc/agent-estimate/blob/main/LICENSE)
[![CI](https://github.com/haoranc/agent-estimate/actions/workflows/ci.yml/badge.svg)](https://github.com/haoranc/agent-estimate/actions/workflows/ci.yml)

`agent-estimate` is a CLI for estimating delivery time of AI-agent work using:

- three-point PERT estimates
- METR-style model reliability thresholds
- dependency-aware wave planning
- explicit review overhead modes (`none`, `standard`, `complex`)
- non-coding task type estimation (brainstorm, research, config, docs)
- multi-agent session estimation

## Installation

Install from PyPI:

```bash
pip install agent-estimate
```

Install from source for development:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
```

## Quick Start

Estimate one task from the command line:

```bash
agent-estimate estimate "Implement OAuth login flow"
```

Show version:

```bash
agent-estimate --version
```

## Claude Code Plugin

`agent-estimate` includes a Claude Code plugin for interactive estimation in Claude Code sessions.

### Install

**Option 1 — From marketplace:**

```
/plugin marketplace add haoranc/agent-estimate
/plugin install agent-estimate@agent-estimate-marketplace
```

**Option 2 — Local development:**

```bash
claude --plugin-dir /path/to/agent-estimate
```

**Prerequisite**: The CLI must be installed first: `pip install agent-estimate`

### Plugin Usage

```
/estimate Add a login page with OAuth
/estimate --file spec.md
/estimate --issues 1,2,3 --repo myorg/myrepo
/validate-estimate observation.yaml
/calibrate
```

## Codex Skill Layout

For Codex-oriented tooling, this repo includes a Codex-specific skill at:

- `.agent/skills/estimate/SKILL.md`

The Claude plugin skill remains at:

- `skills/estimate/SKILL.md`

Both skills cover the same CLI capabilities (`estimate`, `validate`, `calibrate`) but are phrased for their respective ecosystems.

## Usage Examples

Estimate tasks from a text file:

```bash
agent-estimate estimate --file tests/fixtures/tasks_multi.txt
```

Output JSON for downstream tooling:

```bash
agent-estimate estimate "Refactor auth pipeline" --format json
```

Estimate directly from GitHub issues:

```bash
agent-estimate estimate --repo haoranc/agent-estimate --issues 11,12,14
```

Validate estimate vs observed outcome and persist to calibration DB:

```bash
agent-estimate validate tests/fixtures/observation_valid.yaml --db ~/.agent-estimate/calibration.db
```

## TestPyPI Validation

Manual local publish (requires TestPyPI API token configured for `twine`):

```bash
python -m build
python -m twine check dist/*
python -m twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple agent-estimate
```

Or run the GitHub Actions workflow `TestPyPI Dry Run` to publish and smoke-test install end-to-end.

## Default METR Thresholds

The default model thresholds are defined in `src/agent_estimate/metr_thresholds.yaml`:

| Model        | p80 threshold |
| ------------ | ------------- |
| Opus         | 90 minutes    |
| GPT-5.3      | 60 minutes    |
| GPT-5        | 50 minutes    |
| GPT-5.2      | 55 minutes    |
| Gemini 3 Pro | 45 minutes    |
| Sonnet       | 30 minutes    |

## Agent Config Example

Pass a custom config file with `--config`:

```yaml
agents:
  - name: Claude
    capabilities: [planning, implementation, review]
    parallelism: 2
    cost_per_turn: 0.12
    model_tier: frontier
  - name: Codex
    capabilities: [implementation, debugging, testing]
    parallelism: 3
    cost_per_turn: 0.08
    model_tier: production
settings:
  friction_multiplier: 1.15
  inter_wave_overhead: 0.25
  review_overhead: 0.2
  metr_fallback_threshold: 45.0
```

Then run:

```bash
agent-estimate estimate "Ship packaging flow" --config ./my_agents.yaml
```

## Contributing

1. Fork and create a branch from `main`.
2. Install dev dependencies:
   ```bash
   pip install -e '.[dev]'
   ```
3. Run checks:
   ```bash
   ruff check .
   pytest -q
   ```
4. Open a pull request with a clear summary and test evidence.

## License

MIT