AgentsView Architecture: A Local-First Multi-Backend Pipeline for AI Session Management

AgentsView is a local-first, multi-backend web viewer for AI coding agent sessions that uses a data-flow pipeline from CLI through file-watching and parsing to a SQLite archive, served via an embedded HTTP server with a Svelte 5 frontend and optional PostgreSQL replication.

AgentsView is an open-source tool developed by kenn-io that provides a unified interface for viewing AI coding agent sessions across multiple platforms. The AgentsView architecture follows a local-first design philosophy, ensuring your data remains on your machine while offering optional cloud synchronization capabilities. This architecture leverages Go for the backend pipeline and Svelte 5 for the frontend, creating a standalone binary that embeds both the server and the web interface.

Core Architecture Overview

The AgentsView architecture follows a linear data-flow pipeline that transforms raw agent session files into a searchable, web-accessible archive. The system operates as a daemon that watches configured directories, parses updates, and serves them through a REST API with Server-Sent Events (SSE) for live updates.

CLI (agentsview) → Config → DB (SQLite + FTS5)
                     |           |
                     v           v
               File Watcher → Sync Engine → Parsers (one per agent)
                     |           |
                     v           v
                HTTP Server → REST API + SSE + Embedded SPA
                                 |
                                 v
                          PG Push Sync → PostgreSQL (optional)

Key Architectural Components

CLI Entry Point and Configuration

The architecture begins at cmd/agentsview/main.go, which serves as the entry point for all operations. This module handles flag parsing and sub-command routing for serve, pg, and duckdb operations. Configuration management resides in internal/config/config.go, which loads environment variables and TOML configuration files to resolve per-agent directories such as ~/.claude/projects/.

File Watching and Synchronization

The synchronization layer consists of two primary components. The File Watcher (internal/sync/watcher.go) monitors configured agent directories for changes using filesystem events. The Sync Engine (internal/sync/engine.go) orchestrates these observations, triggering incremental updates immediately while running a full resync approximately every 15 minutes to catch missed changes.

Parsing Layer

Agent-specific parsers in internal/parser/*.go (with type definitions in internal/parser/types.go) handle the normalization of raw session data. Each parser targets a specific agent format (Claude, Codex, Forge) and converts JSONL or database files into standardized rows for the archive.

Storage Layer (SQLite + FTS5)

The primary archive uses SQLite with WAL mode enabled for concurrent read/write operations. The database module (internal/db/db.go) manages tables for sessions, messages, and token usage, while FTS5 indexes provide full-text search capabilities for fast querying.

HTTP Server and REST API

The embedded HTTP server (internal/server/server.go) handles auto-port discovery (default 8080) and request routing. REST API endpoints defined in internal/server/sessions.go, search.go, and events.go expose session lists, full-text search, token analytics, and export functionality. Server-Sent Events (events.go) push live updates to connected clients when new messages arrive.

Frontend and Embedded SPA

The user interface is a Svelte 5 Single Page Application (SPA) bundled directly into the Go binary at build time. The internal/web/embed.go module handles static asset embedding, sourcing compiled files from the frontend/ directory. This eliminates external dependencies and allows AgentsView to run as a single portable binary.

Optional PostgreSQL Push Sync

For team environments, the optional PostgreSQL Push Sync layer (internal/postgres/*) replicates the SQLite archive into a shared PostgreSQL schema. The agentsview pg push command fingerprints the local database and upserts rows into PostgreSQL, enabling a read-only "PG serve" mode for multi-machine dashboards.

Data Flow Pipeline

The AgentsView architecture processes data through six distinct stages:

1. Discovery: On startup, the daemon walks all configured agent directories (local or S3 roots) and builds the initial SQLite archive.
2. Watch & Sync: The file watcher notifies the sync engine of changes, while periodic full-syncs (≈15 minutes) ensure consistency.
3. Parsing: The engine routes files to appropriate parsers, which extract messages, timestamps, and token usage into normalized database rows.
4. Indexing: FTS5 indexes update automatically to support full-text search across session content.
5. Serving: The embedded HTTP server exposes /api/v1/... endpoints and streams SSE events to the Svelte UI.
6. Optional PG Push: The push-sync layer replicates data to PostgreSQL for team-wide access.

Implementation Examples

Starting the Daemon

To launch the AgentsView daemon in the foreground:

agentsview serve

This binds to 127.0.0.1:8080, initializes the file watcher, and starts the HTTP server. Implementation in cmd/agentsview/main.go parses the serve sub-command and invokes server.Start().

Programmatic Sync Invocation

For custom tooling, invoke the sync engine directly:

import (
    "github.com/kenn-io/agentsview/internal/sync"
    "github.com/kenn-io/agentsview/internal/config"
)

func main() {
    cfg, _ := config.Load()                     // reads env/TOML
    engine := sync.NewEngine(cfg)              // creates the orchestrator
    engine.SyncAll(context.Background())        // full sync of all agents
}

The sync.NewEngine constructor in internal/sync/engine.go wires together the file watcher, parsers, and database connection.

Querying the REST API

Access session data via the REST API:

curl http://localhost:8080/api/v1/sessions?limit=5

The handler in internal/server/sessions.go queries db.ListSessions to retrieve results from SQLite.

Pushing to PostgreSQL

Enable team synchronization by pushing to PostgreSQL:

agentsview pg push --all

This command in cmd/agentsview/pg.go invokes postgres.PushAll(cfg) from internal/postgres/push.go to replicate the archive.

Key Source Files

Path	Purpose
cmd/agentsview/main.go	CLI entry point and sub-command routing
internal/config/config.go	Configuration loading and environment resolution
internal/sync/engine.go	Core sync orchestration logic
internal/parser/types.go	Registry of supported agent parsers
internal/db/db.go	SQLite archive management and FTS5 setup
internal/server/server.go	HTTP server initialization and middleware
internal/web/embed.go	Svelte SPA embedding into the binary
internal/postgres/push.go	PostgreSQL replication logic

Summary

• AgentsView follows a local-first architecture where data remains in SQLite on your machine.
• The data pipeline moves from CLI → Config → File Watcher → Sync Engine → Parsers → SQLite → HTTP Server → Svelte SPA.
• FTS5 indexing provides fast full-text search across all agent sessions.
• Server-Sent Events enable real-time UI updates without polling.
• Optional PostgreSQL push-sync allows team-wide read-only access while maintaining local ownership of data.
• The entire application compiles to a single binary with the frontend embedded, requiring no external dependencies.

Frequently Asked Questions

What database does AgentsView use for local storage?

AgentsView uses SQLite with WAL (Write-Ahead Logging) mode as its primary archive. The database schema includes tables for sessions, messages, and token usage, with FTS5 full-text search indexes for fast querying. This is implemented in internal/db/db.go.

How does AgentsView handle real-time updates in the web interface?

The architecture uses Server-Sent Events (SSE) via the endpoint defined in internal/server/events.go. When the file watcher detects new session data and the sync engine processes it, the server pushes updates to connected Svelte 5 clients immediately, eliminating the need for browser polling.

Can I use AgentsView with multiple AI coding agents simultaneously?

Yes. The parser registry in internal/parser/types.go supports multiple agent formats including Claude, Codex, and Forge. Each agent gets its own parser implementation in internal/parser/*.go, allowing the sync engine to normalize different session formats into a unified SQLite schema.

Is PostgreSQL required to run AgentsView?

No. PostgreSQL is entirely optional. The application runs completely on SQLite by default. The PostgreSQL integration (internal/postgres/*) only activates when you explicitly run agentsview pg push or agentsview pg serve, enabling team synchronization while keeping the local-first architecture intact.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}