Epoch

Epoch -- 時間見積もり MCP サーバー

Epoch は、妥当性の調整された所要時間の見積もりを必要とするエンジニアリングリード、エージェント、プランナーが、PERT／参照クラスによる見積もりを作成し、実績を記録するのに役立つ時間見積もり MCP サーバーです。

要約： Epoch は時間見積もり MCP サーバーです。妥当性の調整された所要時間の見積もりを必要とするエンジニアリングリード、エージェント、プランナーに最適です。

Epoch は、AI エージェントが時間を理解するのに役立ちます。

AI はコードを書き、データを分析し、アプリを構築できますが、どれくらい時間がかかるか、いくらかかるか、期限が現実的かどうかは判断できません。Epoch がそれを解決します。

---

実際に見てみる

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 tokens

You: "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: 75

You: "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 quality

Epoch を使う理由

AI エージェントは、例外なくスケジュールを幻覚します。「2時間くらいで終わるはず」が2日になることもあります。Epoch は推測ではなく、根拠のあるデータに基づいた見積もりを AI に提供します。確立された見積もり手法（PERT、COCOMO II、モンテカルロ、参照クラス予測）を26個のツールにまとめており、あらゆる AI が利用できます。これにより、アシスタントは推測をやめ、計算を始めます。

すぐに使えます。 Epoch には、メンテナーが記録した見積もりと実績の履歴に基づくタスク種別の補正係数とスコープの基準値、および厳選された公開研究からなる参照データベースが同梱されています。また、トークンと時間の橋渡しを根拠のあるものにするため、ツール利用状況とレイテンシのテレメトリサンプルも含まれています（同梱のカナリアテストとセッションベンチマーク全体で117,791件）。データ収集やアカウント設定をしなくても、初日から妥当な見積もりを得られます。実績を記録することを選べば、Epoch の自己改善エンジンが傾向を学習し、時間とともにさらに正確になります。

MCP とは？

MCP（Model Context Protocol）は、Claude のような AI アシスタントが外部ツールに接続するための仕組みです。プラグインシステムのようなものです。コマンドを1つ実行して Epoch を追加すれば、AI アシスタントがスケジュールを見積もり、営業日を計算し、モデルのコストを比較し、プロジェクトが期限までに完了するかを予測できるようになります。

クイックスタート

30秒でセットアップできます。Claude Code、Cursor、VS Code、Windsurf で動作します。

claude mcp add epoch -- npx @kyanitelabs/epoch

これで完了です。AI アシスタントが26個の時間見積もりツールを利用できるようになります。

または、プロジェクトの .mcp.json に追加します。

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

エージェントスキル

Epoch には、公開エージェントスキル skills/epoch/SKILL.md も同梱されています。時間の見積もり、営業日の計算、モデルコストの比較、スケジュールリスク、見積もりと実績のフィードバックに適した Epoch MCP または CLI のワークフローをエージェントに選ばせたい場合は、対応するエージェントホストで $epoch を使用してください。

Epoch でできること

やりたいこと	Epoch が行うこと	平易な表現
「どのくらいかかりますか？」	現実的な見積もりを、最短・最長の範囲とともに提示します	見積もり
「この期限に間に合いますか？」	スケジュールが現実的か、リスクがあるかを知らせます	スケジュールリスク
「AI の呼び出しにはいくらかかりますか？」	16 種類の AI モデルのトークン費用を並べて計算します	費用比較
「今からリリースまでに営業日は何日ありますか？」	週末と祝日を除いて日数を数えます（5 か国）	カレンダー計算
「見積もりの精度は上がっていますか？」	時間の経過に伴う精度を追跡し、自動で補正します	自己改善
「どのモデルを使うべきですか？」	主要な AI モデルすべての速度、費用、品質を比較します	モデル比較

---

技術リファレンス

以下は、内部の仕組みを理解したい方、CLI または REST API を使いたい方、Epoch に貢献したい方向けの情報です。

アーキテクチャ

時間の見積もり、スケジューリング、費用分析、フィードバックのための 26 個のツールを備えた 6 層構成です。

レイヤー	目的	ツール
1. コア時間処理	時刻、タイムゾーン、期間、日付計算	get_current_time, convert_timezone, parse_duration, time_math
2. カレンダー計算	営業日、祝日（US/UK/FR/DE/JP）	add_business_days, count_business_days
3. 見積もり	PERT、COCOMO II、スプリント、CPM、モンテカルロ法	pert_estimate, cocomo_estimate, sprint_forecast, critical_path, monte_carlo_schedule
4. 分析	参照クラス、コンテキスト分類、較正、トークンと時間の連携、待機メカニズムによる期限	reference_class_estimate, estimate_from_context, calibrate_estimates, token_time_bridge, wait_bound
5. 費用とリスク	トークン費用、モデル比較、精度の推移、リスク、COCOMO の検証	token_cost_estimate, compare_models, accuracy_trend, schedule_risk, cocomo_validate, cocomo_ground_truth
6. フィードバック	実績の記録、保留中の見積もりの追跡、バッチ処理、健全性チェック	record_actual, get_pending_estimates, batch_record_actuals, feedback_health

