Search Codex and Claude Sessions Locally with Chronicle

Agent work disappears into transcript folders faster than teams admit. A bug gets solved in one Claude Code session, a Codex refactor explores three false starts, a Gemini chat contains the exact command that failed, and a week later the only recovery plan is to grep a pile of JSONL.

Chronicle is worth saving because it treats that history as operational material. It reads Claude Code, Codex CLI, and Gemini CLI session storage directly, indexes metadata into local SQLite, adds search and filters, and can resume the selected session in the right terminal command. The useful article is not a product tour. It is a decision guide for when local session history should become part of a coding-agent workflow.

The adoption boundary

Use Chronicle when past agent sessions have become evidence: why a migration went a certain way, which file an agent edited, what command failed, what model handled a bug, or which terminal session should be resumed. Do not install it just because a transcript browser sounds nice. If you only need one known string, rg ~/.codex/sessions or rg ~/.claude/projects is cheaper. Chronicle starts to pay off when search, provider grouping, tags, pins, stats, transcript rendering, and resume actions save real review time.

What the sources prove

The README proves the product scope: Chronicle is a native macOS browser for Claude Code, Codex CLI, and Gemini CLI history, with local SQLite indexing and per-provider isolation. The security policy proves the privacy boundary: no telemetry, no analytics, no remote logging, and only an optional GitHub Releases update check. The Codex provider and parser code prove this is not just a Claude wrapper: Codex sessions are discovered under ~/.codex/sessions/, parsed from date-bucketed rollout-*.jsonl files, and resumed with codex resume <uuid>. The sources do not prove it is a team audit platform, a compliance archive, or a sandboxed enterprise product. That distinction matters.

Install with the trust cost visible

The clean install path is brew tap josephyaduvanshi/chronicle followed by brew install --cask chronicle. The README also documents .pkg, .dmg, and .zip releases, plus xattr -cr /Applications/Chronicle.app for quarantine cleanup on manual installs. Do not hide the first-launch reality: Chronicle is ad-hoc signed, not notarized, because the project does not currently use a paid Apple Developer ID. For a personal tool this may be acceptable. For a managed corporate Mac, that alone may decide against adoption.

Run a safe first check

A safe trial has five steps. First, confirm the machine is on macOS 15 or newer. Second, install with Homebrew if possible so the package path handles the Applications install and quarantine cleanup. Third, launch Chronicle and let it index the default folders. Fourth, if the sidebar is empty, decide whether granting Full Disk Access is acceptable before enabling it in System Settings. Fifth, search for a session you can already identify manually. The acceptance test is not a pretty UI. It is whether Chronicle finds the same transcript you would otherwise locate by path and timestamp.

Run four verification searches

Before treating Chronicle as part of the workflow, run four checks against sessions you can verify from disk. Search a plain title term that should match a recent Claude session. Search /today to confirm the date bucket is sane. Search /in:<workspace> for a known project and compare the decoded workspace path with the source folder. Then run one transcript query such as /full: error handling and wait for the lazy FTS5 index to populate. If any check returns surprising results, inspect the source JSONL before using pins, stats, or resume actions.

Know exactly what it reads

Chronicle's value comes from reading local files directly. The README names the source folders: Claude Code writes under ~/.claude/projects/, Codex CLI writes under ~/.codex/sessions/, and Gemini CLI writes under ~/.gemini/tmp/. Its own database lives at ~/Library/Application Support/Chronicle/chronicle.sqlite. That is convenient and sensitive. These transcripts may include API keys, passwords, file paths, internal architecture, customer details, or failed commands. Treat Chronicle as a local index over private work history, not as harmless UI state.

Why Codex support matters

The Codex source code is the strongest reason to keep this article in the Codex ecosystem. CodexProvider checks for ~/.codex/sessions/ and stops as soon as it finds a rollout-*.jsonl file. CodexParser documents the real event shapes: session_meta for id, cwd, git state, and provider; response_item for user and assistant turns; event_msg for token counts and thread-name updates; and turn_context for newer model names. CodexResumeBuilder emits codex resume <uuid>, explicitly noting that resume is a subcommand, not a flag. That is implementation-level compatibility, not a vague integration badge.

Search should start narrow

