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

> Explore the AgentsView architecture, a local first multi backend pipeline for AI session management. Discover its CLI to SQLite data flow and Svelte 5 frontend.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: architecture
- Published: 2026-07-01

---

**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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go)) monitors configured agent directories for changes using filesystem events. The **Sync Engine** ([`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go)) handles auto-port discovery (default 8080) and request routing. REST API endpoints defined in [`internal/server/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/sessions.go), [`search.go`](https://github.com/kenn-io/agentsview/blob/main/search.go), and [`events.go`](https://github.com/kenn-io/agentsview/blob/main/events.go) expose session lists, full-text search, token analytics, and export functionality. **Server-Sent Events** ([`events.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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:

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go) parses the `serve` sub-command and invokes `server.Start()`.

### Programmatic Sync Invocation

For custom tooling, invoke the sync engine directly:

```go
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`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go) wires together the file watcher, parsers, and database connection.

### Querying the REST API

Access session data via the REST API:

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

```

The handler in [`internal/server/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/sessions.go) queries `db.ListSessions` to retrieve results from SQLite.

### Pushing to PostgreSQL

Enable team synchronization by pushing to PostgreSQL:

```bash
agentsview pg push --all

```

This command in [`cmd/agentsview/pg.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg.go) invokes `postgres.PushAll(cfg)` from [`internal/postgres/push.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/push.go) to replicate the archive.

## Key Source Files

| Path | Purpose |
|------|---------|
| [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go) | CLI entry point and sub-command routing |
| [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) | Configuration loading and environment resolution |
| [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go) | Core sync orchestration logic |
| [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) | Registry of supported agent parsers |
| [`internal/db/db.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db.go) | SQLite archive management and FTS5 setup |
| [`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go) | HTTP server initialization and middleware |
| [`internal/web/embed.go`](https://github.com/kenn-io/agentsview/blob/main/internal/web/embed.go) | Svelte SPA embedding into the binary |
| [`internal/postgres/push.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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.