Epoch is a "time estimation MCP server" positioned to help AI agents understand time. It is aimed at engineering leads, agents, and planners, and is suited to scenarios requiring calibrated duration estimates. AI can write code, analyze data, and build applications, but it struggles to judge how long a piece of work will take, how much it will cost, and whether a deadline is realistic; Epoch attempts to replace guesswork with data-backed estimates.
Main capabilities
Epoch packages established estimation methods into 26 tools, covering six layers:
- Core time tools: get the current time in any IANA time zone, time zone conversion, parse human-readable duration strings, date arithmetic (add_days, add_business_days, diff, convert_tz, parse_nl, format_duration).
- Calendar calculations: add business days with holiday awareness, count business days between two dates, with support for US, UK, France, Germany, and Japan holiday sets.
- Estimation: PERT three-point estimation (including confidence intervals and urgency scoring), COCOMO II software sizing estimation (including cost drivers adapted for LLMs, such as reasoning complexity, context completeness, transformation impact, iteration cycle, and human oversight requirements), sprint velocity forecasting based on historical data, critical path method (with deviation adjustment when merging parallel tasks), and Monte Carlo schedule simulation (seeded PRNG, with deterministic and reproducible results).
- Analysis: reference class forecasting (including planning fallacy correction), estimation from context (performing local deterministic keyword/signal classification on free-text task descriptions and then delegating to reference class estimation, without calling an LLM), team-specific accuracy calibration, and mapping LLM token budgets to actual time (covering 16 model families).
- Cost and risk: token cost estimation for LLM API calls, side-by-side comparison of cost and capability across models, tracking estimation accuracy over time, schedule risk scoring for project timelines, validating COCOMO II estimates with reference data, and benchmarking multiple COCOMO variants.
How to use
MCP (Model Context Protocol) is the way AI assistants such as Claude connect to external tools, and can be thought of as a plugin system. After adding Epoch, an AI assistant can estimate timelines, calculate business days, compare model costs, and predict whether a project will be completed on schedule. Setup is claimed to take 30 seconds and is available in Claude Code, Cursor, VS Code, Windsurused in f, and can also be added to the project's .mcp.json. The repository also includes a public agent skill file skills/epoch/SKILL.md; in a compatible agent host, use $epoch to let the agent choose the correct Epoch MCP or CLI workflow.
At the technical level, in addition to MCP, a CLI and REST API are also provided. Data is stored locally in ~/.epoch/ by default, and the self-improvement engine is automatically triggered every 100 tool calls or every 24 hours. You can view local storage with epoch data where and epoch data status, and use EPOCH_SOURCE=<project name> to tag estimates by project.
Data and Calibration
Epoch uses a three-layer data strategy: a built-in reference database (maintainer estimates versus actual history, curated public research baselines, 117,791 tool usage/latency telemetry samples covering 8 task types and 5 complexity levels, ready to use out of the box); local self-improvement (local recalibration after recording actual values, with data never leaving the machine); and optional anonymous community contributions.
Ways to record actual values include: record_actual; epoch auto-actuals --session <id> automatically records actual values for incomplete estimates based on session wall-clock time. Automatically recorded values have plausibility bounds (0.05-12 hours, within 10x below the estimate), are labeled with the source auto_wallclock, and do not overwrite true actual values; epoch mine-git --repo <path> --since <date> associates pending estimates with closed work through local, offline, read-only git history, derives cycle time windows, and records them with the sources git_derived / git_derived_review_inclusive, also with bounds and without overwriting true values.
When at least 5 matched estimate-actual pairs exist for a task type, PERT and reference-category estimates are presented with calibrated 80% intervals, and clearly state whether the data is sufficient. The engine can detect systematic bias and provide suggestions. The repository provides a runnable regression script scripts/backtest-pert-correction.mjs to verify the correction effect: on the maintainer's production ledger (697 held-out matched pairs), MdAPE improves from 105.2% (uncorrected) to 80.5% (learned correction).
Applicable Scenarios and Limitations
Applicable scenarios include: estimation for mixed workflows where AI-assisted and manual development coexist (ai_native accepts a floating-point value from 0.0 to 1.0 to represent the degree of AI involvement, and is also compatible with boolean values); sprint velocity prediction; LLM token cost and time mapping; project schedule risk analysis; and long-term tracking of team estimation accuracy.
In terms of limitations: the correction factors of the built-in reference database come from the maintainer's history, so initial accuracy is limited; self-improvement requires users to continuously record actual values in order to improve significantly; estimation results depend on the input task type and complexity classification, and free-text classification is a local heuristic, so when confidence is low it returns a prompt rather than silently guessing. Regarding whether it is paid, pricing, and specific platform support details, the materials do not provide information, so these are not yet clear.
