# jazzyalex/agent-sessions architecture

> Architecture diagram of the GitHub repository jazzyalex/agent-sessions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jazzyalex/agent-sessions
- Repository: https://github.com/jazzyalex/agent-sessions

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        direction TB
        SessionsView["SessionsView"]:::ui
        TranscriptView["TranscriptView"]:::ui
        AnalyticsView["AnalyticsView"]:::ui
        SessionsChartView["SessionsChartView"]:::ui
        GitInspectorView["GitInspectorView"]:::ui
        PreferencesView["PreferencesView"]:::ui
        MenuBarController["StatusItemController"]:::ui
        UsageMenuBarView["UsageMenuBarView"]:::ui
    end

    subgraph "Coordinators" 
        direction TB
        AppRuntime["AppRuntime"]:::coord
        WindowFocusCoordinator["WindowFocusCoordinator"]:::coord
        SearchCoordinator["SearchCoordinator"]:::coord
        CodexResumeCoordinator["CodexResumeCoordinator"]:::coord
        ClaudeResumeCoordinator["ClaudeResumeCoordinator"]:::coord
    end

    subgraph "Services & Domain Logic"
        direction TB
        SessionDiscovery["SessionDiscovery"]:::svc
        UnifiedSessionIndexer["UnifiedSessionIndexer"]:::svc
        SessionTranscriptBuilder["SessionTranscriptBuilder"]:::svc
        CodexParser["CodexSessionParser"]:::svc
        ClaudeParser["ClaudeSessionParser"]:::svc
        GeminiParser["GeminiSessionParser"]:::svc
        OpenCodeParser["OpenCodeSessionParser"]:::svc
        AnalyticsService["AnalyticsService"]:::svc
        AnalyticsRepository["AnalyticsRepository"]:::svc
        GitContextExtractor["GitContextExtractor"]:::svc
        GitCommandRunner["GitCommandRunner"]:::svc
        CodexResumeCommandBuilder["CodexResumeCommandBuilder"]:::svc
        CodexResumeLauncher["CodexResumeLauncher"]:::svc
        ClaudeResumeCommandBuilder["ClaudeResumeCommandBuilder"]:::svc
        ClaudeTerminalLauncher["ClaudeTerminalLauncher"]:::svc
        UpdateChecker["UpdateChecker"]:::svc
        UpdaterController["UpdaterController"]:::svc
        GitHubClient["GitHubClient"]:::svc
        ColumnVisibilityStore["ColumnVisibilityStore"]:::svc
        FeatureFlags["FeatureFlags"]:::svc
        JSONLReader["JSONLReader"]:::svc
    end

    subgraph "Data Storage"
        direction TB
        SQLiteDB["DB.swift (SQLiteDB)"]:::storage
        SessionMetaRepository["SessionMetaRepository"]:::storage
        PreferencesStore["PreferencesStore"]:::storage
    end

    subgraph "External Systems"
        direction TB
        LocalFileSystem["LocalFileSystem"]:::ext
        Terminal["Terminal/iTerm"]:::ext
        GitCLI["Git CLI"]:::ext
        GitHubServer["GitHub/Sparkle Server"]:::ext
    end

    %% UI to Coordinators
    SessionsView -->|uses| SearchCoordinator
    TranscriptView -->|uses| SearchCoordinator
    AnalyticsView -->|requests| AnalyticsService
    SessionsChartView -->|requests| AnalyticsService
    GitInspectorView -->|triggers| GitContextExtractor
    PreferencesView -->|reads/writes| PreferencesStore
    MenuBarController -->|controls| UsageMenuBarView
    UsageMenuBarView -->|opens| AppRuntime

    %% Coordinators to Services
    AppRuntime -->|initializes| SessionDiscovery
    AppRuntime -->|initializes| UnifiedSessionIndexer
    AppRuntime -->|initializes| WindowFocusCoordinator
    SearchCoordinator -->|queries| UnifiedSessionIndexer
    SearchCoordinator -->|parses| SessionTranscriptBuilder
    CodexResumeCoordinator -->|builds| CodexResumeCommandBuilder
    CodexResumeCoordinator -->|launches| CodexResumeLauncher
    ClaudeResumeCoordinator -->|builds| ClaudeResumeCommandBuilder
    ClaudeResumeCoordinator -->|launches| ClaudeTerminalLauncher

    %% Services to Storage
    SessionDiscovery -->|reads| LocalFileSystem
    SessionDiscovery -->|writes| SQLiteDB
    UnifiedSessionIndexer -->|writes| SessionMetaRepository
    SessionDiscovery -->|uses| JSONLReader
    SessionTranscriptBuilder -->|parses| JSONLReader
    AnalyticsService -->|queries| SQLiteDB
    GitContextExtractor -->|executes| GitCommandRunner
    UpdateChecker -->|polls| GitHubServer

    %% Services to External
    GitCommandRunner -->|runs| GitCLI
    CodexResumeLauncher -->|launches| Terminal
    ClaudeTerminalLauncher -->|launches| Terminal
    UpdaterController -->|invokes| UpdateChecker

    %% Storage to UI (reactive)
    SQLiteDB -->|publishes| SessionsView
    SessionMetaRepository -->|publishes| SearchCoordinator

    %% Update flow
    UpdateChecker -->|notifies| UpdaterController

    %% Click Events
    click SessionsView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Views/SessionsListView.swift"
    click TranscriptView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Views/TranscriptPlainView.swift"
    click AnalyticsView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Analytics/Views/AnalyticsView.swift"
    click SessionsChartView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Analytics/Views/SessionsChartView.swift"
    click GitInspectorView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/GitInspector/Views/GitInspectorView.swift"
    click PreferencesView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Views/Preferences/PreferencesView.swift"
    click MenuBarController "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/MenuBar/StatusItemController.swift"
    click UsageMenuBarView "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/MenuBar/UsageMenuBar.swift"
    click AppRuntime "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Support/AppRuntime.swift"
    click WindowFocusCoordinator "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/WindowFocusCoordinator.swift"
    click SearchCoordinator "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Search/SearchCoordinator.swift"
    click CodexResumeCoordinator "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Resume/CodexResumeCoordinator.swift"
    click ClaudeResumeCoordinator "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/ClaudeResume/ClaudeResumeCoordinator.swift"
    click SessionDiscovery "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/SessionDiscovery.swift"
    click UnifiedSessionIndexer "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/UnifiedSessionIndexer.swift"
    click SQLiteDB "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Indexing/DB.swift"
    click SessionMetaRepository "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Indexing/SessionMetaRepository.swift"
    click SessionTranscriptBuilder "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/SessionTranscriptBuilder.swift"
    click CodexParser "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/CodexSessionParser.swift"
    click ClaudeParser "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/ClaudeSessionParser.swift"
    click GeminiParser "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/GeminiSessionParser.swift"
    click OpenCodeParser "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Services/OpenCodeSessionParser.swift"
    click AnalyticsService "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Analytics/Services/AnalyticsService.swift"
    click AnalyticsRepository "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Analytics/Repositories/AnalyticsRepository.swift"
    click GitContextExtractor "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/GitInspector/Services/GitContextExtractor.swift"
    click GitCommandRunner "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/GitInspector/Utilities/GitCommandRunner.swift"
    click CodexResumeCommandBuilder "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Resume/CodexResumeCommandBuilder.swift"
    click CodexResumeLauncher "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Resume/CodexResumeLauncher.swift"
    click ClaudeResumeCommandBuilder "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/ClaudeResume/ClaudeResumeCommandBuilder.swift"
    click ClaudeTerminalLauncher "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/ClaudeResume/ClaudeTerminalLauncher.swift"
    click UpdateChecker "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Update/UpdateChecker.swift"
    click UpdaterController "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Update/UpdaterController.swift"
    click GitHubClient "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Update/GitHubClient.swift"
    click ColumnVisibilityStore "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Support/ColumnVisibilityStore.swift"
    click FeatureFlags "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Support/FeatureFlags.swift"
    click JSONLReader "https://github.com/jazzyalex/agent-sessions/blob/main/AgentSessions/Utilities/JSONLReader.swift"

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef coord fill:#90EE90,stroke:#333,stroke-width:1px
    classDef svc fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFD580,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
```