ツールリファレンス

レイヤー 1 -- コア時間処理

get_current_time -- 任意の IANA タイムゾーンにおける現在の実時刻

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 -- IANA タイムゾーン間でタイムスタンプを変換します

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 -- 人が読みやすい形式の期間文字列を解析します

Input:  { duration_string: "2h30m" }
Output: {
  input: "2h30m",
  totalSeconds: 9000,
  humanReadable: "2 hours 30 minutes"
}

time_math -- 日付の算術演算

Input:  { operation: "add_days", operands: { start_date: "2026-05-01", days: 7 } }
Output: "2026-05-08"

対応する操作：add_days、add_business_days、diff、convert_tz、parse_nl、format_duration

レイヤー 2 -- カレンダー計算

add_business_days -- 祝日を考慮して N 営業日を加算します（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",
  holidaySupport: "holiday_calendar",
  humanReadable: "5 business days from 2026-05-01 to 2026-05-08 (US)."
}

count_business_days -- 2 つの日付の間の営業日数を数えます

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",
  holidaySupport: "holiday_calendar",
  humanReadable: "10 business days between 2026-05-01 and 2026-05-15 (US)."
}

どちらのツールも、成功時の出力には常に holidaySupport（対象国に組み込みの祝日セットがある場合（US/UK/FR/DE/JP）は "holiday_calendar"、それ以外は "weekends_only"）が含まれます。country は ^[A-Za-z]{2}$ に一致する必要があり、「USA」のようなコードは、内容がわかるエラーとともに拒否されます。

レイヤー 3 -- 見積もり

pert_estimate -- 信頼区間と緊急度スコアリングを備えた PERT 3 点見積もり

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",
  riskLevel: "high",
  humanReadable: "Expected 2.86–7.14 hours (80% confidence interval); point estimate 5 hours (ledger-recorded basis; adjustedEstimate 5 applies the correction factor). No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.",
  developerProfile: { mode: "ai_native", correctionFactor: 1 },
  adjustedEstimate: 5,
  rawEstimate: 5,
  correctionFactor: 1,
  n: 0,
  interval: { p50: { lower: 3.87, upper: 6.13 }, p80: { lower: 2.86, upper: 7.14 }, p90: { lower: 2.25, upper: 7.75 }, source: "pert_variance" },
  intervalNote: "No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.",
  basisNote: "Interval and point estimate are on the ledger-recorded basis (raw PERT expected × unit factor). adjustedEstimate (5 hours) additionally applies the correction factor (1) and is display-only — it is never recorded or calibrated against."
}

（蓄積されたフィードバックがない新規インストール時の例です。タスク種別に一致する除外フィルター適用後のペアが 5 件以上ある場合、interval.source は "empirical_ratio_quantile" になり、n はサンプルサイズを示し、intervalPopulation は使用された比率母集団を示します。）

cocomo_estimate -- LLM に適応したコストドライバーを用いた COCOMO II ソフトウェア規模見積もり

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 に適応したコストドライバーには、推論の複雑さ、コンテキストの完全性、変換の影響、反復サイクル、人間による監督の要件が含まれます。

sprint_forecast -- 過去のデータに基づくスプリントベロシティの予測

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 -- 並列タスクの合流バイアスを調整したクリティカルパス法

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 -- 決定論的で再現可能な結果を得るための、シード付き PRNG によるモンテカルロシミュレーション

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 10% of simulations", probability: 0.1, impactDays: 0.05 },
    { description: "Task \"B\" exceeded 1.5x PERT expected in 10% of simulations", probability: 0.1, impactDays: 0.04 }
  ],
  criticalPathProbability: null
}

（target_hours の期限が指定されない限り、criticalPathProbability は null です。指定された場合は P（合計時間 ≤ 目標時間）の実際の値になります。riskEvents[].impactDays はタスクごとの予想超過日数で、影響度順に並べられます。）

レイヤー 4 -- 分析

reference_class_estimate -- 計画錯誤を補正した参照クラス予測

