codex-optic

Zero-dependency, local-first TypeScript library for reading OpenAI Codex session data from ~/.codex/.

Bun-only. macOS only (for now).

Install

bun add codex-optic

Usage

import { createCodexHistory } from "codex-optic";

const history = createCodexHistory();

// Index tier — instant, reads history.jsonl only
const sessions = await history.sessions.list();
const today = await history.sessions.list({ date: "2026-02-14" });

// Meta tier — reads rollout headers for model/cwd/tokens
const withMeta = await history.sessions.listWithMeta();
for (const s of withMeta) {
  console.log(s.model, s.totalInputTokens, s.cwd);
}

// Full tier — parses entire rollout file
const detail = await history.sessions.detail(sessions[0].sessionId);
console.log(detail.assistantMessages, detail.toolCalls);

// Watch — yields new sessions as they appear
const handle = history.sessions.watch();
for await (const session of handle.sessions) {
  console.log("New session:", session.sessionId);
}
// handle.stop() to clean up

API tiers

| Tier | Method | Reads | Speed | |------|--------|-------|-------| | Index | list(filter?) | history.jsonl | Instant | | Meta | listWithMeta(filter?) | + rollout headers | Fast | | Full | detail(sessionId) | + entire rollout | Slow | | Watch | watch(filter?) | fs.watch on history | Live |

Privacy

Privacy redaction is applied by default. The local profile strips base_instructions, developer messages, reasoning encrypted content, and function call outputs.

// Profiles: "local" (default), "shareable", "strict"
const history = createCodexHistory({ privacy: "strict" });

// Or customize
const history = createCodexHistory({
  privacy: { redactPrompts: true, redactHomeDir: true },
});

License

MIT