How jazzyalex/agent-sessions works
Project Type and Purpose
• Agent Sessions is a local-first, full-stack macOS desktop application (built in Swift/SwiftUI) that unifies browsing, searching, analytics, and “resume” workflows for multiple AI coding agents (Codex CLI, Claude Code, Gemini CLI, OpenCode).
• It reads session transcripts from local file stores, indexes them in a SQLite DB, exposes a rich UI (windows + menu bar) for search, analytics, and resume, and offers Sparkle-driven auto-updates.
File-Structure Analysis
• Top level: Xcode project (AgentSessions.xcodeproj), source root (AgentSessions/), assets (Assets.xcassets), tests, scripts, tools, docs.
• Under AgentSessions/ are feature modules:
• Analytics (Models, Repositories, Services, Views)
• ClaudeResume, ClaudeStatus, CodexStatus, OpenCode, Resume — each bundles CLI-specific resume/status logic.
• GitInspector (Models, Services, Views)
• Indexing (session discovery, DB)
• MenuBar (NSStatusItem controller, proxies)
• Model (domain types: Session, SessionEvent, SessionSource)
• Search (search coordinator)
• Services (session parsing, discovery, indexing, transcript building, theme, window focus, feature flags)
• Update (Sparkle integration, GitHubClient)
• Utilities & Support (layout, JSONL reader, preferences, autosave, runtime)
• Views (SwiftUI/AppKit combos for sessions list, transcript, analytics, inspector, preferences)
• Config/build: .swiftlint.yml, Info.plist, Sparkle settings, CI workflow in .github/workflows/ci.yml.
Key Insights from README
• Local-only reads from ~/.codex/sessions, ~/.claude/sessions, ~/.gemini/tmp, ~/.local/share/opencode/...
• SQLite-backed indexing for performance.
• Sparkle 2 for automatic in-app updates.
• Multiple UI entry points: Main window (sessions & transcript), Analytics window, Git Context inspector, Menu-bar usage indicator, Preferences.
a. Main Components
• UI Layer
• SwiftUI/AppKit Windows & Views (SessionsView, TranscriptView, AnalyticsView, InspectorViews, PreferencesView)
• Menu Bar Controller (NSStatusItem → UsageMenuBarView)
• Application Coordinator
• AppRuntime (start-up)
• WindowFocusCoordinator, SearchCoordinator, ResumeCoordinator
• Services & Domain Logic
• Session Discovery & Indexing (Indexing module → writes to SQLite DB)
• Session Parsing (TranscriptBuilder, CLI Parsers per agent)
• Analytics Service (queries DB, computes metrics)
• GitInspector Service (runs git commands, collects context)
• Resume Services (launch Terminal/iTerm with reconstructed commands)
• Update Checker (Sparkle + GitHubClient)
• Data Storage
• SQLite DB (DB.swift)
• File System Readers (JSONLReader reads session files)
• Preferences Store (UserDefaults wrappers, FeatureFlags, ColumnVisibilityStore)
• External Systems
• Local File System (agent session directories)
• Terminal/iTerm (resume commands)
• Git (shell commands)
• GitHub/Sparkle Update Server
b. Relationships & Interactions
• At startup, AppRuntime invokes SessionDiscovery → Indexing → writes to SQLite.
• UI sends search/filter commands to SearchCoordinator → Services query DB → return model to Views.
• AnalyticsView requests data from AnalyticsService → runs SQL queries → returns metrics to Views.
• “Show Git Context” triggers GitInspectorService → runs git commands via GitCommandRunner → returns context model → InspectorView.
• Resume action invokes ResumeCoordinator → builds CLI command via <Agent>ResumeCommandBuilder → launches terminal via TerminalLauncher.
• UpdateChecker periodically polls GitHubClient → Sparkle displays update prompts.
c. Architectural Patterns & Principles
• Modular MVVM/MVC: Views bind to ViewModels/Coordinators, which call Services.
• Local-first: offline SQLite DB with background indexing.
• Single Responsibility per module (Analytics only cares about metrics, GitInspector only about git context, etc.)
• Dependency Injection via constructors for testable services.
• Asynchronous background processing (indexing, probes) at utility priority.
d. Technologies & Frameworks
• Swift, SwiftUI + AppKit (for menu bar and advanced window controllers)
• Combine/GCD for async flows
• SQLite (via raw C or lightweight wrapper)
• Sparkle 2 for updates
• Shell execution (Process) for CLI, git, capture scripts