Input:  {
  task_type: "feature",
  complexity: 3
}
Output: {
  rawEstimate: 2,
  correctedEstimate: 2,
  correctionFactor: 1,
  sampleSize: 0,
  baselineSource: "inferred_scope_medium_real_tasks",
  scopeUsed: "medium",
  scopeInferred: true,
  confidence: "pessimistic",
  developerProfile: { mode: "ai_native", estimationMape: 15, underestimationBias: 0.2, correctionFactor: 1 },
  adjustedEstimate: 2,
  basisNote: "correctedEstimate (2 hours) is the ledger-recorded and displayed basis (rawEstimate × correctionFactor). adjustedEstimate (2 hours) additionally applies the developerProfile factor (1) and is display-only — it is never recorded or calibrated against.",
  intervalNote: "Fewer than 5 exclusion-filtered historical \"feature\" reference_class_estimate pairs are available yet, so no empirical confidence interval could be computed."
}

（新規インストール時の出力です。フィードバックが蓄積されると、補正係数とサンプルサイズは独自の一致ペアに基づいて算出され、経験的な区間が設定されます。correctedEstimate は常に記録された基準値です。）

有効な task_type の値：feature、bugfix、refactor、migration、infrastructure、documentation、testing、design。

estimate_from_context -- 自由記述のタスク説明を分類し、参照クラス見積もりに委譲します

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."
}

ローカルで決定論的なキーワード／シグナルのヒューリスティックを使用して、自由記述（イシュー本文、PR／差分の説明、タスク概要など）から task_type と complexity を分類します。LLM の呼び出しは行いません。呼び出し元が指定した task_type／complexity のヒントは、常に分類結果より優先されます。解決された入力は、その後 reference_class_estimate と同じ参照クラス予測の処理に委譲されるため、レスポンスには同じ見積もりフィールドに加えて、ツールがコンテキストをどのように解釈したかを説明する classification の来歴ブロックが含まれます。分類の信頼度が低い場合、黙って推測するのではなく、追加の lowConfidenceNote フィールドが返されます。

calibrate_estimates -- 過去の見積もり値と実績値に基づく、チーム固有の精度校正

Input:  {
  task_type: "feature",
  team_id: "backend"
}
Output: {
  correctionFactor: 1.45,
  accuracyTrend: "stable",
  velocityTrend: "stable",
  recommendations: [
    "Using reference database correction factor (1.45x) — 8 matched samples, need 5.",
    "Record actuals via POST /v1/feedback/record-actual to refine for your team's patterns."
  ]
}

token_time_bridge -- 16 のモデルファミリーについて、LLM のトークン予算を実時間に換算します

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
  }
}

レイヤー 5 -- コストとリスク

token_cost_estimate -- LLM API 呼び出しのトークンコスト見積もり

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 -- LLM モデル間のコストと機能を並べて比較

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 -- 記録されたフィードバックデータから、見積もり精度の経時変化を追跡

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 -- プロジェクトのスケジュールに対するリスクスコアリング

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: 42 },
  recommendation: "Low risk. Estimate is within normal variance.",
  humanReadable: "Schedule risk: low. MAPE: 15% (based on 42 historical records). Confidence intervals: p50=40h, p80=45.1h, p95=49.9h."
}

cocomo_validate -- 参照データに照らして COCOMO II の見積もりを検証

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: []
}

cocomo_ground_truth -- 同じ実際の過去プロジェクトを対象に、すべての COCOMO バリアント（Basic、COCOMO II nominal、AI 12x speedup、AI + 開発者プロファイルの勾配）をベンチマークし、データセット別および種別ごとの内訳を表示

Input:  {}
Output: {
  projectsEvaluated: 182,
  models: [
    { name: "COCOMO Basic", mape: 85.55, mmre: 0.856, pred25: 0.313, pred50: 0.544, bias: 53.5, count: 182 },
    ...
  ],
  byDataset: { ... },
  byType: { ... },
  winner: "AI + Profile (human)",
  conclusion: "Best model: AI + Profile (human) (MAPE=79.66%). ...",
  humanReadable: "..."
}

ai_native モード

Epoch ツールは、AI 支援開発と人間のみの開発では進捗速度が根本的に異なることを考慮し、2 種類の推定モードに対応しています。

ai_native=true（デフォルト）の場合、ツールはツールを考慮した補正係数を用いて Epoch の参照データベースを使用します。これらのベースラインは、より速い反復、高いアウトプット量、異なるエラープロファイルを特徴とする AI エージェントのワークフローを反映しています。

ai_native=false の場合、ツールは人間の開発者向けのベースラインを適用します。

パラメーター	人間向けベースライン	AI ネイティブ向けベースライン
機能開発	14 暦日（業界データ）	中央値 5.7 時間（実タスク 126K 件以上）
バグ修正の所要時間	72 時間（業界データ）	中央値 6.2 時間（推定値と実績値が一致するペア 139 件。出典：src/lib/supplementary-data.ts）
スプリントベロシティ	35 ストーリーポイント（業界データ）	80 ストーリーポイント
見積もり精度（MAPE）	25%（Jorgensen 2004）	15%（AI ネイティブプロファイルに基づく）
補正係数	1.8x（業界標準）	1.07-1.45x（参照 DB に基づく）

