Codex Sessions Analyser dossier

Product summary

Fact: Codex Sessions Analyser is local-first tooling for inspecting Codex session JSONL logs.

Fact: The repository is intentionally local-only at the start and does not include deployment, provider, Wrangler, Cloudflare, or Google Cloud configuration.

Intended users

• Scott analysing local Codex usage, cost, timing, tool behaviour, and friction.
• Developers wanting deterministic reports over local AI-agent session logs.
• Future AI-agent workflow tooling that needs redacted aggregate telemetry.

Problem being solved

AI-agent work can become opaque: cost, timing, tool waits, failures, compactions, file changes, and recurring friction are buried in session logs. Codex Sessions Analyser reads local logs and produces reports, dashboards, exports, and trend data without uploading raw session content by default.

Current status

Fact: The README describes a working local CLI, static HTML dashboard, Vite dashboard app, SQLite derived cache, CSV/Markdown exports, pricing support, timeline output, and a VS Code helper extension.

Fact: No structured Product Compass-compatible project dossier was found during this pass.

Known aims and strategic intent

• Keep raw session logs local by default.
• Provide deterministic analysis for sessions, costs, timing, tool calls, outputs, file changes, compactions, approvals, and findings.
• Support before/after comparisons around scripts, skills, docs, or instruction changes.
• Support redacted metrics-only sync exports across machines.

Built functionality

Fact: README/package files describe:

• CLI commands for inventory, analyse, report, compare, dashboard, dashboard-data, export, sync-export, and import.
• Core parsing, inventory, reporting, and storage helpers.
• SQLite derived analysis cache using Node's built-in node:sqlite.
• Optional models.dev pricing cache and cost estimates.
• Static local HTML dashboard.
• Vite/React dashboard app using generated JSON snapshots.
• CSV exports for turns, timeline, tool calls, project trends, and related metrics.
• VS Code extension helper to open generated dashboards through Live Preview.

Key apps and packages

Surface	Role
apps/cli	Local command-line interface.
apps/dashboard	Local Vite dashboard.
apps/vscode-extension	VS Code helper extension for dashboard preview workflow.
apps/websites/docs	In-repo Docusaurus docs site package.
packages/core	Parsing, reporting, storage, inventory, and analysis primitives.

Data sources and integrations

Fact: Primary input is local Codex session JSONL under user-controlled paths.

Fact: Optional pricing input can come from models.dev or a saved pricing JSON file.

Fact: Local SQLite stores derived analysis. Redacted sync-export excludes raw cwd values, file paths, command text, prompts, and tool output.

Deployment and runtime assumptions

• Local-only Node/TypeScript monorepo.
• No hosted deployment config at this stage.
• Node 24 may emit an experimental warning for node:sqlite.
• Generated dashboard data is local-only and ignored by Git.

Reusable capabilities

Capability	Reuse potential	Notes
JSONL session parser	High	Could support AI-agent productivity tooling and privacy-safe telemetry.
Timeline/event model	High	Useful for debugging agent flows and measuring tool wait.
Cost/pricing estimator	Medium	Useful for local reports, but model pricing inputs change externally.
Redacted sync export	High	Good privacy boundary for future multi-machine or Hub-style summaries.
Dashboard/report generator	Medium	UI patterns can inform Project Hub or Compass, but raw data shape is specialised.

Notable design patterns

• Raw logs stay on disk and are not uploaded by default.
• Derived cache improves repeated dashboard workflows.
• Pricing is optional and unmatched models remain unpriced rather than guessed.
• Sync export redacts sensitive paths, commands, prompts, and output.
• Compare command supports before/after evaluation of prompt, script, docs, or skill changes.

Dependencies on other products or Meridian tooling

Inference: Codex Sessions Analyser can become a useful internal accelerator for Meridian and Product Compass by identifying which agent instructions or workflows reduce waste and friction.

Inference: Its redacted export model could feed Meridian Hub or Product Compass later, but only if privacy boundaries remain explicit.

Risks and unknowns

• Local session logs can contain sensitive prompts, commands, file paths, and outputs.
• Any future sync/Hub integration must avoid raw log upload by default.
• Pricing data is time-sensitive and external.
• No structured project dossier exists, so generated Compass indexes cannot represent this project yet.

Near-term next steps

• Add a project-owned metadata/project-dossier.json or equivalent AI context file.
• Document which aggregate fields are safe for future Hub/Compass sync.
• Keep redaction tests close to sync/export changes.
• Consider a reusable local JSONL/timeline package only after a second consumer exists.

Longer-term product potential

Opportunity: Codex Sessions Analyser could become a local developer tool, AI productivity report, team-safe redacted metrics exporter, or private Meridian Hub plugin for agent workflow health.

Opportunity: The compare flow can validate whether instruction, skill, or tooling changes actually reduce cost and friction.

AI notes

• Never assume raw session logs are safe to upload or paste.
• Prefer redacted aggregate exports for cross-machine or Hub use.
• Do not guess model pricing when a model is unmatched.
• Treat file paths, prompts, commands, and tool outputs as sensitive by default.

Source coverage

Coverage is README/package-derived. No structured project dossier or durable docs tree was found in the source inventory used for this pass.

Sources consulted

• projects/codex-sessions-analyser/README.md
• projects/codex-sessions-analyser/package.json
• projects/codex-sessions-analyser/apps/cli/package.json
• projects/codex-sessions-analyser/apps/dashboard/package.json
• projects/codex-sessions-analyser/apps/vscode-extension/package.json
• projects/codex-sessions-analyser/packages/core/package.json