How to Set Up AgentsView for Development: Complete Guide

To set up AgentsView for development, clone the repository, install Go 1.26+ with CGO and Node 22+, run make build to embed the Svelte frontend, then start the backend with make dev and the frontend dev server with make frontend-dev in separate terminals.

AgentsView is a local web viewer that indexes AI-agent session data into a SQLite archive and serves an embedded Svelte 5 single-page application via a Go HTTP server. Setting up AgentsView for development requires configuring a dual-stack environment where the Go backend and the Vite-powered frontend run simultaneously during active development.

Prerequisites for AgentsView Development

Before compiling the project, verify your system meets the toolchain requirements.

System Requirements

AgentsView requires Go 1.26 or later with CGO enabled (for SQLite support) and Node 22+ with npm for the frontend build pipeline. The Makefile will detect missing tools and fail with instructions if prerequisites are absent.

Platform-Specific Dependencies

Install CGO dependencies for your operating system:

• Debian/Ubuntu: sudo apt install build-essential libsqlite3-dev
• macOS: brew install go node

Understanding the AgentsView Architecture

Understanding the data flow helps diagnose setup issues. According to the AGENTS.md architecture documentation, the system operates as follows:

CLI (cmd/agentsview/main.go) → Config → SQLite/FTS5 (internal/db/)
                   |
                   v
          File Watcher → Sync Engine (internal/sync/engine.go) → Parsers (internal/parser/)
                   |
                   v
          HTTP Server (internal/server/server.go) → REST API + SSE + Embedded SPA

The file watcher discovers session files, the sync engine hands them to per-agent parsers in internal/parser/*.go, and parsed data is written to a SQLite database with FTS5 full-text search. The HTTP server exposes REST endpoints, Server-Sent Events for live updates, and serves the compiled Svelte UI from internal/web/.

Step-by-Step Development Setup

Follow these steps to build from source after cloning https://github.com/kenn-io/agentsview.git.

1. Clone the Repository and Install Dependencies

git clone https://github.com/kenn-io/agentsview.git
cd agentsview

Ensure Go and Node are available in your path. The Makefile will validate versions when you run subsequent commands.

2. Build the Binary with Embedded Frontend

Compile the Go server and bundle the Svelte SPA into the binary:

make build

This command executes the build pipeline defined in the top-level Makefile, embedding the compiled frontend assets so the binary serves the UI without external dependencies.

3. Start the Backend Development Server

Start the Go server with hot-reloading enabled:

make dev

This opens http://127.0.0.1:8080 and auto-restarts the server when Go files change. The server automatically watches directories listed in ~/.agentsview/config.toml (or defaults under $HOME/.agentsview with session data for Claude, Copilot, etc.).

4. Start the Frontend Development Server

In a second terminal, start Vite in watch mode for instant UI updates:

make frontend-dev

This serves the Svelte 5 application at http://localhost:5173 and proxies API requests to the Go backend running on port 8080.

5. Verify the Installation

Test the REST API and UI endpoints:

curl http://127.0.0.1:8080/api/v1/sessions   # Returns [] (empty DB)

open http://localhost:5173                    # Opens AgentsView UI

Development Workflow Commands

The Makefile at the repository root defines shortcuts for common tasks:

Command	Purpose
make dev	Starts backend with hot-reloading
make frontend-dev	Starts Vite dev server for UI work
make build	Compiles production binary with embedded SPA
make test	Executes Go unit tests (SQLite+FTS5)
make e2e	Runs Playwright end-to-end tests (requires Docker)
make test-postgres	Starts Docker Compose stack for PG-backed tests
make lint	Runs static analysis
make vet	Runs Go vet for code correctness

Adding Custom Agent Parsers

To extend AgentsView for a custom AI-coding agent:

1. Create a new *.go file under internal/parser/ implementing the Parse interface.
2. Register the parser in internal/parser/types.go by adding an entry to the AgentDef registry struct.
3. Restart the server with make dev; the sync engine automatically discovers the new parser.

Summary

• Install prerequisites: Go 1.26+ with CGO, Node 22+, and platform-specific build tools.
• Build once: Run make build to embed the Svelte UI into the Go binary.
• Run dual-stack dev: Execute make dev for the backend and make frontend-dev for hot-reload UI development.
• Key paths: Backend logic lives in cmd/agentsview/main.go and internal/server/server.go; frontend source is in frontend/; database logic uses internal/db/db.go.

Frequently Asked Questions

What are the minimum system requirements to set up AgentsView for development?

You need Go 1.26 or later compiled with CGO support (requires a C compiler) and Node.js 22 or later with npm. Linux users need libsqlite3-dev installed, while macOS users can install dependencies via Homebrew.

How do I hot-reload code changes during development?

Run make dev in one terminal to auto-restart the Go server on source changes, and make frontend-dev in another terminal to trigger Vite's HMR (Hot Module Replacement) for the Svelte UI. Changes to Go files restart the backend; changes to Svelte files update the browser instantly without losing state.

Can I use PostgreSQL instead of SQLite for development?

Yes. While the default development mode uses SQLite with FTS5, you can test PostgreSQL integration using make test-postgres to spin up a Docker Compose stack. The agentsview pg push command mirrors the SQLite archive to PostgreSQL, and agentsview pg serve starts a read-only PG-backed UI.

How do I run the full test suite before submitting a pull request?

Execute make test to run Go unit tests against SQLite, followed by make e2e to execute Playwright browser tests. Run make lint and make vet to ensure code passes static analysis and formatting checks defined in the project's CI pipeline.

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