ContextQMD
Back to Codexbar

Codex Workspaces local index

docs/codex-workspaces.md

0.46.04.1 KB
Original Source

Codex Workspaces local index

Codex Workspaces attributes the existing local Codex cost scan to projects, sessions, models, and days. This foundation is local-only library behavior; it does not add a remote API, provider authentication flow, billing interface, or public CLI JSON contract.

Data flow

CostUsageScanner remains authoritative for JSONL parsing, cumulative-token deltas, fork and subagent accounting, pricing, and incremental cursors. The Workspaces index combines that scan cache with the read-only Codex thread catalog:

  1. Scan local rollout JSONL into the Codex v11 cost cache.
  2. Read catalog metadata without modifying the Codex catalog.
  3. Canonicalize workspace attribution and scope it to the selected Codex home.
  4. Publish the complete source state and derived snapshot in one SQLite transaction.
  5. Expose project, session, model, daily, source-status, progress, and CSV library models to presentation consumers.

The supported internal presentation boundary is:

  • CostUsageFetcher.loadCachedCodexLocalProjectUsageSnapshot
  • CostUsageFetcher.loadCodexLocalProjectUsageSnapshot
  • CostUsageFetcher.clearCachedCodexLocalProjectUsageSnapshot
  • CodexLocalProjectUsageSnapshot
  • CodexLocalProjectUsageIndexProgress

Persistence contracts

The Codex cost cache is:

text
~/Library/Caches/CodexBar/cost-usage/codex-v11.json

The Workspaces sidecar is:

text
~/Library/Caches/CodexBar/local-usage/codex-workspaces-v1.sqlite

The sidecar currently uses SQLite schema version 5 and snapshot payload format 3. This is the first released Workspaces schema. A database with any other PRAGMA user_version is rejected as incompatible and is never modified.

v10 to v11

codex-v10.json is not migrated in place and is not accepted as a v11 incremental cursor. Parser and attribution semantics changed, so the first scan after upgrading performs a one-time rebuild and writes a separate v11 artifact. The v10 file remains untouched and recoverable. The v11 file is replaced atomically only after a successful scan; later v11 refreshes can use the normal incremental cursor.

Sidecar rollback

Publication is transactional: a failed synchronization or snapshot write rolls back and leaves the previous complete snapshot available.

Catalog completeness and last-good data

Catalog access distinguishes complete, missing, locked, corrupt, and incompatible states. A complete read replaces catalog metadata for that Codex home scope. A later same-scope incomplete read reports partial or stale source status while retaining the last-good catalog attribution and usage snapshot. Sparse rollout updates do not erase retained titles, workspace paths, or other catalog metadata.

Scope identifiers and invalidation fingerprints are hashes; raw Codex-home paths are not persisted as scope identifiers. Changed and deleted rollout files, parser or pricing changes, history-window changes, and catalog changes invalidate only the affected cached state.

Cost and display semantics

Known model cost and unknown-cost coverage are represented separately. Unknown pricing never becomes a synthetic zero-cost claim. Models analytics, parity checks, performance telemetry, and CSV serialization operate on the same persisted snapshot.

Display-only projections are transient:

  • Hiding estimated cost does not rewrite the sidecar.
  • Including or excluding cached input does not rescan or rewrite the sidecar.
  • Hiding personal information removes persisted workspace paths, working directories, workspace names, and session titles from snapshots before they reach presentation code; it does not rewrite the local sidecar.
  • Rankings, totals, charts, and breakdowns must use the same projection.

Privacy boundary

The scanner, catalog reader, cache, sidecar, analytics, and CSV serializer run locally. They do not upload rollout contents or catalog records. The stored index can contain local workspace paths, session metadata, token totals, and derived cost estimates, so runtime evidence must be sanitized before publication. Remove paths, titles, session IDs, identities, tokens, keys, network addresses, and database row contents from shared logs and screenshots.