Epoch
Epoch is a time estimation MCP server that gives AI agents grounded, data-driven scheduling capabilities across 25 tools, replacing guesswork with established estimation methods.
Time & Calendar Operations
Get current time in any IANA timezone, convert timestamps, and parse human-readable durations (e.g.,
2h30m,1w3d)Add or count business days with public holiday support for US, UK, FR, DE, and JP
Estimation Methods
PERT three-point estimation with confidence intervals and urgency scoring
COCOMO II LLM-adapted software sizing returning nominal and AI-adjusted person-months
Sprint velocity forecasting from historical sprint data
Critical Path Method (CPM) with slack per task and merge-bias adjustment
Monte Carlo simulation for probabilistic schedule risk (P10/P50/P80/P95)
Analytics & Reference Class Forecasting
Data-driven estimates from 126,223+ real task data points with planning fallacy correction
Classify free-text task descriptions and auto-delegate to reference class forecasting
Compute team-specific correction factors from historical estimated vs. actual data
Map LLM token budgets to wall-clock time for 12 model families
Cost & Risk Analysis
Estimate token costs and wall-clock time for LLM API calls by model
Side-by-side model comparison by cost, speed, and quality
Schedule risk scoring with confidence intervals (P50/P80/P95)
Validate COCOMO estimates against 195–240 real historical projects (NASA93, COCOMO81, etc.)
Feedback & Self-Improvement
Record actual hours against previous estimates to calibrate future accuracy
Batch-record up to 500 actuals at once
Track accuracy trends over time (sliding-window MAPE by tool/task type)
Monitor feedback loop health and self-improvement readiness
All self-improvement data stored locally and privately, with optional opt-in for anonymized community sharing
Epoch -- Time Estimation MCP Server
Epoch helps AI agents understand time.
AI can write code, analyze data, and build apps -- but it can't tell you how long something will take, what it'll cost, or whether a deadline is realistic. Epoch fixes that.
Show Me
You: "How long will a 15,000 line project take with a small team?"
Claude (using Epoch):
COCOMO II nominal: 100 person-months (traditional team)
AI-adjusted: 9 person-months (LLM-assisted workflow)
Schedule risk: medium (MAPE 15%, based on 28 historical features)
Cost estimate (Claude Sonnet): ~$340 in API tokensYou: "How many working days between now and launch?"
Claude (using Epoch):
Start: May 1, 2026
End: July 15, 2026
Business days: 54
Weekend days: 16
Holidays: 1 (Independence Day)
Total calendar days: 75You: "Which AI model should we use for a 50k-token job?"
Claude (using Epoch):
gemini-2.0-flash: $0.02 -- fast, budget-friendly
gpt-4o-mini: $0.02 -- fast, budget-friendly
gemini-2.5-pro: $0.37 -- standard, high quality
claude-sonnet-5: $0.57 -- standard, high quality
Recommendation: gemini-2.0-flash for cost, claude-sonnet-5 for qualityRelated MCP server: Calq MCP
Why Epoch?
Every AI agent hallucinates timelines. "This should take about 2 hours" becomes 2 days. Epoch gives AI grounded, data-driven estimates instead of guesses. It packages established estimation methods (PERT, COCOMO II, Monte Carlo, reference class forecasting) into 25 tools any AI can call -- so your assistant stops guessing and starts calculating.
Works out of the box. Epoch ships with a bundled reference database built from 126,223 real data points across task types, complexity levels, and estimation tools. You get accurate estimates from day one — no data collection or account setup required. If you choose to record your actuals, Epoch's self-improvement engine learns your patterns and gets even more precise over time.
What is MCP?
MCP (Model Context Protocol) is how AI assistants like Claude connect to external tools. Think of it like a plugin system -- you add Epoch with one command, and suddenly your AI assistant can estimate timelines, calculate business days, compare model costs, and predict whether your project will finish on time.
Quick Start
30-second setup -- works in Claude Code, Cursor, VS Code, and Windsurf:
claude mcp add epoch -- npx @kyanitelabs/epochThat's it. Your AI assistant now has 25 time estimation tools.
Or add it to your project's .mcp.json:
{
"mcpServers": {
"epoch": {
"command": "npx",
"args": ["@kyanitelabs/epoch"]
}
}
}Agent Skill
Epoch also ships a public agent skill at skills/epoch/SKILL.md. Use $epoch in compatible agent hosts when you want the agent to choose the right Epoch MCP or CLI workflow for time estimates, business-day math, model-cost comparison, schedule risk, and estimate-vs-actual feedback.
What Can Epoch Do?
What you want | What Epoch does | No jargon |
"How long will this take?" | Gives you a realistic estimate with best/worst case ranges | Estimates |
"Can we hit this deadline?" | Tells you if your timeline is realistic or risky | Schedule risk |
"How much will the AI calls cost?" | Calculates token costs across 12 AI models side-by-side | Cost comparison |
"How many business days between now and launch?" | Counts days excluding weekends and holidays (5 countries) | Calendar math |
"Are our estimates getting better?" | Tracks your accuracy over time and auto-corrects | Self-improving |
"What model should we use?" | Compares speed, cost, and quality across all major AI models | Model comparison |
Technical Reference
Everything below is for developers who want to understand the internals, use the CLI or REST API, or contribute to Epoch.
Architecture
Six-layer design with 25 tools for time estimation, scheduling, cost analysis, and feedback:
Layer | Purpose | Tools |
1. Core Temporal | Time, timezones, duration, date math |
|
2. Calendar Math | Business days, holidays (US/UK/FR/DE/JP) |
|
3. Estimation | PERT, COCOMO II, sprint, CPM, Monte Carlo |
|
4. Analytics | Reference class, context classification, calibration, token-time bridge |
|
5. Cost & Risk | Token cost, model comparison, accuracy trends, risk, COCOMO validation |
|
6. Feedback | Record actuals, track pending estimates, batch operations, health checks |
|
Tool Reference
Layer 1 -- Core Temporal
get_current_time -- Current wall-clock time in any IANA timezone
Input: { timezone: "America/New_York" }
Output: {
iso: "2026-05-01T08:30:00.000-04:00",
humanReadable: "Fri, May 1, 2026, 8:30 AM EDT",
timezone: "America/New_York",
utcOffset: "-04:00"
}convert_timezone -- Convert a timestamp between IANA timezones
Input: { timestamp: "2026-05-01T12:00:00Z", target_tz: "Asia/Tokyo" }
Output: {
iso: "2026-05-01T21:00:00.000+09:00",
timezone: "Asia/Tokyo",
utcOffset: "+09:00",
humanReadable: "Fri, May 1, 2026, 9:00 PM JST"
}parse_duration -- Parse human-readable duration strings
Input: { duration_string: "2h30m" }
Output: {
input: "2h30m",
totalSeconds: 9000,
humanReadable: "2 hours 30 minutes"
}time_math -- Date arithmetic operations
Input: { operation: "add_days", date: "2026-05-01", value: 7 }
Output: {
result: "2026-05-08T00:00:00.000Z",
operation: "add_days",
input: "2026-05-01"
}Supported operations: add_days, add_business_days, diff, convert_tz, parse_nl, format_duration
Layer 2 -- Calendar Math
add_business_days -- Add N business days with holiday awareness (US, UK, FR, DE, JP)
Input: { start_date: "2026-05-01", days: 5, country: "US" }
Output: {
startDate: "2026-05-01",
endDate: "2026-05-08",
businessDays: 5,
countryCode: "US",
humanReadable: "5 business days from 2026-05-01 to 2026-05-08 (US)."
}count_business_days -- Count business days between two dates
Input: { start_date: "2026-05-01", end_date: "2026-05-15", country: "US" }
Output: {
startDate: "2026-05-01",
endDate: "2026-05-15",
businessDays: 10,
countryCode: "US",
humanReadable: "10 business days between 2026-05-01 and 2026-05-15 (US)."
}Layer 3 -- Estimation
pert_estimate -- PERT three-point estimation with confidence intervals and urgency scoring
Input: {
optimistic: 2,
most_likely: 4,
pessimistic: 12,
unit: "hours"
}
Output: {
expected: 5,
variance: 2.78,
stdDeviation: 1.67,
confidence95: [1.67, 8.33],
confidence99: [0, 10],
unit: "hours",
urgencyCategory: "medium",
humanReadable: "Expected: 5 hours. 95% confidence: 1.67 to 8.33 hours. 99% confidence: 0 to 10 hours.",
developerProfile: { mode: "ai_native", correctionFactor: 1.45 },
adjustedEstimate: 7.25
}cocomo_estimate -- COCOMO II software sizing with LLM-adapted cost drivers
Input: {
kloc: 15,
reasoning_complexity: 1.2,
context_completeness: 1.0,
transformation_impact: 0.8,
iterative_cycles: 1.5,
human_oversight: 1.2
}
Output: {
kloc: 15,
personMonthsNominal: 99.9,
personMonthsLlmAdjusted: 8.9,
effortMultipliers: {
reasoning_complexity: 1.2,
context_completeness: 1.0,
transformation_impact: 0.8,
iterative_cycles: 1.5,
human_oversight: 1.2,
product: 1.728
},
developerProfile: { mode: "ai_native", correctionFactor: 1.45 }
}LLM-adapted cost drivers include reasoning complexity, context completeness, transformation impact, iterative cycles, and human oversight requirements.
sprint_forecast -- Sprint velocity forecasting from historical data
Input: {
backlog_points: 100,
velocity_history: [20, 25, 22, 23],
sprint_length_days: 14,
hours_per_sprint: 80
}
Output: {
backlogPoints: 100,
averageVelocity: 22.5,
requiredSprints: 4.4,
pessimisticSprints: 4.9,
hoursPerPoint: 3.56,
totalHours: 355.6,
completionDays: 62,
sprintLengthDays: 14,
developerProfile: { mode: "ai_native", sprintVelocityPoints: 80, correctionFactor: 1.45 }
}critical_path -- Critical Path Method with merge-bias adjustment for parallel tasks
Input: {
tasks: [
{ name: "A", duration: 5, predecessors: [] },
{ name: "B", duration: 3, predecessors: ["A"] },
{ name: "C", duration: 4, predecessors: ["A"] }
]
}
Output: {
critical_path: ["A", "C"],
total_duration: 9,
slack_per_task: { A: 0, B: 1, C: 0 },
merge_bias_adjustment: 0
}monte_carlo_schedule -- Monte Carlo simulation with seeded PRNG for deterministic, reproducible results
Input: {
tasks: [
{ name: "A", optimistic: 2, most_likely: 4, pessimistic: 8 },
{ name: "B", optimistic: 1, most_likely: 3, pessimistic: 6 }
],
iterations: 10000
}
Output: {
p10: "5.9",
p50: "7.91",
p80: "9.39",
p95: "10.75",
riskEvents: [{ description: "Task \"A\" exceeded 1.5x PERT expected in 5% of simulations", probability: 0.05, impactDays: 3 }],
criticalPathProbability: 0.8
}Layer 4 -- Analytics
reference_class_estimate -- Reference class forecasting with planning fallacy correction
Input: {
task_type: "feature",
complexity: 3
}
Output: {
rawEstimate: 6.7,
correctedEstimate: 11.1,
correctionFactor: 1.67,
sampleSize: 126223,
baselineSource: "self-improvement",
confidence: "pessimistic",
developerProfile: { mode: "ai_native", estimationMape: 15, underestimationBias: 0.2, correctionFactor: 1.45 },
adjustedEstimate: 9.7,
note: "Correction factors from bundled reference database (126,223 samples). Record actuals to personalize further."
}Valid task_type values: feature, bugfix, refactor, migration, infrastructure, documentation, testing, design.
estimate_from_context -- Classify a free-text task description and delegate to reference class estimation
Input: {
context: "Add OAuth2 login support to the API, including refresh token rotation and a new /auth/callback endpoint"
}
Output: {
tool: "estimate_from_context",
rawEstimate: 2,
correctedEstimate: 2,
correctionFactor: 1,
sampleSize: 0,
baselineSource: "inferred_scope_medium_real_tasks",
scopeUsed: "medium",
scopeGuide: "For feature tasks: small=~2.3h, medium=~6h, large=~10.6h, xl=~17h",
classification: {
classified_task_type: "feature",
classified_complexity: 3,
confidence: "medium",
signals: ["task_type_matched:feature"],
task_type_from_hint: false,
complexity_from_hint: false
},
note: "Using reference database correction factors. Submit actuals via record_actual to improve accuracy."
}Classifies task_type and complexity from free text (an issue body, PR/diff description, or task summary) using a local, deterministic keyword/signal heuristic -- no LLM call is made. Caller-supplied task_type/complexity hints always override the classification. The resolved inputs are then delegated to the same reference-class-forecasting path used by reference_class_estimate, so the response carries the same estimate fields plus a classification provenance block explaining how the tool read the context. When classification confidence is low, an additional lowConfidenceNote field is returned rather than silently guessing.
calibrate_estimates -- Team-specific accuracy calibration from historical estimated vs actual data
Input: {
task_type: "feature",
team_id: "backend"
}
Output: {
correctionFactor: 1.45,
accuracyTrend: "stable",
velocityTrend: "stable",
recommendations: [
"Using reference database correction factor (1.45x) — personalized from 126,223 samples.",
"Record actuals via POST /v1/feedback/record-actual to refine for your team's patterns."
]
}token_time_bridge -- Map LLM token budgets to wall-clock time for 12 model families
Input: {
tokens: 50000,
model: "claude-sonnet-4-20250514",
tool_calls: 10,
reasoning_depth: "deep"
}
Output: {
estimatedSeconds: 697,
estimatedMinutes: 11.6,
confidence: "likely",
urgency: "short",
breakdown: {
promptTokens: 15000,
completionTokens: 35000,
toolOverheadSeconds: 2
}
}Layer 5 -- Cost & Risk
token_cost_estimate -- Token cost estimation for LLM API calls
Input: {
tokens: 50000,
model: "claude-sonnet-5"
}
Output: {
tokens: 50000,
model: "claude-sonnet-5",
estimatedSeconds: 695,
estimatedMinutes: 11.6,
estimatedCost: 0.57,
costBreakdown: { inputCost: 0.045, outputCost: 0.525, toolCallOverheadCost: 0 },
confidence: "likely"
}compare_models -- Side-by-side cost and capability comparison across LLM models
Input: {
tokens: 50000,
sort_by: "cost"
}
Output: {
tokens: 50000,
models: [
{ model: "gemini-2.0-flash", estimatedCost: 0.0155, qualityTier: "fast", tokensPerSecond: 230 },
{ model: "deepseek-v3", estimatedCost: 0.0189, qualityTier: "standard", tokensPerSecond: 97 },
{ model: "gpt-4o-mini", estimatedCost: 0.0233, qualityTier: "fast", tokensPerSecond: 180 }
],
sortBy: "cost"
}accuracy_trend -- Track estimation accuracy over time from recorded feedback data
Input: { team_id: "backend", window_size: 50 }
Output: {
overallTrend: "improving",
currentMape: 26.5,
industryBaselineMape: 25,
totalEstimates: 1049,
totalWithActuals: 1049,
windows: [{ period: "Window 1 (estimates 1-50)", mape: 32, bias: 5.3, sampleSize: 50 }]
}schedule_risk -- Schedule risk scoring for project timelines
Input: {
estimated_hours: 40,
task_type: "feature"
}
Output: {
estimatedHours: 40,
riskLevel: "low",
confidenceIntervals: { p50: 40, p80: 45.1, p95: 49.9 },
historicalAccuracy: { mape: 15, sampleSize: 126223 },
recommendation: "Low risk. Estimate is within normal variance.",
humanReadable: "Schedule risk: low. MAPE: 15% (based on 0 historical records). Confidence intervals: p50=40h, p80=45.1h, p95=49.9h."
}cocomo_validate -- Validate COCOMO II estimates against reference data
Input: {}
Output: {
projectsEvaluated: 182,
mape: 85.55,
bias: 53.5,
byProjectType: {
organic: { mape: 86.57, count: 22 },
semidetached: { mape: 84.75, count: 106 },
embedded: { mape: 86.71, count: 54 }
},
recommendedAdjustments: []
}ai_native Mode
Epoch tools support dual estimation modes to account for the fundamentally different velocity of AI-assisted vs human-only development.
When ai_native=true (default), tools use Epoch's reference database with tool-aware correction factors. These baselines reflect AI agent workflows: faster iteration, higher output volume, and different error profiles.
When ai_native=false, tools apply human developer baselines:
Parameter | Human Baseline | AI-Native Baseline |
Feature development | 14 calendar days (industry data) | 5.7h median (126K+ real tasks) |
Bug fix turnaround | 72 hours (industry data) | 6.2h median (1,498 matched pairs) |
Sprint velocity | 35 story points (industry data) | 80 story points |
Estimation accuracy (MAPE) | 25% (Jorgensen 2004) | 15% (from AI-native profiles) |
Correction factor | 1.8x (industry standard) | 1.07-1.45x (from reference DB) |
Tools that support ai_native: pert_estimate, cocomo_estimate, sprint_forecast, reference_class_estimate, schedule_risk.
Hybrid workflows: ai_native accepts a float from 0.0 (fully human) to 1.0 (fully AI-native). Values like 0.5 produce interpolated profiles for mixed AI/human workflows. Boolean values (true/false) remain supported for backward compatibility.
Self-Improvement Engine
Epoch learns your patterns the more you use it. The bundled reference database already contains 126,223 data points with correction factors tuned from real estimate-vs-actual pairs across 8 task types — it works accurately on day one.
If you record your actuals, Epoch personalizes further:
Estimate -- Generate an initial estimate with any estimation tool
Record -- Track the actual outcome (
record_actual)Learn -- Self-improvement computes personalized correction factors from your data
Improve -- Future estimates apply your team's actual patterns
Trend --
accuracy_trendtracks whether your accuracy is improving over time
Your estimates + your actuals -> Your correction factors -> Better estimates -> RepeatThe loop can close itself. Recording actuals is the step everyone forgets, so Epoch can do it for you: epoch auto-actuals --session <id> records wall-clock-derived actuals for a session's unfinished estimates (agent hosts can wire it into a session-end hook). Auto-recorded actuals are sanity-bounded (0.05–12h, <10x the estimate), provenance-labeled auto_wallclock, never overwrite a real actual, and feedback_health reports them separately (byProvenance) so automated data can't silently skew your calibration.
Estimates lead with honest ranges. When at least 5 matched pairs exist for a task type, pert_estimate and reference_class_estimate open with a calibrated 80% interval ("Expected 1.6–4.2 hours (80% confidence interval); point estimate 2.5 hours") derived from your own historical estimate-vs-actual ratios — and say plainly when there isn't enough data yet.
The engine detects systematic biases (chronic under-estimation, accuracy degradation) and surfaces actionable recommendations.
You do not need to share data with anyone for this to work. Self-improvement runs entirely locally using your own ~/.epoch/ data.
The correction loop, measured
The self-improvement claim above isn't marketing copy -- it's backed by a runnable receipt. scripts/backtest-pert-correction.mjs makes a read-only temp copy of your ~/.epoch ledger, chronologically splits matched pert_estimate (estimate, actual) pairs 80/20, trains the learned per-(tool, task_type) correction factor on the training split only, and reports MdAPE on the held-out test split it never trained on:
npx tsx scripts/backtest-pert-correction.mjsMeasured on the maintainers' production ledger (697 held-out matched pairs at time of writing): MdAPE improved from 105.2% (uncorrected) to 80.5% (learned correction) on data the correction factor never saw during training. This is the mechanism EPOCH_PERT_LEARNED_CORRECTION gates behind before it's recommended on by default -- the script also checks that the corrected median actual/predicted ratio lands in [0.7, 1.3], and reports HOLD (not recommended yet) when that second guard hasn't cleared, so the flag doesn't ship as "on" until both hold. Run the script against your own ledger for your own numbers; they move as more actuals get recorded, which is the point.
reference_class_estimate's correction factors are the same learned mechanism applied to a different tool. Track its current calibration with epoch data status or feedback_health (per-tool MAPE/MdAPE, bias, and trend), or generate a full calibration decision-surface report with node scripts/build-calibration-dashboard.mjs -- also strictly read-only against your ledger.
Data Pipeline
Epoch uses a three-layer data strategy so it's accurate from the start and gets better over time:
1. Bundled reference database (works immediately, no setup): Epoch ships with a pre-built reference database containing 126,223 data points across 8 task types and 5 complexity levels. Correction factors are computed from real estimate-vs-actual pairs. You get accurate estimates the moment you install it.
2. Local self-improvement (automatic, private):
As you use Epoch and record actuals, the self-improvement engine recalibrates correction factors from your data. This runs entirely locally in ~/.epoch/ — nothing leaves your machine. The engine triggers automatically every 100 tool calls or 24 hours.
Auto-recording: Use
scripts/auto-record-actual.mjsto automatically record actual time against pending estimates.Source tagging: Set
EPOCH_SOURCE=<project-name>to tag estimates by project.Inspect your data:
epoch data whereandepoch data statusshow what's stored locally.
3. Community contributions (optional, opt-in): You can optionally share anonymized data to help improve baselines for all users. Community data is stripped of all identifying information — only task type, complexity, estimated hours, actual hours, and date remain. See CONTRIBUTING-data.md for format and privacy requirements.
epoch share-data --validate --description "My anonymized estimation data"This is completely optional. Epoch works great without it.
Surfaces
Epoch exposes the same 25 tools through three interfaces:
Surface | Transport | Use Case |
MCP Server | stdio | Claude Code, Cursor, VS Code, Windsurf |
CLI | Direct invocation | Scripts, CI/CD, quick lookups |
REST API | HTTP (Hono) | Web apps, AI agents, integrations |
Default behavior: running epoch with no arguments starts the MCP stdio server.
CLI
# PERT estimate
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --unit hours
# Token-to-time bridge
epoch token-time-bridge --tokens 50000 --model claude-sonnet-4-20250514
# Monte Carlo simulation
epoch monte-carlo-schedule --tasks '[{"name":"A","optimistic":2,"most_likely":4,"pessimistic":8}]'
# COCOMO II estimate
epoch cocomo-estimate --kloc 15 --project-type organic
# Schedule risk score
epoch schedule-risk --tasks '[{"name":"A","duration":5,"risk_level":"high"},{"name":"B","duration":3,"risk_level":"low"}]'
# List all tools
epoch list-tools
# Pretty table output
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --prettyREST API
# Start the server
epoch serve --port 3099
# or: EPOCH_TRANSPORT=http EPOCH_PORT=3099 epoch
# Call any tool
curl -X POST http://localhost:3099/v1/tools/pert_estimate \
-H "Content-Type: application/json" \
-d '{"optimistic": 2, "most_likely": 4, "pessimistic": 12, "unit": "hours"}'
# Health check
curl http://localhost:3099/health
# OpenAPI spec
curl http://localhost:3099/openapi.jsonAgent-First
Epoch is built for agents as first-class callers, not humans typing in a terminal as an afterthought.
Why agents need time-sense. An LLM has no grounded sense of duration or cost -- it will say "quick fix" for a two-day migration and "big project" for a two-hour config change with equal confidence, because it has no feedback loop telling it otherwise. That's fine for a chat answer; it breaks down the moment an agent is planning multi-step work, sequencing a sprint, or deciding whether a deadline is realistic. Epoch gives the agent a calculator instead of a guess: PERT/COCOMO/Monte Carlo math, a reference-class baseline built from real task data, and a feedback loop that corrects itself as the agent (or its operator) records actuals.
EPOCH_TELEMETRY=1 for headless/agent operators. Telemetry is off by default and requires informed consent. For a human at a terminal, that consent is epoch telemetry enable, which shows the data and asks for confirmation. An agent should never be the one clicking "yes" to that prompt on its own behalf -- there is deliberately no MCP tool that enables telemetry, so an agent cannot self-consent. For headless or agent-operated deployments, the operator opts in out-of-band by setting EPOCH_TELEMETRY=1 in the server's environment (for example, the env block of the MCP server config) before the agent ever starts. Consent stays with the human who configures the deployment, not the agent that runs inside it.
MCP client qualification. Epoch's telemetry schema (v2) records client_name/client_version from the MCP clientInfo your host reports at connection time, plus transport (stdio/http). This is agent qualification, not agent identification: it lets aggregate accuracy stats count "5.7h median across N agent-driven feature estimates" as first-class agent data rather than lumping it in with anonymous CLI usage, without adding any new per-user identifying signal. MCP clients that report clientInfo (Claude Code, Cursor, and most current hosts do) get this for free; clients that don't are still fully functional, they just show up as client_name: null.
Epoch also provides built-in discoverability endpoints so agents can find and use the HTTP API without prior configuration:
Endpoint | Description |
| OpenAI plugin manifest |
| LLM-consumable documentation |
| OpenAPI 3.1 specification |
| Service health and version |
Installation
git clone https://github.com/KyaniteLabs/Epoch.git
cd Epoch
pnpm install
pnpm run buildDevelopment
pnpm test # Run the Vitest suite
pnpm run build # Build with tsup
pnpm run typecheck # TypeScript strict mode check
pnpm run dev # Run development server
pnpm run inspector # Open MCP Inspector for interactive testingTech Stack
Runtime: Node.js 20+ (ESM)
Language: TypeScript 5.8 (strict mode,
noUncheckedIndexedAccess,verbatimModuleSyntax)Validation: Zod 3.24 with
.describe()on every fieldMCP SDK:
@modelcontextprotocol/sdk1.12+HTTP: Hono (lightweight, multi-runtime)
CLI: Commander.js
Date Handling:
date-fns4.x +date-fns-tz3.xBuild:
tsup(ESM output)Testing:
vitest3.x with v8 coverage (97% statements, 88% branches)
Configuration
Variable | Default | Description |
|
| Transport mode: |
|
| HTTP server port |
|
| HTTP server bind address |
|
| Data directory for feedback and self-improvement |
|
| Community data directory |
|
| Max requests per minute per IP (HTTP only) |
| (none) | Project/source tag attached to estimate records |
|
| Set to |
| (none) | Override the configured telemetry receiver endpoint for status/submission. |
Telemetry & Privacy
Epoch can share anonymized estimate/actual pairs to improve accuracy for all users. This is off by default and requires explicit opt-in.
Agent-operator consent model: there is deliberately no MCP tool that enables telemetry -- an agent must not be able to self-consent on a human's behalf. Humans opt in interactively with epoch telemetry enable. Agent/headless operators opt in out-of-band by setting EPOCH_TELEMETRY=1 in the server's environment before the agent starts (see Agent-First). Either way, consent belongs to the person who configures the deployment.
epoch telemetry enable # Opt in (shows exactly what will be shared)
epoch telemetry preview # Preview anonymized data before enabling
epoch telemetry status # Show current settings
epoch telemetry set-endpoint --endpoint https://your-server.example.com/v1/telemetry
epoch telemetry submit # Submit queued anonymized records to the configured endpoint
epoch telemetry disable # Opt out
epoch telemetry export # Export all local data as anonymized JSONWhat is shared: task type, complexity, tool name, estimated hours, actual hours, ratio, date (YYYY-MM-DD only).
What is NEVER shared: project names, notes, team IDs, IP addresses, timestamps with time-of-day, source code, descriptions.
See Privacy Policy and Telemetry Documentation for full details.
Where Your Data Lives
By default, Epoch stores local data under ~/.epoch/ or EPOCH_DATA_DIR. Your local usage data is not automatically committed to GitHub and is not automatically submitted anywhere.
epoch data where # Show local data file locations
epoch data status # Show data file counts, feedback health, telemetry configSharing Data
Use epoch share-data --validate to create a community-data JSON file suitable for data/community/. Review the file before opening a PR.
epoch share-data --description "Anonymized Epoch usage export" --validateMachine Labels
windows-receiver is a historical label. The current receiver host is ubuntu-receiver at 100.113.174.74. See docs/ops/machines.md for the full inventory.
License
MIT License. See LICENSE for full terms.
Part of KyaniteLabs
More from KyaniteLabs. Related projects:
mcp-video — guardrailed video-editing MCP server for AI agents
DialectOS — Spanish dialect localization MCP server & CLI
checkyourself — local-first production-readiness checks for AI-built code
→ More at kyanitelabs.tech
Maintenance
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KyaniteLabs/Epoch'
If you have feedback or need assistance with the MCP directory API, please join our Discord server