ai_native に対応しているツール：pert_estimate、cocomo_estimate、sprint_forecast、reference_class_estimate、schedule_risk。

ハイブリッドワークフロー： ai_native には、0.0（完全に人間）から 1.0（完全に AI ネイティブ）までの浮動小数点数を指定できます。0.5 のような値を指定すると、AI と人間が混在するワークフロー向けにプロファイルが補間されます。後方互換性のため、ブール値（true／false）も引き続き使用できます。

自己改善エンジン

Epoch は使うほど、ユーザーのパターンを学習します。バンドルされた参照データベースには、メンテナーによる見積もりと実績のペアの小規模なセット（補正係数の初期値）、厳選された公開研究のベースライン、117,791 件のツール使用状況／レイテンシのテレメトリサンプル（canary-test とセッションのベンチマーク。これらはレイテンシとトークン処理時間の数値の根拠であり、見積もり精度の根拠ではありません）が含まれています。初日から妥当な出発点を提供し、実績を記録するにつれて精度が向上します。

実績を記録すると、Epoch はさらにパーソナライズされます。

1. 見積もる -- 任意の見積もりツールで初期見積もりを生成します
2. 記録する -- 実際の結果を記録します（record_actual）
3. 学習する -- 自己改善機能が、データからパーソナライズされた補正係数を算出します
4. 改善する -- 今後の見積もりに、チームの実績パターンが反映されます
5. 傾向を追跡する -- accuracy_trend で、時間の経過とともに精度が向上しているかどうかを追跡します

Your estimates + your actuals -> Your correction factors -> Better estimates -> Repeat

このループは自動で完結できます。 実績の記録は誰もが忘れがちなステップです。そのため、Epoch が代わりに実行できます。epoch auto-actuals --session <id> は、セッションの未完了の見積もりについて、経過時間から算出した実績を記録します（エージェントホストはセッション終了フックに組み込めます）。自動記録された実績には妥当性の範囲（0.05～12h、見積もりの10倍未満）が設けられ、出所として auto_wallclock が付与されます。実際の実績が上書きされることはなく、feedback_health では byProvenance に個別に報告されるため、自動化されたデータが気付かないうちに補正値を歪めることはありません。

見積もりの書き込み側で inputs.session_id を記録できない場合は、セッションの実際の時間範囲を明示的に渡してください。epoch auto-actuals --session <id> --window-start <ts> --window-end <ts>。各 <ts> にはエポックミリ秒または ISO タイムスタンプを指定できます。両方のフラグを一緒に指定する必要があり、終了時刻は開始時刻以降でなければなりません。Epoch は、永続化された台帳に正確なセッション ID と一致する見積もりがない場合（確定済みまたは期限切れの見積もりを含む）に限り、この時間範囲を使用します。また、対象はセッションの記録がない保留中の見積もりに限られます。別のセッションに記録された見積もりが選ばれることはありません。時間範囲で選択された候補にも、正確なセッション一致の場合と同じ妥当性チェックと重複チェックが適用されます。

git の履歴も実績の情報源になります。 epoch mine-git --repo <path> --since <date> はローカルの git リポジトリを走査します。設計上、オフラインで読み取り専用です。計画フローですでに記録されている識別キー（task_label、branch、issue_ref）を使って、保留中の見積もりを完了した作業（マージ済み PR と通常のマージ）に関連付けます。作業単位ごとに 2 種類のサイクルタイムを算出して個別に報告し、混在させることはありません。1 つ目は最初のコミットからマージまで（出所 git_derived）、2 つ目はオープンからマージまで（出所 git_derived_review_inclusive）です。ブランチ作成時点の情報がローカルに残っている場合にのみ、2 つ目が算出されます。通常のクローンにはその情報がなく、この期間が捏造されることはありません。--window dev|review-inclusive で記録する期間を選択してください。もう一方は実績のメモに記載されます。抽出された実績には妥当性の範囲（[0.05h, 720h]。暦上の期間は夜間や週末にまたがることがあるため）と、見積もりの10倍未満という条件が設けられます。実際の実績が上書きされることはなく、feedback_health では専用の byProvenance カテゴリー（gitDerived）に分けて報告されるため、暦上の期間に起因するノイズが気付かないうちに補正値を歪めることはありません。

見積もりでは、まず誠実な範囲を示します。 タスク種別に一致するペアが 5 組以上ある場合、pert_estimate と reference_class_estimate は、ユーザー自身の過去の見積もりと実績の比率から算出した、較正済みの80％区間から始まります（「予想所要時間は1.6～4.2時間です（80％信頼区間）。点推定値は2.5時間です」）。データがまだ不足している場合は、そのことを明示します。

