# How to Get Started with Developing kenn-io/agentsview: Complete Setup Guide

> Learn to develop with kenn-io/agentsview. Follow this guide to clone the repo, install dependencies, and run the dev servers for seamless backend and frontend development.

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

---

**Clone the repository, install Go 1.26+ with CGO and Node.js 22+, then run `make dev` and `make frontend-dev` to launch the backend and Svelte frontend development servers.**

`agentsview` is a local web viewer that indexes AI-coding-agent session data into a SQLite (FTS5) archive and serves a Svelte 5 SPA via an embedded Go HTTP server. Developing this open-source project requires setting up a dual-stack environment where Go handles the backend API and file watching, while Node.js powers the modern frontend build pipeline.

## Prerequisites

Before contributing to `kenn-io/agentsview`, ensure your development machine meets the following requirements:

- **Go 1.26 or later** with CGO enabled (required for the SQLite driver and FTS5 support)
- **Node.js 22+** (for the Vite and Svelte frontend build chain)
- **Make** (for convenience wrappers and build automation)
- **Docker** (optional, required only for PostgreSQL integration tests and benchmarks)

## Repository Setup

Start by cloning the repository and installing dependencies for both the backend and frontend:

```bash
git clone https://github.com/kenn-io/agentsview.git
cd agentsview
npm ci

```

The `npm ci` command installs the Svelte UI dependencies and the git-based UI kit referenced in [`frontend/package.json`](https://github.com/kenn-io/agentsview/blob/main/frontend/package.json).

## Development Workflow

The project uses a concurrent development model where the Go server and Vite dev server run simultaneously.

### Start the Backend

Run the following command to start the Go server with live reload disabled:

```bash
make dev

```

This command invokes the build system defined in the repository's Makefile and starts the file watcher and sync engine.

### Serve the Frontend

In a separate terminal, start the Vite development server:

```bash
make frontend-dev

```

The frontend runs on `http://localhost:5173`, while the Go server proxies API calls to this endpoint. This configuration allows you to edit Svelte components under `frontend/src/` and see changes instantly without restarting the backend.

### Build Production Binary

To embed the compiled SPA into a standalone binary:

```bash
make build
./agentsview serve

```

The production server starts on `127.0.0.1:8080` and serves the embedded assets directly from the compiled binary.

## Project Architecture

Understanding the directory structure is essential for effective development. The codebase follows standard Go project layout with a clear separation between backend logic and frontend assets.

| Directory | Purpose | Key Files |
|-----------|---------|-----------|
| `cmd/agentsview/` | CLI entry point and server startup | [`main.go`](https://github.com/kenn-io/agentsview/blob/main/main.go) |
| `internal/config/` | Configuration loading and JSON migration | [`config.go`](https://github.com/kenn-io/agentsview/blob/main/config.go) |
| `internal/db/` | SQLite schema, migrations, and FTS5 search | [`db.go`](https://github.com/kenn-io/agentsview/blob/main/db.go) |
| `internal/parser/` | Per-agent session file parsers | [`types.go`](https://github.com/kenn-io/agentsview/blob/main/types.go) |
| `internal/sync/` | Sync engine, discovery, and periodic rescans | [`engine.go`](https://github.com/kenn-io/agentsview/blob/main/engine.go) |
| `internal/server/` | HTTP router, REST endpoints, and SSE streams | [`server.go`](https://github.com/kenn-io/agentsview/blob/main/server.go) |
| `frontend/` | Svelte 5 SPA and Vite configuration | [`package.json`](https://github.com/kenn-io/agentsview/blob/main/package.json) |

## Core Development Tasks

### Adding a New Agent Parser

To support a new AI coding agent format:

1. Append an `AgentDef` entry to [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go).
2. Implement a `ParseXXX` function in a dedicated file under `internal/parser/`.
3. Register the parser in the registry if applicable.
4. Add unit tests using the `testDB(t)` helper under `internal/parser/`.

### Extending the REST API

To add new HTTP endpoints:

1. Create a handler file in `internal/server/` (e.g., [`foo.go`](https://github.com/kenn-io/agentsview/blob/main/foo.go)).
2. Register the route in [`server.go`](https://github.com/kenn-io/agentsview/blob/main/server.go) using `mux.HandleFunc`.
3. Write integration tests that spin up an in-memory database.

### UI Enhancements

When modifying the Svelte frontend:

1. Create or edit components under `frontend/src/`.
2. Update TypeScript definitions in [`frontend/src/types.ts`](https://github.com/kenn-io/agentsview/blob/main/frontend/src/types.ts) if adding new data structures.
3. Run `npm run check` and `npm run i18n:compile` after modifying message catalogs.

## Testing and CI

The repository includes comprehensive testing for both backend and frontend components.

Run Go unit tests with FTS5 support enabled:

```bash
make test

```

Execute PostgreSQL integration tests (requires Docker):

```bash
make test-postgres

```

Run end-to-end Playwright tests:

```bash
make e2e

```

The CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/kenn-io/agentsview/blob/main/.github/workflows/ci.yml) automatically executes all test suites on every pull request.

## Summary

- **Setup**: Install Go 1.26+ (CGO), Node.js 22+, and run `npm ci` after cloning.
- **Development**: Use `make dev` for the backend and `make frontend-dev` for the Svelte SPA.
- **Architecture**: Backend logic resides in `internal/`, frontend in `frontend/`, with entry point at [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go).
- **Testing**: Use `make test` for Go, `make test-postgres` for PostgreSQL integration, and `make e2e` for Playwright frontend tests.
- **Building**: Run `make build` to embed the SPA into a production-ready binary.

## Frequently Asked Questions

### What Go version is required to build agentsview?

You need **Go 1.26 or later** with CGO enabled. The CGO dependency is mandatory because the SQLite driver requires it for FTS5 full-text search functionality, as implemented in [`internal/db/db.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db.go).

### How do I refresh the sync engine without restarting the server?

Use the CLI command `agentsview sync now` to trigger an immediate rescan of session files. This invokes the sync engine logic in [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go) without requiring a daemon restart.

### Can I use PostgreSQL instead of SQLite for development?

Yes, while SQLite is the default, you can configure PostgreSQL as a push sync target. Run `agentsview pg push` to migrate your local SQLite archive to a configured PostgreSQL instance, which is useful for integration testing via `make test-postgres`.

### Where are the REST API endpoints defined?

HTTP routes are registered in [`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go) using the router's `HandleFunc` method. Individual handlers reside in separate files within `internal/server/`, and the server provides both REST endpoints and SSE event streams for real-time UI updates.