agent-sessions - Full Setup Guide¶
Repo: jazzyalex/agent-sessions | ⭐ 683 Author: jazzyalex | Language: Swift | License: MIT Platform: macOS (native SwiftUI)
agent-sessions is a local-first macOS app that lets you browse, search, analyze, and resume AI coding-agent session histories across Hermes Agent, Claude Code, Codex, and Cursor. All session data stays on your machine - no cloud sync, no telemetry.
Prerequisites¶
- macOS 14 (Sonoma) or later
- At least one supported agent runtime installed (Hermes Agent, Claude Code, Codex, or Cursor)
- Xcode 16+ (only if building from source)
Installation¶
Option A: Download from GitHub Releases (Recommended)¶
- Go to the Releases page
- Download the latest
.dmgfile - Open the DMG and drag
agent-sessions.appto your Applications folder - On first launch, right-click → Open to bypass Gatekeeper (the app is not notarized yet)
Option B: Build from Source¶
git clone https://github.com/jazzyalex/agent-sessions.git
cd agent-sessions
open agent-sessions.xcodeproj
# In Xcode: Product → Archive → Distribute App → Copy App
Configuration¶
1. First Launch¶
On first launch, agent-sessions scans standard agent session directories:
| Agent | Default Session Path |
|---|---|
| Hermes Agent | ~/.hermes/profiles/*/state.db |
| Claude Code | ~/.claude/sessions/ |
| Codex | ~/.codex/sessions/ |
| Cursor | ~/Library/Application Support/Cursor/User/workspaceStorage/ |
2. Custom Session Paths¶
If your sessions are stored in non-standard locations:
- Open agent-sessions → Settings (⌘,)
- Click the Sessions tab
- Click + to add a custom path
- Browse to your session directory
- agent-sessions auto-detects the format
3. Supported Formats¶
agent-sessions auto-detects these session formats:
- Hermes Agent: SQLite state databases (.db)
- Claude Code: JSON session files
- Codex: Session directories with metadata
- Cursor: VS Code workspace storage
Usage¶
Browsing Sessions¶
The main window shows all sessions across all agents, sorted by last activity:
- Left sidebar: Agents and session groups
- Center panel: Session list with preview snippets
- Right panel: Full session transcript (read-only)
Searching Sessions¶
Press ⌘F to search across all sessions:
- Full-text search: Searches all messages in all sessions
- Agent filter: Click agent icons to filter by runtime
- Date range: Use the calendar picker to narrow by date
- Bookmark: Click ★ to bookmark important sessions
Resuming Sessions¶
To resume a session in its original agent:
- Select the session in the list
- Click Resume (or press ⌘R)
- agent-sessions opens the agent with the session context restored
Note: Resume behavior varies by agent:
- Hermes Agent: Opens a new terminal with hermes --resume <session-id>
- Claude Code: Opens Claude Code with the session file
- Codex: Opens Codex with --session flag
- Cursor: Opens the workspace
Analyzing Sessions¶
Click the Analytics tab (⌘2) for session insights:
- Token usage trends: Per-agent, per-session, per-day
- Tool call frequency: Which tools are used most
- Session duration: How long sessions typically run
- Model usage: Which models are called most often
Integration with Hermes Agent¶
Hermes Session Path¶
agent-sessions auto-discovers Hermes sessions at:
~/.hermes/profiles/<profile-name>/state.db
If you use multiple Hermes profiles (e.g., corpusiq, default), agent-sessions lists all of them.
Hermes Session Format¶
Hermes stores sessions as rows in a SQLite database. agent-sessions reads:
- sessions table: session metadata, timestamps
- messages table: individual message content, role, tool calls
- tools table: tool execution logs
Known Limitation¶
Hermes sessions stored in ~/.hermes/profiles/ may be locked by a running Hermes gateway. If agent-sessions shows "Database locked," close the Hermes gateway first or use a read-only copy.
Troubleshooting¶
"No sessions found"¶
Cause: agent-sessions couldn't find any agent session directories.
Fix:
1. Open Settings → Sessions
2. Verify session paths are correct
3. Click Rescan to force a re-scan
4. Check that sessions exist: ls ~/.hermes/profiles/*/state.db
"Unsupported format"¶
Cause: The session format is not recognized.
Fix: Check the repo issues for format support requests. Currently supported: Hermes SQLite, Claude Code JSON, Codex metadata directories, Cursor workspace storage.
"Database locked" (Hermes)¶
Cause: Hermes gateway has an active write lock on the state database.
Fix:
# Stop the Hermes gateway
hermes gateway stop
# Open agent-sessions (it reads the DB in read-only mode)
# Restart gateway when done
hermes gateway start
Security Notes¶
- All data stays local. agent-sessions reads session files directly - nothing is uploaded.
- No network access. The app does not phone home or send telemetry.
- Read-only by default. agent-sessions never modifies session data unless you explicitly save a bookmark.
- Build from source if you want to audit the code before running.
Alternatives¶
| Tool | Platform | Stars | Notes |
|---|---|---|---|
| agent-sessions | macOS | 683 | This guide |
| Hermes WebUI | Web | 15K | Full agent control panel |
| Hermex | iOS | 450 | Native iPhone app |
| OpenClaw Session Viewer | CLI | - | Built into OpenClaw |
Guide last updated: July 4, 2026 | Repo | Report issue
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.