このエンジンは、体系的な偏り（慢性的な過小見積もり、精度の低下）を検出し、実行可能な推奨事項を提示します。

この機能を使うために、誰かとデータを共有する必要はありません。 自己改善機能は、ユーザー自身の ~/.epoch/ データを使ってすべてローカルで実行されます。

補正ループの実測値

前述の自己改善に関する主張はマーケティング文句ではなく、実行可能な記録によって裏付けられています。scripts/backtest-pert-correction.mjs は、~/.epoch 台帳の読み取り専用の一時コピーを作成し、一致する pert_estimate（推定値、実績値）のペアを時系列順に 80/20 に分割します。学習用の分割のみで学習済みのツール・タスクタイプ別補正係数を訓練し、学習に一度も使っていない保留テスト分割の MdAPE を報告します。

npx tsx scripts/backtest-pert-correction.mjs

執筆時点でのメンテナーの本番台帳での実測値は、保留された一致ペア 697 件で、補正係数が学習時に一度も見ていないデータにおいて、MdAPE は 105.2%（未補正）から 80.5%（学習済み補正）に改善しました。これは、EPOCH_PERT_LEARNED_CORRECTION がデフォルトで有効にすることを推奨する前に、背後で制御する仕組みです。このスクリプトは、補正後の実績値と予測値の比率の中央値が [0.7, 1.3] に収まることも確認します。また、この 2 つ目のガード条件をクリアしていない場合は HOLD（まだ推奨されません）と報告するため、両方の条件を満たすまでは、このフラグが「有効」の状態でリリースされることはありません。ご自身の台帳に対してスクリプトを実行し、ご自身の数値を確認してください。実績値が記録されるにつれて数値は変化します。それが狙いです。

reference_class_estimate の補正係数も、別のツールに適用される同じ学習済みの仕組みです。現在の較正状況は epoch data status または feedback_health（ツールごとの MAPE／MdAPE、バイアス、傾向）で追跡できます。または、node scripts/build-calibration-dashboard.mjs で較正の判断サーフェス全体のレポートを生成できます。こちらも台帳に対して完全な読み取り専用で動作します。

データパイプライン

Epoch は、最初から正確に動作し、時間とともに改善されるよう、3 層のデータ戦略を採用しています。

1. バンドルされた参照データベース（すぐに使え、セットアップ不要）： Epoch には、事前構築済みの参照データベースが含まれています。メンテナー自身の推定値と実績値の履歴からシードされた補正係数、厳選された公開研究に基づくスコープのベースライン、そして 117,791 件のツール使用状況・レイテンシのテレメトリサンプル（8 種類のタスクタイプ、5 段階の複雑度にわたるカナリアテストとセッションベンチマーク）です。Epoch でデータ量が表示される箇所では、テレメトリサンプル数と、一致する推定値・実績値ペアの件数が個別に報告されます。

2. ローカルでの自己改善（自動、プライベート）： Epoch を使って実績値を記録すると、自己改善エンジンがご自身のデータを使って補正係数を再較正します。この処理はすべて ~/.epoch/ 内でローカルに実行され、マシンの外部にデータが送信されることはありません。エンジンはツール呼び出し 100 回ごと、または 24 時間ごとに自動で起動します。

• 自動記録： scripts/auto-record-actual.mjs を使って、保留中の推定値に対する実績時間を自動的に記録できます。
• ソースタグ付け： EPOCH_SOURCE=<project-name> を設定して、プロジェクトごとに推定値をタグ付けできます。
• データの確認： epoch data where と epoch data status で、ローカルに保存された内容を確認できます。

3. コミュニティへの貢献（任意、オプトイン）： 匿名化したデータを任意で共有し、すべてのユーザー向けのベースライン改善に役立てることができます。コミュニティデータからはすべての識別情報が削除され、タスクタイプ、複雑度、推定時間、実績時間、日付のみが残ります。形式とプライバシー要件については、CONTRIBUTING-data.md を参照してください。

epoch share-data --validate --description "My anonymized estimation data"

これは完全に任意です。Epoch は、これを使わなくても十分に機能します。

インターフェース

Epoch は、同じ 26 個のツールを 3 つのインターフェースで提供します。

インターフェース	トランスポート	用途
MCP Server	stdio	Claude Code、Cursor、VS Code、Windsurf
CLI	直接実行	スクリプト、CI/CD、クイック検索
REST API	HTTP (Hono)	Web アプリ、AI エージェント、インテグレーション

デフォルトの動作：引数なしで epoch を実行すると、MCP stdio サーバーが起動します。

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

