# How to Set Up AgentsView for Development: Complete Guide

> Learn how to set up AgentsView for development by cloning the repository, installing dependencies, and running build commands. Get your local development environment running quickly.

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

---

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go) and [`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go); frontend source is in `frontend/`; database logic uses [`internal/db/db.go`](https://github.com/kenn-io/agentsview/blob/main/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.