Quick Start

Install

Desktop App

Download the latest .dmg (macOS), .exe (Windows), or .AppImage (Linux) from GitHub Releases. The desktop app is fully bundled — no CLI or dependencies needed — and includes built-in auto-update support.

Note

The desktop app and CLI share the same data directory (~/.agentsview/), so you can use one or both. They are fully complementary, not mutually exclusive.

pip / uvx

pip install agentsview    # install permanently
uvx agentsview            # or run without installing

Platform-specific wheels are published to PyPI for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x86_64).

Shell Script

curl -fsSL https://agentsview.io/install.sh | bash

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://agentsview.io/install.ps1 | iex"

The installer detects your OS and architecture, downloads the latest release from GitHub Releases, verifies the SHA-256 checksum, and installs the binary.

Build from source

Requires Go 1.26+ with CGO and Node.js 22+:

git clone https://github.com/wesm/agentsview.git
cd agentsview
make build
make install  # installs to ~/.local/bin

Note

CGO is required for the SQLite driver. The fts5 build tag enables full-text search.

Docker

Multi-arch images for linux/amd64 and linux/arm64 are published to GitHub Container Registry on every tagged release and on pushes to main:

docker run --rm -p 127.0.0.1:8080:8080 \
  -v agentsview-data:/data \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  ghcr.io/wesm/agentsview:latest

The container’s entrypoint runs agentsview serve by default. Set PG_SERVE=1 to switch to agentsview pg serve instead — the same image powers both modes.

A containerized AgentsView only sees agent sessions from directories you explicitly bind-mount into the container. Mount each agent’s session root read-only and point the matching directory env var at it. The data volume (/data) is owned by root inside the container, so prefer a named Docker volume over a host bind mount, or pre-create the host directory with the desired ownership.

A production-style Compose example lives in the repo at docker-compose.prod.yaml. It persists /data in a named volume, mounts Claude, Codex, and OpenCode session roots read-only, and publishes the UI on 127.0.0.1:8080:

docker compose -f docker-compose.prod.yaml up -d

The example publishes the UI on loopback only. To expose it beyond the host, also enable bearer-token authentication and publish the port intentionally.

For a PostgreSQL-backed deployment, point the container at your shared database:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e PG_SERVE=1 \
  -e AGENTSVIEW_PG_URL='postgres://user:password@host:5432/agentsview?sslmode=require' \
  ghcr.io/wesm/agentsview:latest

Run

The desktop app handles startup automatically — just open the app. CLI users start the server manually:

agentsview serve

This will:

1. Initialize the SQLite database at ~/.agentsview/sessions.db
2. Discover and sync sessions from all supported agents
3. Start watching session directories for changes
4. Launch the web UI at http://127.0.0.1:8080

Open http://127.0.0.1:8080 in your browser. Pass --no-browser to disable automatic browser launch.

Customize

Override the default port or host:

agentsview serve --port 9090
agentsview serve --host 0.0.0.0 --port 3000
agentsview serve --no-browser  # Disable browser auto-open

Point to custom session directories with environment variables:

export CLAUDE_PROJECTS_DIR=~/custom/claude/projects
export CODEX_SESSIONS_DIR=~/custom/codex/sessions
export COPILOT_DIR=~/custom/copilot
export CURSOR_PROJECTS_DIR=~/custom/cursor/projects
export GEMINI_DIR=~/custom/gemini
export OPENCODE_DIR=~/custom/opencode
export AMP_DIR=~/custom/amp/threads
export VSCODE_COPILOT_DIR=~/custom/vscode
export OPENCLAW_DIR=~/custom/openclaw/agents
export PI_DIR=~/custom/pi/sessions
export IFLOW_DIR=~/custom/iflow/projects
export ZENCODER_DIR=~/custom/zencoder/sessions
export KIMI_DIR=~/custom/kimi/sessions
export WARP_DIR=~/custom/warp
export HERMES_SESSIONS_DIR=~/custom/hermes
export CORTEX_DIR=~/custom/cortex
export KIRO_SESSIONS_DIR=~/custom/kiro
export KIRO_IDE_DIR=~/custom/kiro-ide
agentsview serve

What You’ll See

Once running, the web UI provides:

• Session list with filtering by project, agent, date, and message count
• Message viewer with full content, tool calls, and thinking blocks
• Session intelligence with health grades, outcomes, and signal panels
• Full-text search across all message content
• Analytics including activity heatmaps, tool usage, and velocity charts
• Session export to standalone HTML, markdown export links for agent handoff, or GitHub Gist