Configuration

Two files control everything, and you can edit both without touching code. Changes to settings.json take effect immediately; changes to pricing.json need a restart.

`config/pricing.json`

Model prices per million tokens, kept separate from usage data so the table can be updated when prices change. A claude-* model with no entry is priced like the newest listed model of its family and marked priced as … in the model view until it gets an entry of its own. Any other unlisted model counts as $0 and is flagged.

`config/settings.json`

{
  "billing_period": { "mode": "calendar_month", "anchor_day": 1 },
  "limits": {                        // null => reported as unavailable, never guessed
    "monthly_cost_allowance_usd": null,
    "monthly_token_allowance": null,
    "monthly_request_allowance": null,
    "remaining_credits_usd": null
  },
  "budgets": { "monthly_usd": null, "daily_usd": null, "per_project_usd": {} },
  "alert_thresholds_pct": [50, 75, 90, 100],
  "guard": {                         // per-conversation token limit (+ optional live warnings)
    "session_tokens": null,          // tokens per Claude Code conversation; null => no limit
    "warn_pct": [75, 80],            // warn, never block, as a conversation crosses these
    "after_approval": "step",        // after you say "continue": ask again every step_pct, or "once"
    "step_pct": 25,
    "projects": {},                  // {"/abs/path": {"session_tokens": n} | {"off": true}}
    "sessions": {}                   // one conversation's own limit, set from Running sessions
  },
  "hygiene":    { "context_thresholds": [100000, 150000] },
  "history":    { "keep_deleted_transcripts": true },   // keep sessions Claude Code deleted
  "subagents":  { "min_runs": 5 },   // runs needed on each side before a model is compared
  "waste_rules": { /* thresholds for each detector */ },
  "anomaly":    { /* z-score and ratio triggers */ },
  "scorecard":  { /* the reference points each dimension is graded against */ }
}

The Budgets view lets you edit limits, budgets and thresholds in the browser. Your changes are saved to ~/.claude-finops/settings.local.json, so the shared defaults stay untouched. Amounts accept short numbers like 20M, 500k or $3,000.

The per-conversation limit counts billable tokens (input, output, cache reads and cache writes), the same figure as the Tokens column in Sessions. Cache reads make up most of a long conversation, which is exactly what this limit is for. The optional live warnings (claude-finops --install-guard) are a Claude Code hook; your limits work without them.

Provider API keys for Billed vs local are set on the Settings page (or with --set-key) and stored in ~/.claude-finops/secrets.local.json. The Jev key from the Jev page is stored as TYPESAFE_API_KEY under env in ~/.claude/settings.json, so Claude Code sessions can use it.