Core Dependencies for kenn-io/agentsview: Complete Module Guide

The kenn-io/agentsview project relies on Cobra for CLI commands, Huma v2 for HTTP API generation, fsnotify for file watching, go-sqlite3 for embedded SQLite storage, and pgx for PostgreSQL synchronization, alongside specialized libraries for configuration, compression, and real‑time updates.

The kenn-io/agentsview repository is a Go‑based local web viewer that ingests AI agent sessions and serves them through a Svelte frontend. Understanding the core dependencies declared in go.mod is essential for developers extending the sync engine or troubleshooting integration issues. This guide breaks down each third‑party module and its specific architectural role.

CLI and Command Handling with Cobra

The command‑line interface is built on github.com/spf13/cobra at version v1.10.2, paired with github.com/spf13/pflag v1.0.10 for POSIX‑compliant flag parsing. Together, these provide the agentsview command hierarchy—including agentsview serve, agentsview pg push, and subcommand structures—defined in cmd/agentsview/main.go.

// cmd/agentsview/main.go
rootCmd := &cobra.Command{
    Use:   "agentsview",
    Short: "Local web viewer for AI agent sessions",
    RunE:  serveCmd,
}
rootCmd.AddCommand(&cobra.Command{
    Use:   "pg",
    Short: "PostgreSQL sync commands",
    RunE:  pgCmd,
})
cobra.CheckErr(rootCmd.Execute())

HTTP API and OpenAPI Generation with Huma

REST endpoint definitions and automatic OpenAPI documentation are handled by github.com/danielgtaylor/huma/v2 v2.38.0. This library generates type‑safe HTTP routers and request validation logic in internal/server/server.go, eliminating the need for manual Swagger specification maintenance.

// internal/server/server.go
router := huma.New("AgentsView API", "1.0.0")
router.OpenAPI(func(gen *huma.OpenAPI) {
    gen.Info.Title = "AgentsView"
    gen.Info.Version = "v0.0.1"
})
router.Handle("GET", "/sessions", listSessionsHandler)
http.ListenAndServe(":8080", router)

File System Watching with fsnotify

To detect changes in session directories, the sync engine uses github.com/fsnotify/fsnotify v1.10.1. This triggers ingestion workflows when agent files are created or modified on disk, as implemented in internal/sync/engine.go.

// internal/sync/engine.go
watcher, _ := fsnotify.NewWatcher()
defer watcher.Close()
watcher.Add(config.DataDir) // config.DataDir from TOML file

go func() {
    for {
        select {
        case ev := <-watcher.Events:
            if ev.Op&fsnotify.Write == fsnotify.Write {
                engine.SyncFile(ev.Name) // trigger parser + DB upsert
            }
        case err := <-watcher.Errors:
            log.Error(err)
        }
    }
}()

Database Layer: SQLite and PostgreSQL

Local data persistence relies on github.com/mattn/go-sqlite3 v1.14.47, which drives the embedded SQLite database with WAL mode and FTS5 full‑text indexing. For remote synchronization, github.com/jackc/pgx/v5 v5.10.0 enables the optional "pg push" command to mirror local data to PostgreSQL.

// internal/db/sessions.go
stmt, _ := db.Prepare(`INSERT INTO sessions (id, agent, created_at) VALUES (?, ?, ?)`)
_, err := stmt.Exec(sess.ID, sess.Agent, sess.CreatedAt)

// internal/postgres/push.go
pgConn, _ := pgx.Connect(context.Background(), os.Getenv("PG_URL"))
defer pgConn.Close(context.Background())

tx, _ := pgConn.Begin(context.Background())
_, err := tx.Exec(context.Background(),
    `INSERT INTO agentsview.sessions (id, agent, created_at) SELECT id, agent, created_at FROM sqlite.sessions`)
_ = tx.Commit(context.Background())

Configuration Parsing with TOML

User‑editable settings are loaded from config.toml using github.com/BurntSushi/toml v1.6.0, parsed in internal/config/config.go to define data directories and per‑agent settings.

Specialized Utilities and Analytics

The project integrates several utility libraries for specific functions:

• github.com/duckdb/duckdb-go/v2 v2.10504.0 provides an alternative query engine for analytics and complex searches when SQLite FTS5 is insufficient.
• github.com/gofrs/flock v0.13.0 implements file‑level locking for safe multi‑process access to the database.
• github.com/klauspost/compress v1.18.6 supplies compression utilities for data export and import operations.
• github.com/shirou/gopsutil/v4 v4.26.5 collects runtime statistics (CPU, memory) displayed on the UI dashboard.
• github.com/minio/minio-go/v7 v7.2.0 supports Server‑Sent Events (SSE) for pushing real‑time updates to the browser.
• github.com/modelcontextprotocol/go-sdk v1.6.1 supplies typed structures for supported AI agents (Claude, ChatGPT, Llama).
• github.com/tidwall/gjson v1.19.0 enables fast JSON extraction from agent session files.
• github.com/dmarkham/enumer v1.6.3 generates enum helpers for type safety.
• go.kenn.io/kit v0.1.7 provides internal shared helpers used across the codebase.

Testing and Development Dependencies

Quality assurance relies on github.com/stretchr/testify v1.11.1 for unit tests and github.com/testcontainers/testcontainers-go v0.43.0 (including the PostgreSQL module) for integration testing of database and sync layers.

Summary

• Cobra and pflag provide the CLI framework and flag parsing for agentsview commands.
• Huma v2 generates type‑safe HTTP routers and automatic OpenAPI documentation.
• fsnotify triggers the synchronization engine when session files change on disk.
• go-sqlite3 with FTS5 powers the embedded local database, while pgx enables optional PostgreSQL mirroring.
• BurntSushi/toml handles configuration parsing, and minio-go facilitates real‑time server‑sent events.
• testify and testcontainers-go support comprehensive testing of the database and sync layers.

Frequently Asked Questions

Does agentsview require PostgreSQL to run?

No. PostgreSQL is optional. The application runs entirely on SQLite via go-sqlite3 by default. The pgx dependency is only utilized when you explicitly run the agentsview pg push command to mirror local data to a remote PostgreSQL instance.

Why does agentsview use both SQLite and DuckDB?

SQLite with FTS5 handles the primary session storage and full‑text search for the local web viewer. DuckDB is included as a fallback analytics engine for complex queries and large‑scale data analysis that may exceed SQLite's performance characteristics for specific use cases.

How does the file watcher trigger database updates?

The fsnotify library monitors the configured data directory for write events. When a session file is modified, internal/sync/engine.go receives the event, parses the file using the agent SDK, and upserts the data into SQLite via go-sqlite3, ensuring the UI reflects changes immediately.

Which dependency handles the REST API documentation?

github.com/danielgtaylor/huma/v2 automatically generates OpenAPI 3.0 specifications from Go struct definitions and handler signatures. This eliminates manual YAML maintenance and provides interactive documentation at runtime.

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