Chronicle supports plain title search and slash filters. Use /today or /this-week when the time window is known. Use /in:project when the workspace is known. Use /tag:client-work after you have tagged important sessions. Save /full: for transcript-level search because the README and FtsIndex source both show that FTS5 is lazy and built when full-text search is needed. A good first query is not /full: auth. It is /in:myapp auth, then /full: auth migration only if title and metadata search do not find the right session.

Resume only after verifying the transcript

One-click resume is useful and dangerous in the same way. Chronicle can route to Ghostty, iTerm, Terminal.app, Alacritty, WezTerm, or kitty, and provider builders choose the right CLI command. Before resuming, open the transcript view and confirm the workspace, model, files touched, and last user request. Resuming the wrong agent session can pull stale assumptions into a live repo. The better workflow is search, inspect, then resume. That turns Chronicle into a review step instead of a jump button.

Use tags and pins as audit markers

The article value is not just search. Pins and tags let a developer mark sessions that explain a decision: migration-source, prod-debug, security-review, or do-not-repeat. Smart folders can then combine workspace, tag, token range, dates, flags, and free text. That gives a solo engineer a lightweight audit habit without turning every agent run into a formal report. The rule is simple: tag sessions that future you would cite in a PR, postmortem, or architecture note.

Respect the privacy line

The README and security policy are clear that transcripts stay local. Chronicle has no telemetry, analytics, or remote logging. Optional iCloud sync writes metadata such as tags, pins, notes, custom titles, and smart folders, not transcripts. That is a strong privacy posture, but it does not remove local risk. The app is unsandboxed, reads sensitive folders, shells out to launch terminals, and stores a searchable index. If the machine is shared, heavily managed, or contains regulated transcripts, local-only is not enough by itself.

Tie privacy claims to the files

The security policy is the evidence anchor here, not the marketing copy. It says the in-scope assets include Chronicle.app, release artifacts, the SQLite database at ~/Library/Application Support/Chronicle/chronicle.sqlite, and the iCloud sync file at ~/Library/Mobile Documents/com~apple~CloudDocs/Chronicle/chronicle-sync.json. It also states the privacy posture: local-only app, no telemetry, no analytics, no remote logging, and an optional GitHub Releases update check. The README adds the operational detail that iCloud sync stores metadata only and that transcripts remain on the device that generated them. That supports a local-first claim; it does not support a claim that the data is low-risk.

Where the Linux CLI fits

The companion chronicle CLI is useful on remote Linux boxes, but it is a different product surface. The README says it reads the Claude ~/.claude/projects/ tree directly, exposes chronicle list, chronicle sessions, chronicle search, and chronicle show, and skips SQLite and FTS. That makes it a lightweight transcript utility, not the full macOS history browser. Use it to inspect remote Claude sessions; do not evaluate the whole Chronicle workflow from the Linux CLI alone.

Skip it in these cases

Skip Chronicle if you cannot run macOS 15, cannot accept an ad-hoc signed app, cannot grant local file access to transcript folders, or need a shared team audit trail. Skip it if your agent history is small enough for direct filesystem search. Also skip it if the main need is project documentation retrieval; a knowledge-base tool such as Lore solves a different problem. Chronicle is for past agent sessions. It should help you find and resume work that already happened, not become the place where project truth lives.

A workflow worth publishing

A practical workflow looks like this: install Chronicle, let it index, verify one Claude session and one Codex session against their source folders, run a title search, run one /full: query, tag two sessions that explain a decision, and resume one known session with the right terminal. After that, add a team convention: important agent sessions get tagged before a PR is merged. That is where Chronicle becomes more than a convenience app. It creates a local trail for agent-assisted engineering decisions.

Save Chronicle as a local session-history operations article. It is valuable when Claude Code and Codex transcripts need search, inspection, tagging, and careful resume workflows, but it is not a shared compliance system or a substitute for writing decisions down.

Practical takeaway

Install with brew tap josephyaduvanshi/chronicle and brew install --cask chronicle, then verify one known transcript from ~/.claude/projects/ or ~/.codex/sessions/ before trusting the index. Use /in:, /tag:, /today, and /full: searches deliberately. Inspect workspace, files touched, model, and last request before using codex resume <uuid> or claude --resume <uuid> from the app.