Agent Sessions: a local index over 14 AI coding-agent histories on macOS

The problem: session history scattered across fourteen incompatible formats

Every coding agent writes its transcript somewhere different. Codex, Claude Code, Cursor and the rest each pick their own storage: JSONL files, SQLite databases, state directories with names only the agent's authors know. Once you have used three or four of them for a few months, the history is effectively write-only. You remember that you solved a particular build failure in some session, but not which agent, which project, or which week. Grepping by hand across half a dozen hidden directories is the current alternative, and it stops working as soon as the agent stores structured records rather than plain text. Agent Sessions is aimed at the developer who already has that pile of local history and wants one search box over it. The README frames the pitch as finding the session you need, reading the transcript, and resuming supported CLI sessions, with Codex and Claude quota burn shown alongside. It is not a tool for teams sharing transcripts, and it is not a hosted archive. The app is macOS only, distributed as a signed and notarized DMG and a Homebrew cask.

How the indexing works: read-only discovery, local search, no upload

The architecture described in the README is deliberately narrow. Agent Sessions discovers agent session folders, parses them, builds a search index, and serves search and navigation from that index, all on the machine. The README states that agent session folders are read rather than rewritten. That is the important design constraint: the app is a consumer of other tools' on-disk state, not a manager of it, so it does not migrate, normalize or delete your transcripts. Search covers prompts, responses, tool calls, command output, errors, file paths and supported image references. Network access is limited to two things per the privacy section: signed Sparkle update checks and fetching a public model-price list. Neither request carries transcript data, according to the README. The consequence of the read-only model is that capability tracks whatever the underlying agent wrote. If an agent truncates its own history, rotates files, or changes its schema, the app's view degrades with it. The README acknowledges this directly by tying capabilities to the installed CLI version and pointing at STEWARDS.md for format-maintenance owners, verification dates and tested versions.

Install and first run: Homebrew cask or a notarized DMG

Two install paths are documented. The DMG route is a manual download of AgentSessions-5.2.dmg, opening it, and dragging Agent Sessions.app into Applications. The Homebrew route is a single command: brew install --cask jazzyalex/agent-sessions/agent-sessions. Updates arrive through Sparkle and the README says they are signed and notarized. There is no configuration file documented in the supplied material, no environment variables, and no CLI flags. Setup is expected to happen through the app's own interface, where you enable sources and the app reads each agent's local history. That is a deliberate choice for a GUI-first tool, but it also means there is nothing to script and nothing to check into a dotfiles repository. If you administer Macs at scale, the Homebrew cask is the only automatable part of the install; the per-source enablement is a UI action. The README does not describe a headless mode or an export format, so treat the app as an interactive tool rather than a pipeline component.

The Quota Meter, and why the dollar figure is not your bill

The Quota Meter is the feature that goes beyond search. An account-level meter tells you that some percentage of a window is consumed. Agent Sessions attributes that consumption to individual active Codex or Claude sessions, showing per-session burn against the available 5-hour and weekly windows. Four views are listed: 5-hour, weekly, tokens per hour, and estimated API-equivalent dollars per hour, with per-model pricing when a single session uses more than one model. Two caveats matter. The README states plainly that the dollar view is an API-equivalent estimate, not your subscription bill, so it is a relative signal for comparing sessions, not an accounting figure. And the app reports explicit unavailable states when a provider does not expose a usable limit, which is the honest behavior but also means the meter is not universally populated. Release 5.2 tightened the weekly rate calculation to use recent evidence, added Astra and Sol long-context pricing, and made uncertain inputs fail closed. That last phrase is worth noting: when the app cannot be confident about an input, it declines to produce a number rather than guessing.

Where the coverage table stops being a promise

The supported-sources table lists 14 active formats plus legacy Droid sessions, but the resume column is not uniform. OpenClaw is browse-and-search only, with no resume. Qwen Code resume is limited to active sessions and marked end-to-end unverified. Devin CLI resumes supported active sessions. fx has a tested command plan but interactive reopen is unverified. Droid is legacy sessions only, with no active monitoring. Read that as an honest inventory rather than a limitation to be fixed later: the maintainers are distinguishing what they have verified from what they have not. The practical failure mode is a developer installing the app for one specific agent and finding that agent in the unverified row. The README also warns that capabilities differ by source and installed CLI version, so an agent listed as fully supported may behave differently on an older or newer CLI than the one tested. There is also a hard platform boundary. This is a Swift macOS application; the material describes no Linux or Windows build, and the resume integration targets Terminal.app, iTerm2 and Warp, all macOS terminals.

Compared with a plain grep or a general log viewer

The obvious alternative is doing nothing: leaving transcripts in place and searching them with ripgrep or a generic log viewer. That works while the formats stay textual. The Claude Code history guide in the README points at JSONL, which a determined grep can handle, but the OpenCode guide points at SQLite, and the Hermes guide points at a state database. Once the transcript is a database, text search requires knowing the schema, and the schema is not yours. That is the gap Agent Sessions fills: it carries the per-format parsing knowledge so you do not. The trade-off is the reverse of grep's. Grep has no maintenance burden and never breaks when an agent ships a new version; Agent Sessions has to track 14 formats and will lag when one changes. The STEWARDS.md file and the Session-Bench comparison of ten agents across 20 format gates exist precisely because that tracking is ongoing work. If you only use Claude Code, the app is a convenience over reading JSONL yourself. If you use four or five agents, the parsing it absorbs is the reason to install it.

Maintenance, licence and the cost of keeping up with fourteen formats

The project is MIT licensed, which permits commercial and private use and modification, with the usual absence of warranty. This is not legal advice; read the licence text if the distinction matters to you. The maintenance picture is more interesting than the licence. A tool that parses other projects' private storage formats is in a permanent race with those projects' release cycles. The README's own framing, that capabilities differ by installed CLI version, admits this. The mitigation visible in the material is process rather than code: STEWARDS.md names format-maintenance owners and verification dates, Session-Bench publishes evidence-backed format gates, and the contributing section invites a new-source form for missing agents. The release cadence shown in the supplied material is three releases in roughly two weeks during August and September 2026, which suggests active upkeep but also means the app changes often enough that you should read the changelog before upgrading. Release 5.2 also added English and Simplified Chinese localization and an in-app invitation for users to help add another language, so interface coverage outside those two languages is a community contribution rather than a shipped feature.

Editorial conclusion

Adopt Agent Sessions if you run several coding agents on a Mac and regularly need to find an old prompt, tool call or error message. Skip it if you work on Linux or Windows, if you only use one agent, or if you need a format the README lists as unverified. Before relying on it, check STEWARDS.md for the verification date and tested CLI version of each source you care about, and confirm the resume path for your specific agent rather than assuming the table's Yes applies to your installed version.

Official sources

1. jazzyalex/agent-sessions on GitHub
2. License: MIT
3. Project website
4. README
5. Releases