Agent Sessions: one Mac app for 15 local coding-agent histories

The problem: fifteen session stores and no index across them

Every coding agent writes its own history in its own shape. Codex, Claude Code, Cursor, Copilot CLI, OpenCode, Antigravity, Pi, Kimi Code, Grok CLI, Hermes, OpenClaw, Qwen Code, Devin CLI and fx each keep transcripts somewhere under the user's home directory, in JSONL, SQLite, or a state database depending on the tool. The README describes the result plainly: sessions you cannot find again once the terminal window is closed.

The audience is narrow and specific. You need a Mac, you need more than one agent installed, and you need to go back to old work. That last condition is what separates Agent Sessions from a novelty viewer. A developer who starts a fresh session each morning and never revisits it has nothing to index. A developer who spends an afternoon hunting for the prompt that produced a working migration does.

The README also lists a second job the app takes on: for Codex and Claude, showing which sessions are consuming quota. That is a different problem from search, and it is the one with the most caveats attached.

How the index is built and what stays on disk

The repository is a Swift macOS application, split into AgentSessions, AgentSessionsLogicTests and AgentSessionsTests targets inside AgentSessions.xcodeproj, plus a Resources directory and a scripts directory. The README states that transcript discovery, parsing, indexing, search and navigation all happen locally, and that agent session folders are read rather than rewritten. That read-only stance matters: pointing the app at a live agent directory should not corrupt the store the agent itself is still appending to.

Search covers more than prompt text. According to the README, the index spans prompts, responses, tool calls, command output, errors, file paths and supported image references. That is a wider surface than a grep over JSONL, because tool output and error strings are often the only thing you remember about a session.

Network access is limited to two named cases: signed Sparkle update checks and a fetch of a public model-price list. The README says neither request contains transcript data. There is no telemetry. The trade-off is that the price list is remote, so the estimated cost view depends on an external file rather than anything bundled.

Installing Agent Sessions and finding a session

The README offers two install paths. The direct one is the v5.2 disk image from the releases page: download AgentSessions-5.2.dmg, open it, and drag Agent Sessions.app into Applications. The Homebrew path is a single cask command.

brew install --cask jazzyalex/agent-sessions/agent-sessions

After the cask finishes, Agent Sessions appears in Applications like any other app. Updates arrive through Sparkle and the README states they are signed and notarized.

On first launch the app scans the agent directories it knows about. The README does not document a configuration file or a path override for pointing it at a non-standard session directory, so if your agent writes somewhere unusual, expect to check the supported-sources table before assuming it will appear.

Once sessions are listed, the workflow is search then resume. The README says you can copy a resume command or open a supported CLI session in Terminal.app, iTerm2, or Warp. The resume column of the table is not uniform: OpenClaw is listed as No, Droid has no active monitoring, and Qwen Code, Devin CLI and fx carry verification notes rather than a plain Yes.

# illustrative only: the README does not publish the exact resume command string

The README does not give the literal resume command text for any agent, so the safe move is to use the copy action in the app rather than reconstructing the command yourself.

The Quota Meter is an estimate, and the README says so

The Quota Meter is the feature most likely to be misread. It shows per-session burn for Codex and Claude against available 5-hour and weekly windows, with four views: 5-hour, weekly, tokens per hour, and estimated API-equivalent dollars per hour. Per-model pricing applies when one session uses more than one model.

The README is explicit that the dollar view is an API-equivalent estimate, not your subscription bill. That distinction is the whole feature. If you are on a flat-rate plan, the dollar number tells you what the same tokens would have cost through the API, which is a useful relative signal between sessions and a misleading absolute one.

The 5.2 release notes add a second caveat: weekly rates use stricter, recent evidence, and uncertain inputs fail closed. Failing closed means the meter shows an unavailable state rather than a guess. The README also notes explicit unavailable states when a provider does not expose a usable limit. A meter that refuses to render a number is less satisfying than one that always shows something, and more honest.

Where Agent Sessions is the wrong tool

The platform limit is absolute. This is a macOS app built with Swift and shipped as a signed, notarized disk image plus a Homebrew cask. There is no Linux or Windows build described anywhere in the README, and no server component to run headless. If your agents live on a remote box or in a container, the session files are not on the Mac and the app has nothing to index.

The second limit is per-source, and it is the one that will bite quietly. The README states that capabilities differ by source and installed CLI version. A source can support browsing and search while its resume path is unverified. Qwen Code is listed as "Active sessions; end-to-end unverified"; fx is "Command plan tested; interactive reopen unverified". Those labels are unusually candid for a project README, and they should be read as instructions: check the row for your agent before you depend on resume.

Third, this is a viewer over files other tools own. If an agent changes its on-disk format, the app's parser for that source is what breaks, and the fix depends on the maintainer's schedule. The last push was on 2026-09-10, and STEWARDS.md is the file that records format-maintenance owners and verification dates, which is where you look when a source stops appearing.

Alternatives and the real difference in approach

The obvious alternative is not another app. It is the shell: grep, jq and ripgrep over the agent's own JSONL or SQLite files. That approach has no install, no index build, and no per-source parser to go stale. It also has no unified view. You need to know where each agent stores history and in what schema, and every query is written against one format. Agent Sessions trades that per-format work for a single search box and a supported-sources table that tells you which formats are covered.

A second comparison is with the agent vendors themselves. Codex and Claude Code both expose their own history and quota surfaces, and for a single-agent user those are usually enough. The difference is scope: a vendor view covers its own sessions, while Agent Sessions spans 14 active formats plus legacy Droid sessions in one index. Cross-agent search is the entire reason the project exists, and it is the only feature a single-agent user cannot get from the vendor tool.

Session-Bench, linked from the README, compares ten agents across 20 evidence-backed format gates. That is the project's own measurement of format coverage, so read it as a claim by the maintainer rather than an independent result.

Licence, maintenance and upgrade cost

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is the standard permissive position and it places no obligation on you to publish changes. It also means no warranty, and nothing in the README suggests a support contract or a paid tier. This is a description of the licence text, not legal advice; if you are redistributing the app inside a company, have someone read the actual LICENSE file rather than this paragraph.

Upgrade cost is low by design. The README states that updates are signed, notarized and delivered through Sparkle, so the app updates itself rather than requiring a manual reinstall. The Homebrew cask path updates the same way, through brew upgrade. Release cadence is visible in the repository: v5.2 on 2026-09-09, v5.1.1 on 2026-08-31, v5.1 on 2026-08-27. That is a tight sequence, and the last push to the repository was on 2026-09-10.

The maintenance risk sits with the parsers, not the app shell. Each supported source is a format that some other project controls, and the README points to STEWARDS.md for format-maintenance owners, verification dates and tested versions. When an agent ships a format change, that file is the first place to check whether the source has been re-verified.

Editorial conclusion

Adopt Agent Sessions if you run several coding agents on one Mac and keep losing the session where a fix actually worked; the search index and the resume command are the payoff. Skip it if you work on Linux or Windows, or if you only ever use one agent, since its value is cross-agent search rather than any single integration. Before relying on it, verify which of your installed agents appear in the supported-sources table with a Yes in both columns, and check STEWARDS.md for the tested CLI version, because the README states that capabilities differ by source and installed CLI version.

Frequently asked questions

Official sources

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