---
name: epoch
description: Use Epoch for time estimation, business-day math, PERT/COCOMO/Monte Carlo forecasting, token cost comparison, schedule risk, and estimate-vs-actual feedback. Trigger when an agent needs realistic duration, deadline, model-cost, or planning calibration instead of a vibes-based guess.
---

# Epoch

Use Epoch when a task needs grounded time, cost, schedule, or calibration answers. Epoch is both an MCP server and a CLI, with 24 tools covering temporal math, calendar math, estimation, analytics, cost and risk, and feedback.

## Start Here

- Read `../../README.md` for tool categories, MCP setup, and examples.
- Read `../../package.json` for the package name, binary name, and verification scripts.
- Use the MCP server when the host can call tools directly: `npx @kyanitelabs/epoch`.
- Use the CLI for terminal workflows: `epoch <command>` or `node dist/index.js <command>` from a built checkout.

## Workflow

1. Classify the question before choosing a tool:
   - Timezone or duration math: `get-current-time`, `convert-timezone`, `parse-duration`, `time-math`.
   - Working-day planning: `add-business-days`, `count-business-days`.
   - Task/project estimates: `pert-estimate`, `cocomo-estimate`, `sprint-forecast`, `critical-path`, `monte-carlo-schedule`.
   - Evidence-based calibration: `reference-class-estimate`, `calibrate-estimates`, `accuracy-trend`, `self-improve`.
   - Model or token economics: `token-time-bridge`, `token-cost-estimate`, `compare-models`.
   - Delivery confidence: `schedule-risk`, `cocomo-validate`.
   - Learning loop: `record-actual`, `get-pending-estimates`, `batch-record-actuals`, `feedback-health`.
2. Ask for missing quantitative inputs only when the estimate would otherwise be meaningless. Reasonable defaults are acceptable for exploratory planning, but label them as assumptions.
3. Prefer JSON output for agent workflows and table output for human summaries.
4. Record actuals when the work completes if an estimate or feedback token was produced.

## CLI Examples

```bash
epoch pert-estimate --optimistic 1 --most-likely 2 --pessimistic 5 --unit hours --format json
epoch count-business-days --start-date 2026-06-01 --end-date 2026-07-15 --country US
epoch compare-models --input-tokens 50000 --output-tokens 5000 --format table
epoch record-actual --estimate-id <feedback-token> --actual-hours 3.25 --notes "Completed with build and verification"
```

## MCP Setup

```json
{
  "mcpServers": {
    "epoch": {
      "command": "npx",
      "args": ["@kyanitelabs/epoch"]
    }
  }
}
```

## Guardrails

- Do not present an estimate as a promise. Include uncertainty, assumptions, and risk when relevant.
- Use business-day tools for calendar commitments; do not count weekdays manually.
- Use model-cost tools for LLM budget questions; do not infer current prices from memory.
- Close the loop with `record-actual` whenever possible so Epoch improves over time.