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

> Discover the core dependencies for kenn-io/agentsview including Cobra, Huma v2, fsnotify, go-sqlite3, and pgx. Understand essential modules for CLI, API, file watching, and database operations.

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

---

**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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go).

```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`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go), eliminating the need for manual Swagger specification maintenance.

```go
// 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`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go).

```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.

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

```

```go
// 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`](https://github.com/kenn-io/agentsview/blob/main/config.toml) using **`github.com/BurntSushi/toml`** **v1.6.0**, parsed in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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.