agent-odometer: Instructions file for Codex

AGENTS.md

These instructions apply to the entire repository.

Project purpose

Odometer is a local Tauri companion to agent CLI harnesses: the ChatGPT desktop app's Codex experience and Claude Code. It reads each harness's session JSONL files and presents searchable task, turn, token, subagent, and estimated cost data in per-harness tabs. Rust owns filesystem access, parsing, persistence, pricing, and Tauri IPC; Svelte owns filtering, presentation, and aggregation of already-priced values.

Start with README.md for commands and docs/ARCHITECTURE.md for the data flow, contracts, invariants, and known limitations.

Before changing code

• Run git status --short and preserve unrelated work. Do not normalize or rewrite existing files as a side effect.
• Treat src-tauri/gen/schemas/ as generated. Do not hand-edit it; commit generated changes only when an intentional Tauri capability/configuration change requires them.
• Both lockfiles are authoritative and should stay committed. Use npm ci and Cargo's --locked flag for reproducible validation.
• Never commit real Codex sessions, prompts, local paths, credentials, or platform config. Parser fixtures must be synthetic or thoroughly redacted.

Architecture boundaries

• Keep filesystem access and JSONL parsing in Rust. The frontend should receive typed data through Tauri commands/events, not read session files directly.
• Keep pricing in the shared Rust query service (query.rs and query_desktop.rs). Frontend code may sum returned costs and use src/lib/currency.ts for presentation, but must not resolve rates or calculate token prices. Preserve the frozen bucket and detail pricing oracles; do not restore a duplicate TypeScript calculator in tests or browser mocks.
• Saved rate-card replacements invalidate priced responses by object identity, even when RateCard.version is unchanged. Preserve raw totals, mark obsolete costs unavailable, and refetch batched prices; reject superseded successes and failures before updating caches or tray output.
• Put Rust commands in src-tauri/src/commands.rs, register them in src-tauri/src/lib.rs, and expose typed frontend wrappers in src/lib/ipc.ts.
• Keep Rust serialized structs and src/lib/types.ts synchronized. Add backward-compatible Serde defaults when persisted or historical data may omit a new field.
• Event names are contracts: session-updated (payload: SessionSummary), session-removed, scan-progress (payload: ScanStatus), history-progress (payload: HistoryStatus), config-updated, and rates-updated. Update every producer and listener together. Full sessions travel only through get_session_details; keep SessionSummary free of turns/tokens_history — the split exists because full sessions measured ~200 MB across a real corpus.
• history-progress (#116) mirrors scan-progress's contract for the durable-history archive: AppState starts in a third Pending state (distinct from an archive that is genuinely Unavailable) until commands::spawn_history_open resolves it on a background thread, emitting one event per migration step plus a terminal ready/unavailable event. The frontend calls get_history_status once on mount (events may have already fired) and then follows the event, matching scan-progress/get_scan_status. commands::sessions_in_ranges — the ledger accounting authority — checks AppState::history_readiness() directly and returns an explicit "still preparing" error while Pending, rather than falling back to a partial in-memory answer that would look complete.
• Use the established Svelte 5 rune style ($state, $derived, $effect). Module-level rune state belongs in *.svelte.ts files.
• Keep Tauri capabilities minimal. Do not add remote content, network access, shell execution, or broader capabilities without an explicit requirement and a security review. Current exceptions: updater:default and process:allow-restart exist solely for the in-app auto-updater.