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

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:

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.

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:

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:

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:

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
internal/config/	Configuration loading and JSON migration	config.go
internal/db/	SQLite schema, migrations, and FTS5 search	db.go
internal/parser/	Per-agent session file parsers	types.go
internal/sync/	Sync engine, discovery, and periodic rescans	engine.go
internal/server/	HTTP router, REST endpoints, and SSE streams	server.go
frontend/	Svelte 5 SPA and Vite configuration	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.
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).
2. Register the route in 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 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:

make test

Execute PostgreSQL integration tests (requires Docker):

make test-postgres

Run end-to-end Playwright tests:

make e2e

The CI pipeline defined in .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.
• 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.

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

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