Development
Plugin
agent-sessions
Live per-session quota burn for Codex and Claude — see which session is eating your 5-hour and weekly limits, priced per model.
Plugin Signal76/100Solid
maintained99
capable41
documented100
adopted61
Install
$ npx -y skills add jazzyalex/agent-sessions --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
What's inside
Skills
6/deployUse when shipping a release of Agent Sessions — bumping version, updating CHANGELOG, building, signing, notarizing, publishing appcast, and creating a GitHub release./release-notesUse when writing or curating the user-facing release copy for an Agent Sessions release — README "What's New", GitHub release notes, Sparkle release notes, or website/launch copy. Not for the internal CHANGELOG, which stays a full development history./add-agent-supportCreate and ship AgentSessions support for a new or changed local AI agent/provider. Use when adding, reviewing, testing, documenting, or marketing a provider integration, session parser, transcript source, support-matrix entry, verified-version bump, or provider UI surface;/agent-session-format-checkVerify agent session format compatibility for Agent Sessions. Use when any agent CLI updates, when monitoring flags drift, or when bumping max verified versions (fixtures + docs + tests). Covers session schema, usage/limits tracking, storage backends, and discovery path/agent-support-matrixMaintain Agent Sessions agent support matrix and JSON/JSONL parsing compatibility. Use when checking upstream agent releases for session format changes, updating max verified versions in docs/agent-support/agent-support-matrix.yml, or updating docs/agent-json-tracking.md and/sc-skillCapture deterministic macOS screenshots for testing, docs, release notes, and marketing assets. Use when asked to automate app screenshots, batch-generate screenshot sets, standardize window sizing/composition, or choose between Peekaboo and native macOS screenshot tooling.
Badges
1
README
1Agent Sessions (macOS)
Live per-session quota burn for Codex and Claude — see which session is eating your 5-hour and weekly limits, priced per model. Plus a searchable history across Codex, Claude, OpenCode, Cursor, GitHub Copilot CLI, Pi, Kimi Code, Antigravity CLI, Hermes, and OpenClaw — transcripts, images, and one-click resume. macOS, local-only.
Session Bench: how ten agents' session formats score — 19 pass/fail gates, evidence behind every cell.
If Agent Sessions hands you back something you thought you'd lost, star the repo. It is the only thing this project asks for.
- Requires: macOS 14+
- License: MIT
- Security & Privacy: Local-only. No telemetry. Details:
docs/PRIVACY.mdanddocs/security.md
New in 4.7 — Kimi Code joins as the tenth current agent source, active Claude cloud sessions appear in the Quota Meter, and Pi and Cursor sessions get back the working directory their resume commands and project filters depend on. See what's new ↓
Overview
Run three agents at once and a normal quota meter tells you "60% used" — not which one spent it. Agent Sessions attributes burn to the individual session, live, against your Codex and Claude 5-hour and weekly windows. Pick the lens you want (5-hour, weekly, tokens/hour, or dollars); the $ lens prices each model in a session at its own rate, so an Opus orchestrator driving Sonnet subagents is costed per model instead of blended into one number.
It's also a local-first Mac app for finding useful work coding agents already wrote to disk — Codex, Claude, OpenCode, Cursor Agent, Hermes, OpenClaw, Antigravity, GitHub Copilot CLI, Pi, and Kimi Code histories in one searchable view, with transcript inspection, image browsing, saved-session recovery, and resume commands for supported CLIs.
Security & Privacy
- Local-first: session data stays on your Mac.
- No telemetry, analytics, remote logging, advertising identifiers, or session-history uploads.
- Reads local session folders you choose, plus supported default CLI locations.
- Builds local indexes/databases for search and navigation.
- Explicit actions may open Terminal/iTerm2 resume commands or run status/probe cleanup workflows.
- The only network activity is optional Sparkle update checks and an optional read-only fetch of a public model-price list (for the runway's $ estimate) — neither sends any personal or session data.
Details: docs/PRIVACY.md and docs/security.md.
What's New in 4.7
TL;DR - Kimi Code is the tenth current agent source Agent Sessions reads, active Claude cloud sessions now show up in the Quota Meter, and a working-directory bug that quietly broke resume commands and project filtering for Pi and Cursor is fixed.
New in 4.7:
- Kimi Code, the tenth current agent source — sessions in the list, in search and in Analytics, with tool calls and assistant output in the transcript, a toolbar filter pill, Copy Resume Command and terminal resume. It switches itself on when Kimi Code is on your Mac.
- Claude cloud sessions in the Quota Meter — sessions running on Anthropic's infrastructure were invisible outside Claude Desktop; they now sit beside your local agents, marked Cloud. Off by default, offered once you have saved a claude.ai cookie.
- Pi and Cursor get their working directory back — resume commands came back without the
cd, and the search index stored no path at all, so filtering by project silently missed those sessions. History you already have is repaired in the background after you update. - A resume that fails now says so — every failure reason produced an error nothing displayed, so a refused launch looked exactly like no launch. Warp in particular used to report success when it never opened.
- Checking an agent's CLI no longer freezes the window — eight of the agent coordinators probed binaries on the main thread with no timeout, so a slow shell profile hung the whole app.
Recent releases — 4.6.4: Compact and Full Agent Cockpit retired, leaving the Quota Meter as the only mode. 4.6.3: the footer usage meters can finally be switched off. 4.6.2: Codex guardian sessions nest under their parent instead of duplicating it. 4.6: paste-a-cookie Claude web usage, no CLI or Full Disk Access needed. Full history in the changelog.
Core Features
- Browse and search Codex CLI, Codex Desktop, and Codex VS Code sessions in one place.
- Browse Claude CLI and Claude Desktop sessions with consistent labels and project context.
- Browse Cursor Agent transcripts from Cursor's local storage, enriched with Cursor chat metadata when available.
- Hermes Agent sessions participate in browsing, search, filtering, analytics, and resume workflows, including current
~/.hermes/state.dbstorage. - OpenClaw sessions participate in browsing, search, filtering, deleted-session visibility, and resume workflows while ignoring trajectory traces.
- Pi CLI sessions now participate in browsing, search, filtering, and resume workflows.
- Unified browsing across supported agents, with strict filtering, saved sessions, and a single session list.
- Unified Search and Image Browser across sessions, plus in-session Find for fast transcript navigation.
- Readable tool calls/outputs and navigation between prompts, tools, and errors.
- Right-click Copy Resume Command or Resume for supported CLI sessions, with Terminal.app, iTerm2, and Warp launch targets.
- Quota Meter with Session Runway shows live burn rate per session against your Codex and Claude 5-hour and weekly limits — in percent, tokens/hour, or dollars priced per model.
- Local-only indexing designed for large histories.
Quota Meter — Session Runway
An ordinary quota meter says "60% used." It won't say which of your three running agents spent it. The Quota Meter attributes burn to the individual session, live, against your Codex and Claude 5-hour and weekly windows.
- Per-session burn bars — each active session gets its own rate against the live window, so you know which one to stop.
- Four lenses — 5-hour, weekly, tokens/hour, or dollars; chosen from the meter and remembered.
- Priced per model — the
$lens rates each model in a session at its own rate, so an Opus orchestrator driving Sonnet subagents is costed at what each actually runs at rather than blended into one number. - Honest states — a calm "no limit" when a provider drops a window, and "can't verify" rather than a wrong number if usage data changes shape.
- Stays where you put it — drag it anywhere, right-click for controls. Show or hide it from the View menu (⌘⌥⇧C).
Quota Meter Setup
Prerequisites
- Agent Sessions with live session detection enabled
- Agents running in a terminal, or in Codex or Claude Desktop
Ideal Setup
Session rows read best when your terminal names them clearly:
- Set the terminal window title to the repo name
- Run that repo's agents in that window
- Give each tab/session its own clear name
- Use the same name for the tab, session, and badge
Layout
- One repo per desktop/Space if possible
- Or keep several on one desktop if you prefer
- Keep the Quota Meter pinned in a corner so you can always see activity
Install
Option A — Download DMG
- Download AgentSessions-4.7.dmg
- Drag Agent Sessions.app into Applications.
Option B — Homebrew
brew tap jazzyalex/agent-sessions
brew install --cask agent-sessions
Automatic Updates (Sparkle)
Agent Sessions uses Sparkle for automatic updates (signed + notarized).
To force an update check (for testing):
defaults delete com.triada.AgentSessions SULastCheckTime
open "/Applications/Agent Sessions.app"
Documentation
- Guides:
- Release notes:
docs/CHANGELOG.md - Monthly summaries:
docs/summaries/ - Privacy:
docs/PRIVACY.md - Security:
docs/security.md - Maintainers:
docs/deployment.md
Resume Workflows
- Right-click any supported CLI session and choose Copy Resume Command to get the exact CLI command for that session.
- Open supported Resume sessions in your preferred terminal: Terminal.app, iTerm2, or Warp.
- Use Unified Search (across sessions) and Find (within a session) to jump to relevant tool calls and outputs quickly.
Privacy & Security
- Local-only. No telemetry.
- Reads agent session directories in read-only mode:
~/.codex/sessions~/.claude/projects~/.gemini/antigravity/brain~/.copilot/session-state~/.cursor/projectsand~/.cursor/chats~/.factory/sessionsand~/.factory/projects~/.hermes/state.dband~/.hermes/sessions~/.openclaw/agentsand legacy~/.clawdbot/agents~/.pi/agent/sessions~/.local/share/opencode/opencode.dband~/.local/share/opencode/storage/session
- Details:
docs/PRIVACY.mdanddocs/security.md
Development
Prerequisites:
- Xcode (macOS 14+)
Build:
xcodebuild -project AgentSessions.xcodeproj -scheme AgentSessions -configuration Debug -destination 'platform=macOS' build
Tests:
xcodebuild -project AgentSessions.xcodeproj -scheme AgentSessionsTests -destination 'platform=macOS' test
Contributing:
CONTRIBUTING.md
License
MIT. See LICENSE.
File tree
1098jazzyalex/agent-sessionsView on GitHub
.claude/
analytics-layout-spec.md
skills/
agent-session-format-check.md
deploy/
deploy.md
SKILL.md
release-notes/
SKILL.md
.codex/
hooks/
xcode_build_policy.py
.git-tools/
edit_msg.sh
reword_all.py
.github/
FUNDING.yml
workflows/
ci.yml
.gitignore
.mailmap
.superpowers/
brainstorm/
36235-1773789975/
.server-stopped
.server.pid
53979-1773791855/
.server-info
name-display-modes.html
rename-popover.html
toolbar-and-menu.html
waiting.html
.swiftlint.yml
agents.md
AgentSessions/
AgentSessions.xcodeproj/
project.pbxproj
xcshareddata/
xcschemes/
AgentSessions.xcscheme
AgentSessionsLogicTests.xcscheme
AgentSessions.entitlements
AgentSessionsApp.swift
Analytics/
Models/
AnalyticsData.swift
AnalyticsDateRange.swift
README.md
Repositories/
AnalyticsRepository.swift
Services/
AnalyticsService.swift
Utilities/
AnalyticsColors.swift
AnalyticsDesignTokens.swift
Views/
AgentBreakdownView.swift
AnalyticsView.swift
AnalyticsWindowController.swift
SessionsChartView.swift
StatsCardsView.swift
TimeOfDayHeatmapView.swift
AntigravityResume/
AntigravityResumeCommandBuilder.swift
AntigravityResumeCoordinator.swift
AntigravityResumeTypes.swift
AntigravityTerminalLauncher.swift
Assets.xcassets/
AppIcon.appiconset/
Contents.json
icon_128x128.png
icon_128x128@2x.png
icon_16x16.png
icon_16x16@2x.png
icon_256x256.png
icon_256x256@2x.png
icon_32x32.png
icon_32x32@2x.png
icon_512x512.png
icon_512x512@2x.png
AxisGridline.colorset/
Contents.json
CardBackground.colorset/
Contents.json
chatgpt_8bit_alpha.imageset/
chatgpt_8bit_alpha.png
Contents.json
claude_8bit_alpha.imageset/
claude_8bit_alpha.png
Contents.json
Contents.json
FooterIconClaude.imageset/
claude-color.svg
Contents.json
FooterIconCodex.imageset/
Contents.json
openai.svg
HeatmapCellEmpty.colorset/
Contents.json
MenuIconClaude.imageset/
Contents.json
MenuIconClaude-18.png
MenuIconClaude-36.png
MenuIconCodex.imageset/
Contents.json
MenuIconCodex-18.png
MenuIconCodex-36.png
OnboardingCockpitScreenshot.imageset/
Contents.json
onboarding-cockpit.png
onboarding-cockpit@2x.png
OnboardingCockpitScreenshotDark.imageset/
Contents.json
onboarding-cockpit-dark.png
onboarding-cockpit-dark@2x.png
OnboardingQuotaMeterPredictionMarkers.imageset/
Contents.json
onboarding-quota-meter-prediction-markers.png
OnboardingQuotaMeterRunway.imageset/
Contents.json
onboarding-quota-meter-session-runway.png
OnboardingQuotaMeterRunwayAnimated.dataset/
Contents.json
v40-quota-meter-runway-both-agents-trimmed.gif
ClaudeCloud/
ClaudeCloudAPIClient.swift
ClaudeCloudError.swift
ClaudeCloudHUDRowMapper.swift
ClaudeCloudLiveModel.swift
ClaudeCloudSessionCatalog.swift
ClaudeCloudSourceState.swift
ClaudeResume/
ClaudeCLIEnvironment.swift
ClaudeFeatureFlag.swift
ClaudeITermLauncher.swift
ClaudeResumeCommandBuilder.swift
ClaudeResumeCoordinator.swift
ClaudeResumeSettings.swift
ClaudeResumeTypes.swift
ClaudeSessionIDHelper.swift
ClaudeTerminalLauncher.swift
ClaudeStatus/
ClaudeAuthClassifier.swift
ClaudeDesktopSessionTitles.swift
ClaudeOAuth/
ClaudeCredentialFingerprint.swift
ClaudeDelegatedTokenRefresh.swift
ClaudeLimitSnapshot.swift
ClaudeManualWebCookie.swift
ClaudeOAuthTokenResolver.swift
ClaudeOAuthUsageClient.swift
ClaudeTmuxUsageFallbackAdapter.swift
ClaudeUsageNormalizer.swift
ClaudeUsageSnapshotStore.swift
ClaudeUsageSourceManager.swift
ClaudeWebCookieResolver.swift
ClaudeWebUsageClient.swift
ClaudeWebUsageNormalizer.swift
ClaudeProbeConfig.swift
ClaudeProbeProject.swift
ClaudeRunwayLogIO.swift
ClaudeRunwayRecentSessionScanner.swift
ClaudeRunwaySnapshotLoader.swift
ClaudeRunwayTokenActivityParser.swift
ClaudeStatusService.swift
ClaudeUsageModel.swift
CodexStatus/
CapPressureStore.swift
CodexAuthClassifier.swift
CodexCLIRPCProbe.swift
CodexOAuth/
CodexOAuthCredentials.swift
CodexOAuthUsageFetcher.swift
CodexResetCreditsFetcher.swift
CodexProbeCleanup.swift
CodexProbeConfig.swift
CodexRateLimitWindowClassifier.swift
CodexRunwayModel.swift
CodexStatusService.swift
MenuBarPrefs.swift
RunwayPriceTable.swift
UsageDisplayFormatter.swift
UsageDisplayMode.swift
UsageFreshness.swift
UsageStaleCheck.swift
Copilot/
CopilotCLIEnvironment.swift
CopilotSettings.swift
CopilotResume/
CopilotResumeCommandBuilder.swift
CopilotResumeCoordinator.swift
CopilotResumeTypes.swift
CopilotTerminalLauncher.swift
Cursor/
CursorBackendDetector.swift
CursorChatMetaReader.swift
CursorCLIEnvironment.swift
CursorSettings.swift
CursorResume/
CursorResumeCommandBuilder.swift
CursorResumeCoordinator.swift
CursorResumeTypes.swift
CursorTerminalLauncher.swift
Droid/
DroidCLIEnvironment.swift
DroidSettings.swift
Hermes/
HermesCLIEnvironment.swift
HermesSettings.swift
HermesResume/
HermesResumeCommandBuilder.swift
HermesResumeCoordinator.swift
HermesResumeTypes.swift
HermesTerminalLauncher.swift
Indexing/
AnalyticsIndexer.swift
DB.swift
SessionMetaRepository.swift
Info.plist
Kimi/
KimiCLIEnvironment.swift
KimiSettings.swift
KimiResume/
KimiResumeCommandBuilder.swift
KimiResumeCoordinator.swift
KimiResumeTypes.swift
KimiTerminalLauncher.swift
MenuBar/
SettingsUpdateProxy.swift
StatusItemController.swift
UsageMenuBar.swift
Model/
Session.swift
SessionEvent.swift
SessionSource.swift
Onboarding/
Components/
AnimatedGIFView.swift
OnboardingComponents.swift
OnboardingPalette.swift
Models/
FeedbackSubmitter.swift
OnboardingContent.swift
OnboardingCoordinator.swift
WhatsNewCatalog.swift
Utilities/
OnboardingDefaults.swift
Views/
FeedbackPromptView.swift
FirstRunSetupView.swift
OnboardingListTopSlot.swift
OnboardingSheetView.swift
QuotaMeterPromoView.swift
WhatsNewPanelView.swift
OpenCode/
OpenCodeBackendDetector.swift
OpenCodeCLIEnvironment.swift
OpenCodeSettings.swift
OpenCodeSqliteReader.swift
OpenCodeResume/
OpenCodeResumeCommandBuilder.swift
OpenCodeResumeCoordinator.swift
OpenCodeResumeTypes.swift
OpenCodeTerminalLauncher.swift
Pi/
PiCLIEnvironment.swift
PiSettings.swift
PiResume/
PiResumeCommandBuilder.swift
PiResumeCoordinator.swift
PiResumeTypes.swift
PiTerminalLauncher.swift
Resources/
claude_usage_capture.sh
codex_ping_test.sh
codex_probe_marker_test.sh
codex_status_after_marker_test.sh
codex_status_capture.sh
codex_status_min_test.sh
codex_status_quick_test.sh
codex_status_tui_test.sh
Resume/
AgentTerminalLauncher.swift
CodexCLIEnvironment.swift
CodexLaunchMode.swift
CodexResumeCommandBuilder.swift
CodexResumeCoordinator.swift
CodexResumeLauncher.swift
CodexResumeSettings.swift
CodexResumeSheet.swift
CodexVersion.swift
CommandExecutor.swift
ResumeHealthCheck.swift
ResumePreferenceHelpers.swift
ShellQuoting.swift
Search/
SearchCoordinator.swift
SearchIngestService.swift
SearchSessionStore.swift
SessionSearchTextBuilder.swift
UnifiedSearchState.swift
Services/
ActivationPolicyDecider.swift
AgentEnablement.swift
AgentUpdateService.swift
AnalyticsIndexPhase.swift
AnalyticsSourceSupport.swift
AntigravityCLIEnvironment.swift
AntigravityCLISettings.swift
AntigravityHashResolver.swift
AntigravitySessionDiscovery.swift
AntigravitySessionIndexer.swift
AntigravitySessionParser.swift
AntigravityTranscriptParser.swift
AppAppearance.swift
ClaudeArchiveRestore.swift
ClaudeSessionIndexer.swift
ClaudeSessionParser.swift
CodeFenceParser.swift
CodexActiveSessionsModel.swift
CodexSideChatLogReader.swift
CopilotSessionIndexer.swift
CopilotSessionParser.swift
CursorSessionDiscovery.swift
CursorSessionIndexer.swift
CursorSessionParser.swift
DroidSessionDiscovery.swift
DroidSessionIndexer.swift
DroidSessionParser.swift
FilterEngine.swift
HermesSessionDiscovery.swift
HermesSessionIndexer.swift
HermesSessionParser.swift
IDEOpener.swift
InternalPayloadFormatter.swift
KimiSessionDiscovery.swift
KimiSessionIndexer.swift
KimiSessionParser.swift
LayoutMode.swift
MarkdownBodyRenderer.swift
ModelNameAbbreviator.swift
OpenClawSessionDiscovery.swift
OpenClawSessionIndexer.swift
OpenClawSessionParser.swift
OpenCodeSessionDiscovery.swift
OpenCodeSessionIndexer.swift
OpenCodeSessionParser.swift
PiSessionDiscovery.swift
PiSessionIndexer.swift
PiSessionParser.swift
PlanParser.swift
PresenceEngine.swift
PresenceSnapshot.swift
RenderedBody.swift
SessionArchiveManager.swift
SessionDiscovery.swift
SessionIndexer.swift
SessionIndexingEngine.swift
SessionRowsBuilder.swift
SessionTranscriptBuilder.swift
SessionViewMode.swift
StarredSessionsStore.swift
SubagentHierarchyBuilder.swift
TerminalKind.swift
TerminalLineID.swift
TerminalModels.swift
ToolTextBlockNormalizer.swift
TranscriptCache.swift
TranscriptColorSystem.swift
TranscriptDerivedState.swift
TranscriptFindNavigator.swift
TranscriptRenderMode.swift
TranscriptTheme.swift
TranscriptToolSummary.swift
TranscriptTurnTiming.swift
TranscriptUserAnchors.swift
TranscriptWindow.swift
UnifiedDiffParser.swift
UnifiedSessionIndexer.swift
WindowFocusCoordinator.swift
Shared/
AuthStatusNotifier.swift
CLIAuthStatusProbe.swift
CLIBinaryPresence.swift
ProbeCoordinator.swift
UsageAuthStatus.swift
Views/
AuthRemediationBanner.swift
Support/
AppEdition.swift
AppRuntime.swift
ColumnVisibilityStore.swift
CrashReporting/
CrashEmailDraftBuilder.swift
CrashReportDetector.swift
CrashReportEnvelope.swift
CrashReportingService.swift
CrashReportStore.swift
DeprecatedCockpitDefaultsCleanup.swift
FeatureFlags.swift
... 893 moreFAQ
agent-sessions is a Claude Code plugin with 6 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes deploy, release-notes, add-agent-support. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is agent-sessions?
- Live per-session quota burn for Codex and Claude — see which session is eating your 5-hour and weekly limits, priced per model.
- How do I install agent-sessions?
- Run these in Claude Code: npx -y skills add jazzyalex/agent-sessions --agent claude-code. Then prompt normally.
- Does agent-sessions auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is agent-sessions free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.