# Schedule risk score
epoch schedule-risk --estimated-hours 40

# List all tools
epoch list-tools

# Pretty table output
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --pretty

ソースをチェックアウトした場合、pnpm install と pnpm run build の実行後、同じ CLI は dist/index.js です。CI は変更のたびにこのブロックを実行し、各 # expect: 行が出力に含まれている必要があるため、これらの例がコードと食い違うことはありません。

node dist/index.js --version
node dist/index.js parse-duration --duration 2h30m
# expect: "totalSeconds": 9000
node dist/index.js count-business-days --start-date 2026-05-01 --end-date 2026-05-15 --country US
# expect: "businessDays": 10
node dist/index.js add-business-days --start-date 2026-05-01 --days 5 --country US
# expect: "endDate": "2026-05-08"
node dist/index.js time-math --operation add_days --date 2026-05-01 --days 7
# expect: "data": "2026-05-08"

REST 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.json

フィードバック REST ルート

/v1/feedback/* は、見積もりから実績までのフィードバックループを閉じるための安定した REST API です。フィードバックツールの別名ではありません。リクエストの検証、レスポンスの形式、ステータスコードは、POST /v1/tools/<name>（または MCP や CLI）を通じて同じツールを呼び出す場合とは異なります。呼び出すインターフェースに合わせてコードを作成してください。

ルート	REST の仕様	/v1/tools/<name> 経由のツール
POST /v1/feedback/record-actual	{estimate_id, actual_hours, notes?}。成功時は {estimateId, actualHours, recorded, flagged?, flagHint?}（キャメルケース）を返します。ステータス：入力不正または呼び出し側で修正可能な拒否（below_threshold、synthetic_id、unknown_tool、自動チェックまたは git のサニティゲートの失敗）の場合は 400、重複の場合は 409、ストレージ障害の場合は 500 です。	record_actual：成功時は {recorded, estimate_id, actual_hours, message, flagged?, flagHint?}（スネークケース）を返します。失敗時はすべて 422 となり、メッセージに理由が示されます。
GET /v1/feedback/pending?limit=	limit のデフォルトは 50 で、1～200 の範囲に制限されます。数値以外の値を指定すると 50 にフォールバックします。上限までの保留中の見積もりをすべて、完全なレコードとして返します。	get_pending_estimates：limit のデフォルトは 20、最大値は 100 です。{count, summary, estimates} を返します。count は上限までの件数を示しますが、estimates に含まれるのは直近の最大 10 件です。
POST /v1/feedback/batch-record-actuals	1～500 件を指定できます。部分成功に対応しています。有効なエントリーは記録され、無効なエントリーはそれぞれインデックスとともに errors に報告されます。成功したエントリーがない場合、原因がストレージ障害なら 500、それ以外は 422 です。	batch_record_actuals：Zod は各エントリーを先に検証するため、無効なエントリーが 1 件でもあるとバッチ全体が拒否され（422）、何も記録されません。
GET /v1/feedback/health	フィードバックのヘルスレポートを返します。	feedback_health：同じレポートに intervalCoverage（P80 予測区間の較正）を追加して返します。

エージェントファースト

Epoch は、端末に入力する人間を後回しにするのではなく、エージェントを第一級の呼び出し元として設計されています。

エージェントに時間感覚が必要な理由。 LLM には、所要時間やコストについて根拠に基づいた感覚がありません。2 日かかる移行を「簡単な修正」と呼んだり、2 時間で済む設定変更を「大規模なプロジェクト」と呼んだりしても、確信度は同じです。そうした判断を正すフィードバックループがないためです。チャットでの回答なら問題ありませんが、エージェントが複数ステップの作業を計画したり、スプリントの順序を決めたり、期限が現実的かどうかを判断したりする段階になると、うまくいかなくなります。Epoch は推測の代わりに計算手段をエージェントに提供します。PERT／COCOMO／モンテカルロ法による計算、実際のタスクデータに基づく参照クラスのベースライン、そしてエージェント（またはそのオペレーター）が実績を記録するにつれて自己修正するフィードバックループです。

ヘッドレス／エージェントのオペレーター向けの EPOCH_TELEMETRY=1。 テレメトリはデフォルトでオフになっており、十分な情報に基づく同意が必要です。端末を使う人間の場合、その同意は epoch telemetry enable で行います。このコマンドはデータを表示し、確認を求めます。エージェントが自らの判断でそのプロンプトに「はい」と答えてはなりません。意図的にテレメトリを有効にする MCP ツールは用意されていないため、エージェントが自ら同意することはできません。ヘッドレス環境やエージェントが操作するデプロイでは、オペレーターがエージェントの起動前に、サーバーの環境変数（たとえば MCP サーバー設定の env ブロック）に EPOCH_TELEMETRY=1 を設定し、別途オプトインします。同意するのはデプロイを設定する人間であり、その中で動作するエージェントではありません。

MCP クライアントの分類。 Epoch のテレメトリスキーマ（v2）は、接続時にホストから報告される MCP の clientInfo から client_name／client_version を記録し、さらに transport（stdio／http）も記録します。これはエージェントの「識別」ではなく「分類」です。新たにユーザー個人を特定するシグナルを追加することなく、「エージェント主導の機能見積もり N 件における中央値は 5.7 時間」といった集計精度統計を、匿名の CLI 利用にまとめず、エージェントのデータとして扱えます。clientInfo を報告する MCP クライアント（Claude Code、Cursor、および現在のほとんどのホスト）では、これが自動的に利用できます。報告しないクライアントもすべての機能を利用できますが、client_name: null として表示されます。

Epoch には、エージェントが事前設定なしで HTTP API を見つけて利用できるようにする、組み込みの検出用エンドポイントもあります。

エンドポイント	説明
GET /.well-known/ai-plugin.json	OpenAI プラグインマニフェスト
GET /llms.txt	LLM が利用できるドキュメント
GET /openapi.json	OpenAPI 3.1 仕様
GET /health	サービスの状態とバージョン

インストール

git clone https://github.com/KyaniteLabs/Epoch.git
cd Epoch
pnpm install
pnpm run build

開発

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 testing

技術スタック

• ランタイム: Node.js 22+（ESM；engines.node >=22 — Node 20 は 2026 年 4 月に EOL を迎えました）
• 言語: TypeScript 6（strict モード、noUncheckedIndexedAccess、verbatimModuleSyntax）
• バリデーション: Zod 4。すべてのフィールドに .describe() を指定
• MCP SDK: @modelcontextprotocol/sdk 1.12+
• HTTP: Hono（軽量、マルチランタイム）
• CLI: Commander.js
• 日付処理: date-fns 4.x + date-fns-tz 3.x
• ビルド: tsup（ESM 出力）
• テスト: v8 カバレッジ対応の vitest 4.x（ステートメント 97%、分岐 88%）

設定

変数	デフォルト	説明
EPOCH_TRANSPORT	stdio	トランスポートモード：stdio または http
EPOCH_PORT	3000	HTTP サーバーのポート
EPOCH_HOST	127.0.0.1	HTTP サーバーのバインドアドレス
EPOCH_DATA_DIR	~/.epoch/	フィードバックと自己改善のためのデータディレクトリ
EPOCH_COMMUNITY_DIR	data/community/	コミュニティデータディレクトリ
EPOCH_RATE_LIMIT	100	クライアントごとの1分あたりの最大リクエスト数（HTTP のみ）。0 にすると制限が無効になります。無効な値または負の値を指定した場合は、警告とともに 100 に戻ります。429 レスポンスには Retry-After ヘッダーが含まれます。
EPOCH_TRUST_PROXY	0	信頼できるリバースプロキシの背後で実行する場合に限り 1 に設定してください。この場合、レート制限のキーには接続アドレスではなく X-Forwarded-For／X-Real-IP が使用されます（これらのヘッダーはクライアントが偽装できるため、デフォルトでは無視されます）。
EPOCH_CORS_ORIGINS	(なし)	HTTP API の CORS 処理で許可するオリジンをカンマ区切りで指定します（例：https://app.example.com,http://localhost:5173）。すべてのオリジンを許可するには * を指定します。デフォルトでは CORS ヘッダーは一切付与されません。同一オリジンのツール、curl、MCP クライアントには影響しませんが、クロスオリジンのブラウザーリクエストは失敗します。プリフライトの OPTIONS リクエストには常に応答します。
EPOCH_SOURCE	(なし)	見積もりレコードに付与するプロジェクト／ソースタグ
EPOCH_TELEMETRY	0	匿名テレメトリーを有効にするには 1 に設定します。テレメトリーとプライバシーを参照してください。
EPOCH_TELEMETRY_ENDPOINT	(なし)	ステータス確認／送信用に設定済みのテレメトリー受信エンドポイントを上書きします。

テレメトリーとプライバシー

Epoch は、すべてのユーザーの精度向上のため、見積もりと実績のペアを匿名化して共有できます。この機能はデフォルトで無効であり、明示的なオプトインが必要です。

エージェント運用者の同意モデル： テレメトリーを有効にする MCP ツールは意図的に用意されていません。エージェントが人間に代わって自ら同意することがあってはならないためです。人間は epoch telemetry enable を対話形式で実行してオプトインします。エージェント／ヘッドレス環境の運用者は、エージェントの起動前にサーバーの環境で EPOCH_TELEMETRY=1 を設定して、別の方法でオプトインします（エージェントファーストを参照）。どちらの場合も、デプロイを設定する人が同意します。

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 JSON

共有される情報： タスクの種類、複雑さ、ツール名、見積もり時間、実績時間、比率、日付（YYYY-MM-DD のみ）。

共有されることのない情報： プロジェクト名、メモ、チーム ID、IP アドレス、時刻を含むタイムスタンプ、ソースコード、説明。

詳しくは、プライバシーポリシーとテレメトリーのドキュメントを参照してください。

データの保存場所

デフォルトでは、Epoch はローカルデータを ~/.epoch/ または EPOCH_DATA_DIR の下に保存します。ローカルの使用状況データが GitHub に自動的にコミットされたり、どこかに自動送信されたりすることはありません。

epoch data where     # Show local data file locations
epoch data status    # Show data file counts, feedback health, telemetry config

データの共有

epoch share-data --validate を使うと、data/community/ に適したコミュニティデータの JSON ファイルを作成できます。PR を作成する前にファイルを確認してください。

epoch share-data --description "Anonymized Epoch usage export" --validate

マシンラベル

フリートのホストインベントリは、このリポジトリでは公開されていません。docs/ops/machines.md には、マシンを内部で追跡するためのスキーマが記載されています。実際のホスト名、アドレス、SSH ユーザーは、実行時に環境変数で指定します（scripts/ と docs/ops/epoch-fleet-audit.md を参照）。windows-receiver は過去に使われていたラベルにすぎません。

ライセンス

Apache License 2.0。利用条件の全文は LICENSE を参照してください。日付入りのライセンス変更履歴（npm 0.2.x を MIT ライセンスのもとで利用するユーザーを含む）：LICENSING.md。

---

KyaniteLabs の一部

KyaniteLabs のその他のプロジェクトはこちらです。関連プロジェクト：

• kinocut — AI エージェント向けのガードレール付き動画編集 MCP サーバー（旧称 mcp-video）
• DialectOS — スペイン語の方言ローカライズ用 MCP サーバーおよび CLI
• checkyourself — AI が作成したコードのための、ローカルファーストな本番環境対応チェック

→ kyanitelabs.tech で詳細をご覧ください

Epoch とは？

Epoch は、期間の見積もりを行う MCP サーバーです。調整された所要期間の見積もりが必要なエンジニアリングリーダー、エージェント、計画担当者が、PERT／参照クラス見積もりを作成し、実績を記録するのに役立ちます。

製品	Epoch
カテゴリ	期間見積もり MCP サーバー
最適な対象	調整された所要期間の見積もりが必要なエンジニアリングリーダー、エージェント、計画担当者
対象外	カレンダーやプロジェクトトラッカー
ソース	GitHub · Forgejo（非公開、メンテナーのみ）
キーワード	期間見積もり MCP、PERT、参照クラス予測

対象ユーザー

• 主な対象：調整された所要期間の見積もりが必要なエンジニアリングリーダー、エージェント、計画担当者
• PERT／参照クラス見積もりの作成と実績の記録が必要な場合にご利用ください
• カレンダーやプロジェクトトラッカーが必要な場合は対象外です

FAQ

Epoch とは？

Epoch は期間見積もりを行う MCP サーバーです。調整された所要期間の見積もりが必要なエンジニアリングリーダー、エージェント、計画担当者が、PERT／参照クラス見積もりを作成し、実績を記録するのに役立ちます。

Epoch は誰が使うべきですか？

調整された所要期間の見積もりが必要なエンジニアリングリーダー、エージェント、計画担当者です。

Epoch の特長は何ですか？

感覚に頼った時間の見積もりとは異なり、Epoch では構造化された見積もりと実績からのフィードバックが必須です。

Epoch は本番環境で使えるソフトウェアですか？

成熟度の判断には、README のステータスとリリースタグを一次情報として扱ってください。本番環境で使用する前に、ご自身の要件に照らして検証してください。

ステータス

• 2026 年時点で、デフォルトブランチでメンテナンスされています
• 依存関係を固定する場合は、リリースタグを優先してください
• 問題はGitHubに報告してください

エージェント向け情報

• コーディングエージェント：まずこの README を読み、続いてリポジトリのドキュメントと、存在する場合は AGENTS.md を読んでください
• リポジトリに機械可読な概要（llms.txt）がある場合は、そちらを優先してください
• MCP またはスキルのエントリーポイントは、該当する場合、リポジトリ内に記載されています

コントリビューション

GitHub での Issue と PR を歓迎します。公開ドキュメントには、シークレットやマシン固有のパスを含めないでください。

ライセンス

このリポジトリ内の LICENSE を参照してください（ライセンスがパッケージのみに適用される場合は、パッケージのメタデータを参照してください）。