coding-agent-cost 0.1.0__py3-none-any.whl

agent_cost/__init__.py

@@ -0,0 +1,9 @@
+"""agent-cost: estimate AI coding agent token usage and cost from local logs.
+
+Reads Claude Code and Codex CLI logs that already exist on disk and turns
+them into per-event "facts" (billing events), then prices those facts
+against a versioned rate catalog. Everything happens locally; there are no
+network calls.
+"""
+
+__version__ = "0.1.0"

agent_cost/aggregate.py

@@ -0,0 +1,201 @@
+"""Price facts and aggregate them into report rows.
+
+Pricing and grouping are pure functions over a list of ``Fact`` and a
+``RateCatalog`` -- they know nothing about where the facts came from, so
+they're testable independently of any reader.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import Iterable, Optional, Tuple
+from zoneinfo import ZoneInfo
+
+from .facts import Fact
+from .rates import RateCatalog
+
+GROUP_DIMENSIONS = ("month", "agent", "model", "token-kind")
+_STATUS_RANK = {"unpriced": 0, "lower_bound": 1, "priced": 2}
+
+
+def price_fact(catalog: RateCatalog, fact: Fact) -> Tuple[Optional[Decimal], str, Optional[Decimal]]:
+    """Price one fact. Returns ``(estimated_cost_usd, pricing_status, credits)``.
+
+    ``cache_write_unknown`` (a cache write whose TTL couldn't be
+    determined) is priced at the 5-minute rate as a *lower bound* --
+    never at the more expensive 1-hour rate -- and flagged accordingly.
+    An unrecognized model or an unpriced token kind for an otherwise-known
+    model both return ``(None, "unpriced", None)`` rather than a guess.
+    """
+    resolved_key, period = catalog.rate_for(fact.model_key, fact.occurred_at_utc)
+    if resolved_key is None or period is None:
+        return None, "unpriced", None
+
+    rate_field = fact.token_kind
+    lower_bound = False
+    if fact.token_kind == "cache_write_unknown":
+        rate_field = "cache_write_5m"
+        lower_bound = True
+
+    rate = period.values.get(rate_field)
+    if rate is None:
+        return None, "unpriced", None
+
+    entry = catalog.models[resolved_key]
+    tokens = Decimal(fact.tokens)
+    multiplier = entry.fast_multiplier if fact.mode == "fast" else Decimal("1.0")
+    cost = (tokens / Decimal(1_000_000)) * rate * multiplier
+
+    credits = None
+    if entry.credits_per_mtok is not None:
+        credit_rate = entry.credits_per_mtok.get(rate_field)
+        if credit_rate is not None:
+            credits = (tokens / Decimal(1_000_000)) * credit_rate * multiplier
+
+    status = "lower_bound" if lower_bound else "priced"
+    return cost, status, credits
+
+
+def filter_facts(
+    facts: Iterable[Fact],
+    *,
+    since_utc: Optional[datetime] = None,
+    until_utc: Optional[datetime] = None,
+    agents: Optional[set] = None,
+):
+    """Apply the ``[since, until)`` half-open window and an agent filter."""
+    for f in facts:
+        if since_utc is not None and f.occurred_at_utc < since_utc:
+            continue
+        if until_utc is not None and f.occurred_at_utc >= until_utc:
+            continue
+        if agents is not None and f.agent not in agents:
+            continue
+        yield f
+
+
+@dataclass
+class DataQuality:
+    malformed_events: int = 0
+    skipped_files: int = 0
+    negative_deltas: int = 0
+    unpriced_tokens: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "malformed_events": self.malformed_events,
+            "skipped_files": self.skipped_files,
+            "negative_deltas": self.negative_deltas,
+            "unpriced_tokens": self.unpriced_tokens,
+        }
+
+
+@dataclass
+class Row:
+    month: Optional[str] = None
+    agent: Optional[str] = None
+    model: Optional[str] = None
+    token_kind: Optional[str] = None
+    tokens: int = 0
+    priced_tokens: int = 0
+    unpriced_tokens: int = 0
+    estimated_cost_usd: Decimal = field(default_factory=lambda: Decimal("0"))
+    credits: Decimal = field(default_factory=lambda: Decimal("0"))
+    pricing_status: str = "priced"
+
+    def to_dict(self) -> dict:
+        return {
+            "month": self.month,
+            "agent": self.agent,
+            "model": self.model,
+            "token_kind": self.token_kind,
+            "tokens": self.tokens,
+            "priced_tokens": self.priced_tokens,
+            "unpriced_tokens": self.unpriced_tokens,
+            "estimated_cost_usd": float(self.estimated_cost_usd),
+            "credits": float(self.credits),
+            "pricing_status": self.pricing_status,
+        }
+
+
+def _month_key(dt: datetime, tz: ZoneInfo) -> str:
+    local = dt.astimezone(tz)
+    return f"{local.year:04d}-{local.month:02d}"
+
+
+def build_rows(
+    facts: Iterable[Fact],
+    catalog: RateCatalog,
+    *,
+    group_by: Tuple[str, ...] = GROUP_DIMENSIONS,
+    timezone_name: str = "UTC",
+) -> Tuple[list, DataQuality]:
+    """Group priced facts into rows. Dimensions not in ``group_by`` are
+    left ``None`` on every row (per-fact filtering/pricing still happens
+    on the full, ungrouped dimension set).
+
+    A row's ``pricing_status`` is the worst status among its facts
+    (``unpriced`` beats ``lower_bound`` beats ``priced``), so a row is
+    never silently reported as fully priced when part of it wasn't.
+    """
+    tz = ZoneInfo(timezone_name)
+    buckets: dict = {}
+    unpriced_tokens_total = 0
+
+    for f in facts:
+        cost, status, credits = price_fact(catalog, f)
+        if status == "unpriced":
+            unpriced_tokens_total += f.tokens
+
+        month = _month_key(f.occurred_at_utc, tz) if "month" in group_by else None
+        agent = f.agent if "agent" in group_by else None
+        model = f.model_key if "model" in group_by else None
+        token_kind = f.token_kind if "token-kind" in group_by else None
+        key = (month, agent, model, token_kind)
+
+        row = buckets.get(key)
+        if row is None:
+            row = Row(month=month, agent=agent, model=model, token_kind=token_kind)
+            buckets[key] = row
+
+        row.tokens += f.tokens
+        if status == "unpriced":
+            row.unpriced_tokens += f.tokens
+        else:
+            row.priced_tokens += f.tokens
+            if cost is not None:
+                row.estimated_cost_usd += cost
+            if credits is not None:
+                row.credits += credits
+
+        if _STATUS_RANK[status] < _STATUS_RANK[row.pricing_status]:
+            row.pricing_status = status
+
+    rows = sorted(
+        buckets.values(),
+        key=lambda r: (r.month or "", r.agent or "", r.model or "", r.token_kind or ""),
+    )
+    return rows, DataQuality(unpriced_tokens=unpriced_tokens_total)
+
+
+def rows_totals(rows: Iterable[Row]) -> dict:
+    """Sum a set of rows into a single scalar totals dict.
+
+    Sums the underlying Decimal cost/credits fields (not their float
+    conversions) so precision isn't lost across many rows before
+    converting to float once at the end, for callers (like ``measure``)
+    that need one aggregate number across rows that were grouped by
+    dimensions they don't care about.
+    """
+    rows = list(rows)
+    estimated_cost_usd = sum((r.estimated_cost_usd for r in rows), Decimal("0"))
+    credits = sum((r.credits for r in rows), Decimal("0"))
+    return {
+        "tokens": sum(r.tokens for r in rows),
+        "priced_tokens": sum(r.priced_tokens for r in rows),
+        "unpriced_tokens": sum(r.unpriced_tokens for r in rows),
+        "estimated_cost_usd": float(estimated_cost_usd),
+        "credits": float(credits),
+    }

agent_cost/cli.py

@@ -0,0 +1,393 @@
+"""Command-line entry point: ``agent-cost report / export / rates / doctor``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+from zoneinfo import ZoneInfo
+
+from . import __version__
+from .aggregate import DataQuality, build_rows, filter_facts, rows_totals
+from .config import load_config
+from .facts import SOURCE_QUALITY_VALUES
+from .rates import RatesValidationError, load_rates
+from .readers import claude as claude_reader
+from .readers import codex as codex_reader
+from .renderers import render_csv, render_json, render_table
+
+#: agent-cost measure's output contract version. Bump on a breaking change
+#: to the JSON shape (removed/renamed field, changed field meaning); adding
+#: a new field is not breaking. Consumers (e.g. lane's TelemetryAdapter)
+#: should check this before trusting the shape of the payload.
+MEASURE_PROTOCOL_VERSION = "measure/v1"
+
+
+def _parse_window_bound(value: Optional[str], tz: ZoneInfo) -> Optional[datetime]:
+    if not value:
+        return None
+    # Python 3.9-3.10's datetime.fromisoformat() rejects the "Z" (Zulu/UTC)
+    # suffix that ISO 8601 allows and that, e.g., JavaScript's
+    # Date.toISOString() always emits -- normalize it to the equivalent
+    # "+00:00" offset fromisoformat does accept, before parsing.
+    text = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        dt = datetime.fromisoformat(text)
+    except ValueError as exc:
+        raise SystemExit(f"[error] invalid date/time: {value!r} ({exc})")
+    if dt.tzinfo is not None:
+        return dt.astimezone(timezone.utc)
+    # Date-only (or naive datetime) input is interpreted in --timezone.
+    return dt.replace(tzinfo=tz).astimezone(timezone.utc)
+
+
+def _collect_facts(config, *, agents: set, exclude_archived: bool):
+    facts: list = []
+    dq = DataQuality()
+
+    if "claude" in agents:
+        result = claude_reader.read_claude_facts(config.claude_projects_dir)
+        facts.extend(result.facts)
+        dq.malformed_events += result.malformed_events
+        dq.skipped_files += result.skipped_files
+
+    if "codex" in agents and config.codex_db_path.exists():
+        result = codex_reader.read_codex_facts(
+            config.codex_db_path,
+            config.codex_home,
+            include_archived=not exclude_archived,
+        )
+        facts.extend(result.facts)
+        dq.malformed_events += result.malformed_events
+        dq.skipped_files += result.skipped_files
+        dq.negative_deltas += result.negative_deltas
+
+    return facts, dq
+
+
+def cmd_report(args) -> int:
+    config = load_config()
+    tz = ZoneInfo(args.timezone)
+    since = _parse_window_bound(args.since, tz)
+    until = _parse_window_bound(args.until, tz)
+    agents = set(args.agent.split(",")) if args.agent else {"claude", "codex"}
+    group_by = tuple(args.group_by.split(",")) if args.group_by else (
+        "month",
+        "agent",
+        "model",
+        "token-kind",
+    )
+
+    try:
+        catalog = load_rates(Path(args.rates) if args.rates else None)
+    except RatesValidationError as exc:
+        print(f"[error] rates catalog invalid: {exc}", file=sys.stderr)
+        return 2
+
+    facts, dq = _collect_facts(config, agents=agents, exclude_archived=args.exclude_archived)
+    facts = list(filter_facts(facts, since_utc=since, until_utc=until, agents=agents))
+    rows, agg_dq = build_rows(facts, catalog, group_by=group_by, timezone_name=args.timezone)
+    dq.unpriced_tokens = agg_dq.unpriced_tokens
+
+    payload = {
+        "schema_version": "1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "window": {
+            "since": since.isoformat() if since else None,
+            "until": until.isoformat() if until else None,
+        },
+        "timezone": args.timezone,
+        "rates": {"catalog_version": catalog.catalog_version, "sha256": catalog.sha256},
+        "group_by": list(group_by),
+        "data_quality": dq.to_dict(),
+        "rows": [r.to_dict() for r in rows],
+    }
+
+    renderer = {"table": render_table, "csv": render_csv, "json": render_json}[args.format]
+    print(renderer(payload))
+    return 0
+
+
+def cmd_export(args) -> int:
+    config = load_config()
+    tz = ZoneInfo(args.timezone)
+    since = _parse_window_bound(args.since, tz)
+    until = _parse_window_bound(args.until, tz)
+    agents = set(args.agent.split(",")) if args.agent else {"claude", "codex"}
+
+    facts, _dq = _collect_facts(config, agents=agents, exclude_archived=False)
+    facts = list(filter_facts(facts, since_utc=since, until_utc=until, agents=agents))
+
+    out = open(args.out, "w") if args.out else sys.stdout
+    try:
+        for f in facts:
+            record = {
+                "occurred_at_utc": f.occurred_at_utc.isoformat(),
+                "agent": f.agent,
+                "session_id": f.session_id,
+                "model_raw": f.model_raw,
+                "model_key": f.model_key,
+                "token_kind": f.token_kind,
+                "tokens": f.tokens,
+                "mode": f.mode,
+                "source_quality": f.source_quality,
+            }
+            out.write(json.dumps(record, ensure_ascii=False) + "\n")
+    finally:
+        if args.out:
+            out.close()
+    return 0
+
+
+def cmd_measure(args) -> int:
+    """Machine-readable per-session usage/cost digest for other tools.
+
+    Unlike ``report`` (a human-facing table by default), ``measure`` is a
+    stable JSON contract meant to be parsed by another process (e.g.
+    lane's TelemetryAdapter calling this as a subprocess): fixed top-level
+    keys, a ``protocol_version`` a caller can check, and exit codes a
+    caller can branch on (0 = success, including the case where none of
+    the requested session ids matched anything; 2 = bad input, nothing
+    was measured).
+    """
+    session_ids = list(dict.fromkeys(args.session_id or []))
+    if not session_ids:
+        print("[error] measure requires at least one --session-id", file=sys.stderr)
+        return 2
+
+    try:
+        tz = ZoneInfo(args.timezone)
+    except Exception as exc:  # zoneinfo raises a range of errors for a bad key
+        print(f"[error] invalid --timezone: {args.timezone!r} ({exc})", file=sys.stderr)
+        return 2
+
+    try:
+        since = _parse_window_bound(args.since, tz)
+        until = _parse_window_bound(args.until, tz)
+    except SystemExit as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    agents = set(args.agent.split(",")) if args.agent else {"claude", "codex"}
+
+    try:
+        catalog = load_rates(Path(args.rates) if args.rates else None)
+    except RatesValidationError as exc:
+        print(f"[error] rates catalog invalid: {exc}", file=sys.stderr)
+        return 2
+
+    config = load_config()
+    facts, dq = _collect_facts(config, agents=agents, exclude_archived=False)
+    facts = list(filter_facts(facts, since_utc=since, until_utc=until, agents=agents))
+
+    # measure is a per-session query, not a time-bucketed report: group by
+    # agent/model/token-kind only, never by month.
+    group_by = ("agent", "model", "token-kind")
+
+    requested = set(session_ids)
+    combined_facts = [f for f in facts if f.session_id in requested]
+
+    quality_counts = {v: 0 for v in SOURCE_QUALITY_VALUES}
+    for f in combined_facts:
+        quality_counts[f.source_quality] = quality_counts.get(f.source_quality, 0) + 1
+
+    sessions_payload = {}
+    for sid in session_ids:
+        session_facts = [f for f in combined_facts if f.session_id == sid]
+        rows, _ = build_rows(session_facts, catalog, group_by=group_by, timezone_name=args.timezone)
+        sessions_payload[sid] = {
+            "matched": len(session_facts) > 0,
+            "rows": [r.to_dict() for r in rows],
+            "totals": rows_totals(rows),
+        }
+
+    total_rows, total_dq = build_rows(combined_facts, catalog, group_by=group_by, timezone_name=args.timezone)
+
+    payload = {
+        "protocol_version": MEASURE_PROTOCOL_VERSION,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "window": {
+            "since": since.isoformat() if since else None,
+            "until": until.isoformat() if until else None,
+        },
+        "timezone": args.timezone,
+        "agent": sorted(agents),
+        "rates": {"catalog_version": catalog.catalog_version, "sha256": catalog.sha256},
+        "session_ids": session_ids,
+        "sessions": sessions_payload,
+        "total": {
+            "rows": [r.to_dict() for r in total_rows],
+            "totals": rows_totals(total_rows),
+        },
+        "data_quality": {
+            "malformed_events": dq.malformed_events,
+            "skipped_files": dq.skipped_files,
+            "negative_deltas": dq.negative_deltas,
+            "unpriced_tokens": total_dq.unpriced_tokens,
+            "source_quality": quality_counts,
+        },
+    }
+    print(render_json(payload))
+    return 0
+
+
+def cmd_rates_show(args) -> int:
+    try:
+        catalog = load_rates(Path(args.rates) if args.rates else None)
+    except RatesValidationError as exc:
+        print(f"[error] {exc}", file=sys.stderr)
+        return 2
+
+    if args.model:
+        resolved = catalog.resolve_model_key(args.model)
+        if not resolved:
+            print(f"[unpriced] no rate entry for {args.model!r}")
+            return 0
+        entry = catalog.models[resolved]
+        print(f"model_key: {entry.model_key}  (queried: {args.model})")
+        print(f"aliases: {list(entry.aliases)}")
+        print(f"fast_multiplier: {entry.fast_multiplier}")
+        for period in entry.rates:
+            until = period.effective_until.isoformat() if period.effective_until else "(open)"
+            print(f"  [{period.rate_id}] {period.effective_from.isoformat()} .. {until}")
+            for field_name, value in period.values.items():
+                print(f"      {field_name}: {value if value is not None else '(unpriced)'}")
+        return 0
+
+    print(f"catalog_version: {catalog.catalog_version}")
+    print(f"currency: {catalog.currency}  unit: {catalog.unit}  usd_per_credit: {catalog.usd_per_credit}")
+    print(f"models ({len(catalog.models)}):")
+    for key in sorted(catalog.models):
+        print(f"  - {key}")
+    return 0
+
+
+def cmd_rates_validate(args) -> int:
+    path = Path(args.path) if args.path else None
+    try:
+        catalog = load_rates(path)
+    except RatesValidationError as exc:
+        print(f"[invalid] {exc}", file=sys.stderr)
+        return 1
+    print(
+        f"[ok] {path or '(packaged default)'}: catalog_version={catalog.catalog_version}, "
+        f"{len(catalog.models)} models, sha256={catalog.sha256}"
+    )
+    return 0
+
+
+def cmd_doctor(_args) -> int:
+    config = load_config()
+    ok = True
+
+    print("agent-cost doctor")
+    print(f"  version: {__version__}")
+
+    claude_dir = config.claude_projects_dir
+    if claude_dir.exists():
+        count = sum(1 for _ in claude_dir.glob("*/*.jsonl"))
+        print(f"  [ok] Claude projects dir: {claude_dir} ({count} session files)")
+    else:
+        print(f"  [warn] Claude projects dir not found: {claude_dir}")
+
+    codex_db = config.codex_db_path
+    if codex_db.exists():
+        print(f"  [ok] Codex state DB found: {codex_db}")
+        try:
+            snapshot = codex_reader.snapshot_db(codex_db)
+            try:
+                threads = codex_reader.fetch_threads(snapshot)
+                print(f"  [ok] Codex threads readable via sqlite3 ({len(threads)} threads)")
+            finally:
+                snapshot.unlink(missing_ok=True)
+        except Exception as exc:  # surfaced as a doctor finding, not a crash
+            ok = False
+            print(f"  [error] Codex state DB read failed: {exc}")
+    else:
+        print(f"  [warn] Codex state DB not found: {codex_db}")
+
+    try:
+        catalog = load_rates()
+        print(f"  [ok] rates.json valid: catalog_version={catalog.catalog_version}, {len(catalog.models)} models")
+    except RatesValidationError as exc:
+        ok = False
+        print(f"  [error] rates.json invalid: {exc}")
+
+    return 0 if ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-cost",
+        description=(
+            "Estimate AI coding agent token usage and cost from local logs "
+            "(Claude Code, Codex CLI). Fully offline; makes no network calls."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_report = sub.add_parser("report", help="Aggregate usage and estimated cost")
+    p_report.add_argument("--since", help="ISO date/datetime, inclusive")
+    p_report.add_argument("--until", help="ISO date/datetime, exclusive")
+    p_report.add_argument("--timezone", default="UTC", help="IANA zone for date-only input and month grouping")
+    p_report.add_argument("--agent", help="comma-separated: claude,codex")
+    p_report.add_argument("--group-by", help="comma-separated: month,agent,model,token-kind")
+    p_report.add_argument("--format", choices=["table", "csv", "json"], default="table")
+    p_report.add_argument("--rates", help="path to a rates.json that fully replaces the packaged catalog")
+    p_report.add_argument("--exclude-archived", action="store_true", help="exclude archived Codex threads")
+    p_report.set_defaults(func=cmd_report)
+
+    p_export = sub.add_parser("export", help="Export canonical facts as JSONL")
+    p_export.add_argument("--agent", help="comma-separated: claude,codex")
+    p_export.add_argument("--since")
+    p_export.add_argument("--until")
+    p_export.add_argument("--timezone", default="UTC")
+    p_export.add_argument("--out", help="output path (default: stdout)")
+    p_export.set_defaults(func=cmd_export)
+
+    p_measure = sub.add_parser(
+        "measure",
+        help=f"Machine-readable per-session usage/cost digest ({MEASURE_PROTOCOL_VERSION})",
+    )
+    p_measure.add_argument(
+        "--session-id",
+        action="append",
+        dest="session_id",
+        help="repeatable; at least one required",
+    )
+    p_measure.add_argument("--since", help="ISO date/datetime, inclusive")
+    p_measure.add_argument("--until", help="ISO date/datetime, exclusive")
+    p_measure.add_argument("--timezone", default="UTC", help="IANA zone for date-only input")
+    p_measure.add_argument("--agent", help="comma-separated: claude,codex")
+    p_measure.add_argument("--rates", help="path to a rates.json that fully replaces the packaged catalog")
+    p_measure.add_argument("--format", choices=["json"], default="json")
+    p_measure.set_defaults(func=cmd_measure)
+
+    p_rates = sub.add_parser("rates", help="Inspect or validate a rates catalog")
+    rates_sub = p_rates.add_subparsers(dest="rates_command", required=True)
+    p_rates_show = rates_sub.add_parser("show")
+    p_rates_show.add_argument("--model")
+    p_rates_show.add_argument("--rates")
+    p_rates_show.set_defaults(func=cmd_rates_show)
+    p_rates_validate = rates_sub.add_parser("validate")
+    p_rates_validate.add_argument("path", nargs="?")
+    p_rates_validate.set_defaults(func=cmd_rates_validate)
+
+    p_doctor = sub.add_parser("doctor", help="Check environment and rates catalog health")
+    p_doctor.set_defaults(func=cmd_doctor)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_cost/config.py

@@ -0,0 +1,67 @@
+"""Runtime configuration: where to find each tool's local logs.
+
+Resolution order (highest priority first): environment variables, then
+``~/.config/agent-cost/config.json`` (or the path in ``AGENT_COST_CONFIG``),
+then built-in defaults.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "agent-cost" / "config.json"
+
+
+@dataclass(frozen=True)
+class Config:
+    claude_home: Path
+    codex_home: Path
+    codex_db_filename: str = "state_5.sqlite"
+
+    @property
+    def claude_projects_dir(self) -> Path:
+        return self.claude_home / "projects"
+
+    @property
+    def codex_db_path(self) -> Path:
+        return self.codex_home / self.codex_db_filename
+
+
+def _load_config_file(explicit_path: Optional[Path]) -> dict:
+    config_path = explicit_path or Path(
+        os.environ.get("AGENT_COST_CONFIG", str(DEFAULT_CONFIG_PATH))
+    )
+    if not config_path.exists():
+        return {}
+    try:
+        with config_path.open() as fh:
+            data = json.load(fh)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def load_config(config_path: Optional[Path] = None) -> Config:
+    file_data = _load_config_file(config_path)
+
+    claude_home = Path(
+        os.environ.get("CLAUDE_HOME")
+        or file_data.get("claude_home")
+        or os.path.expanduser("~/.claude")
+    )
+    codex_home = Path(
+        os.environ.get("CODEX_HOME")
+        or file_data.get("codex_home")
+        or os.path.expanduser("~/.codex")
+    )
+    codex_db_filename = str(file_data.get("codex_db_filename") or "state_5.sqlite")
+
+    return Config(
+        claude_home=claude_home,
+        codex_home=codex_home,
+        codex_db_filename=codex_db_filename,
+    )