skill-cost-projections

ホスト：Codex CLI — このスキルはClaude Code向けに設計され、Codex向けに調整されています。 コマンドの相互参照では、/octo:* スラッシュコマンドではなく、Codexでインストール済みのスキル名を使用します。 現在のCodexシェルとサブエージェントツールを使用してください。現在のセッションで利用可能になっていないプロバイダー、モデル、ホストのサブエージェントが利用できると断言しないでください。 ホストのツールに相当するものについては、skills/blocks/codex-host-adapter.md を参照してください。

コスト予測スキル

概要

完了済みの作業におけるフェーズごとの平均コストに基づいて、ワークフローの残りのコストを予測します。HUD／ステータスラインにコストデータを表示し、予測合計が設定済みの予算上限を超える場合に警告します。

最低限必要なデータ： 予測を行うには、2つ以上の完了済みステップが必要です。データポイントが2つ未満の場合、平均値の信頼性が低いため、実際の支出のみを表示し、予測は行いません。

ステップ1：完了済みフェーズのコストを収集する

~/.claude-octopus/metrics/ または metrics-tracker.sh の出力からコストデータを読み取ります。完了した各フェーズ／ステップには、対応するコストエントリーが必要です。

# Read metrics from the session metrics directory
METRICS_DIR="$HOME/.claude-octopus/metrics"
SESSION_METRICS="$METRICS_DIR/session-$(date +%Y%m%d).jsonl"

# Each line contains: {"phase": "discover", "cost": 0.42, "tokens_in": 12000, "tokens_out": 3400, "timestamp": "..."}
# Sum costs from completed steps
completed_costs=$(jq -s '[.[].cost]' "$SESSION_METRICS")
completed_count=$(jq -s 'length' "$SESSION_METRICS")
total_spent=$(jq -s '[.[].cost] | add' "$SESSION_METRICS")

データソース（優先順位順）：

1. ~/.claude-octopus/metrics/session-*.jsonl — フェーズごとの構造化されたコストエントリー
2. metrics-tracker.sh の出力 — 従来のセッション向けのフォールバック
3. HUDの累積コストカウンター — 最終手段

完了済みステップが2つ未満の場合は、実際の支出のみを表示します：

💰 Spent: 0.42 USD (1 step complete — need 2+ for projection)

ステップ2：ステップあたりの平均コストを計算する

完了済みのすべてのステップの平均コストを計算します。

avg_cost=$(echo "$total_spent / $completed_count" | bc -l)

計算式：

avg_cost = total_cost / completed_steps

例： 3つのステップのコストが0.30 USD、0.50 USD、0.40 USDの場合 → 平均 = 1.20 USD / 3 = 0.40 USD／ステップ

ステップ3：残りのコストを予測する

ステップあたりの平均コストに残りのステップ数を掛けます。

remaining_steps=$((total_steps - completed_count))
projected_remaining=$(echo "$avg_cost * $remaining_steps" | bc -l)
projected_total=$(echo "$total_spent + $projected_remaining" | bc -l)

計算式：

projected_remaining = avg_cost × remaining_steps
projected_total     = total_spent + projected_remaining

ワークフローの種類別ステップ数：

ワークフロー	合計ステップ数	フェーズの例
embrace	4	発見、定義、開発、提供
research	3-7	エージェントごとの調査回数
review	3	Fleet、検証、統合
debate	3	冒頭陳述、反論、統合

ステップ4：HUDに表示する

HUD／ステータスライン表示用にコスト予測を整形します。

標準表示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD

書式ルール：

• すべての金額は小数点以下2桁で表示します
• 予測合計の先頭に推定を示す ~ を付けます
• コスト行の先頭に 💰 を付けます
• ステータスラインへの統合に合わせて、1行にまとめて表示します

データ不足の場合（2ステップ未満）：

💰 Spent: 0.42 USD (need 2+ steps for projection)

統合： この表示行は octopus-hud フックが出力し、フェーズの進捗状況とプロバイダーの状態とともにステータスラインに表示されます。

ステップ5：予算上限の警告

OCTO_BUDGET_CEILING 環境変数が設定されている場合、予測合計と比較し、超過時に警告します。

if [[ -n "${OCTO_BUDGET_CEILING:-}" ]]; then
  ceiling="$OCTO_BUDGET_CEILING"
  if (( $(echo "$projected_total > $ceiling" | bc -l) )); then
    overage=$(echo "$projected_total - $ceiling" | bc -l)
    echo "⚠️ Budget ceiling: ${ceiling} USD — projected to exceed by ${overage} USD"
  fi
fi

予算超過時の表示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
⚠️ Budget ceiling: 5.00 USD — projected to exceed by 1.00 USD

予算内の場合の表示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
✅ Within budget ceiling: 10.00 USD

注： OCTO_BUDGET_CEILING は任意です。設定されていない場合、上限のチェックは行われません。

ステップ6：プロファイルの提案

タスクに対して予測合計が高い場合は、コストを削減するため、budgetプロファイルへの切り替えを提案します。

# Suggest budget profile when projected total exceeds 5.00 USD (configurable)
COST_THRESHOLD="${OCTO_COST_THRESHOLD:-5.00}"
if (( $(echo "$projected_total > $COST_THRESHOLD" | bc -l) )); then
  echo "💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs"
fi

表示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs

budgetプロファイル（OCTO_PROFILE=budget）は、より安価なモデルにルーティングし、エージェント数を減らして支出を最小限に抑えます。

表示例

通常 — 予算内、コストは中程度：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD

予算上限を超過：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
⚠️ Budget ceiling: 5.00 USD — projected to exceed by 1.00 USD
💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs

ワークフロー序盤（データ不足）：

💰 Spent: 0.42 USD (need 2+ steps for projection)

低コスト — 警告なし：

💰 Spent: 0.80 USD | Est. remaining: 0.80 USD | Total: ~1.60 USD

統合

octopus-hud フックとの連携

コスト予測行はHUDのステータスライン出力の一部として表示され、各フェーズの完了後に更新されます。

metrics-tracker.sh との連携

metrics trackerが書き込んだフェーズごとのコストデータを読み取ります。完了した各フェーズについて、コスト、トークン数、プロバイダーの詳細が記録されます。

OCTO_PROFILEとの連携

OCTO_PROFILE=budget が有効な場合、より安価なモデルへのルーティングによる、ステップごとのコスト削減が予測に反映されます。

エラー処理

メトリクスディレクトリがない場合：

💰 Cost projection unavailable — no metrics data found

メトリクスデータが破損している場合： 形式が不正なエントリをスキップし、有効なデータのみから予測します。有効なエントリが残らない場合は、利用不可のメッセージを表示します。

残りのステップがゼロの場合： すべてのステップが完了したら、最終合計のみを表示します：

💰 Final cost: 4.80 USD (4 steps)