last_edited: 2026-10-22

agentsview

Browse, search, and track costs across your AI coding agents. Your session archive stays on your machine unless you choose a feature that shares it.

This README and the documentation follow main. The latest release is v0.46.1. Check the changelog for what it includes.

Version 0.46.1 fixes Antigravity transcripts and read-only mounts, preserves repeated prompts, and restores container builds.

Version 0.46.0 adds Claude.ai Sync through Chrome, opt-in Codex cloud chats, and Muse Code and fx sessions. Preserve a retired machine's history with local archives, or sync a remote machine over SSH without installing a daemon. Find work by label or linked pull request, narrow cost charts by project, and inspect tool effectiveness with transcript evidence. Connected assistants gain eight read-only MCP tools for the same archive.

Install

macOS and Linux:

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

Windows (PowerShell):

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

Or download the desktop app (macOS / Windows) from GitHub Releases or via homebrew: brew install --cask agentsview

On macOS, see Use the bundled CLI for terminal setup and the required first launch. For Macs managed over SSH, use the standalone CLI installer above.

Or run the published Docker image:

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

Quick Start

agentsview serve           # start the server in the foreground
agentsview daemon start    # alternatively, start the same server in the background
agentsview daemon status   # show daemon status
agentsview daemon restart  # restart from current configuration
agentsview daemon stop     # stop the server, web UI, and sync
agentsview session list    # read from the daemon if warm, otherwise SQLite
agentsview usage daily     # print daily cost summary

On first run, agentsview discovers sessions from every supported agent on your machine, syncs them into a local SQLite database, and serves a web UI at http://127.0.0.1:8080.

The daemon is the server: the web UI, API, session sync, and file watchers share one process. Choose serve for a foreground process or daemon start for a background process. Running serve when a compatible daemon is already running reports its URL and exits with an error (status 1) in the foreground. daemon stop and serve stop both stop that writable server, including sync; serve stop also stops read-only mirror servers for the same data directory.

For custom directories, additional agent homes, and supported S3 sources, see Session discovery. The same guide explains how to choose what content to archive.

The desktop app and ordinary session CLI commands share a detached local daemon and start one when needed. Dedicated diagnostics such as db adopt-machine --list and doctor sync read the archive without starting it. Commands such as sync, usage, token-use, pg push, duckdb push, and clickhouse push auto-start the daemon when needed. Daily usage reports read saved archive data; run agentsview sync first to include new source changes. The server remains running after these commands exit and also serves the web UI. For a one-shot sync with no background server, stop the daemon first and run AGENTSVIEW_NO_DAEMON=1 agentsview sync.

Use agentsview daemon start when you want to start the writable SQLite daemon explicitly. It loads the normal effective configuration from config.toml and supported environment variables; daemon start and daemon restart accept no serve-specific flags. Background daemons self-exit after an idle period unless a client request or daemon-owned job is active.

The existing agentsview serve --background, agentsview serve status, and agentsview serve stop commands remain available. Use serve --background when a one-off daemon needs a serve-only flag, such as --no-sync or an unauthenticated non-loopback --host override.

Remote / forwarded access

agentsview binds to loopback and validates the request Host header to guard against DNS-rebinding attacks. When you reach it through SSH port-forwarding, a reverse proxy, or a remote dev environment (exe.dev, Codespaces, Coder, WSL2), the browser sends a Host that the server does not recognize, so API requests such as /api/v1/settings are rejected with 403 Forbidden.

To fix this, restart the server with --public-url set to the exact origin you open in the browser:

# Browser opens http://127.0.0.1:18080 via `ssh -L 18080:127.0.0.1:8080 host`
agentsview serve --public-url http://127.0.0.1:18080

# Browser opens a forwarded hostname
agentsview serve --public-url https://your-workspace.exe.dev

--public-url also selects the URL opened on startup; it does not configure a listener or external proxy. Use --no-browser on a headless server, or use --public-origin (repeatable or comma-separated) on its own for trust-only configuration. If you expose the UI beyond loopback, also enable --require-auth. See Remote Access for the listener, browser URL, and managed Caddy port rules.

Docker

The image runs the agentsview binary directly. With no command it starts agentsview serve; set AGENTSVIEW_MODE=pg-serve (or pass pg serve) to read PostgreSQL instead. The older PG_SERVE=1 selector still works.

The image listens on 0.0.0.0 inside the container, does not open a browser, and requires bearer-token authentication. Those defaults come from environment variables, so flags you pass, such as --port 9000, keep them. On first start the image generates a token and stores it in /data/config.toml; read it with docker exec <container> grep auth_token /data/config.toml, or supply your own through a mounted secret file named by AGENTSVIEW_AUTH_TOKEN_FILE. See the container deployment guide for every variable.

docker-compose.prod.yaml is included as a production example:

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

The included compose file persists the agentsview data directory in a named volume and mounts Claude, Codex, Forge, and OpenCode session roots read-only. The container runs as root, so prefer a named volume for /data over a host bind mount; if you do bind-mount, pre-create the directory with the desired ownership to avoid root-owned files in your home directory.

The examples publish the UI on loopback only (127.0.0.1). Every request needs the bearer token, including the DuckDB and Quack examples below, which bind the container's wildcard host. Publish the port beyond localhost only intentionally.

Important: a containerized agentsview instance can only discover agent sessions from directories you explicitly mount into the container. If you do not mount an agent's session directory and point the matching env var at it, that agent will not appear in the UI.

Example PostgreSQL-backed startup:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e AGENTSVIEW_MODE=pg-serve \
  -e AGENTSVIEW_PG_URL='postgres://user:password@postgres.example.com:5432/agentsview?sslmode=require' \
  ghcr.io/kenn-io/agentsview:latest

Example DuckDB mirror startup:

# Populate /data/sessions.duckdb from the mounted SQLite archive.
docker run --rm \
  -v agentsview-data:/data \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  ghcr.io/kenn-io/agentsview:latest duckdb push --full

# Serve the populated mirror read-only.
docker run --rm -p 127.0.0.1:8080:8080 \
  -v agentsview-data:/data \
  ghcr.io/kenn-io/agentsview:latest duckdb serve

Example Quack startup:

# Expose the local DuckDB mirror over Quack from the host/container.
QUACK_TOKEN="$(openssl rand -base64 32)"
docker run --rm -p 127.0.0.1:9494:9494 \
  -v agentsview-data:/data \
  ghcr.io/kenn-io/agentsview:latest \
  duckdb quack serve \
    --bind quack:0.0.0.0:9494 \
    --token "$QUACK_TOKEN" \
    --allow-insecure

# Serve the web UI from a remote Quack endpoint.
# The client url uses the native quack:HOST:PORT form; the Quack extension
# does not accept quack:http:// or quack:https:// urls. A non-loopback host
# needs --allow-insecure.
docker run --rm -p 127.0.0.1:8080:8080 \
  -e AGENTSVIEW_DUCKDB_URL='quack:duckdb.example.com:9494' \
  -e AGENTSVIEW_DUCKDB_TOKEN="$QUACK_TOKEN" \
  ghcr.io/kenn-io/agentsview:latest duckdb serve --allow-insecure

Keep Quack on loopback or behind TLS. Plain HTTP Quack on a non-loopback bind requires --allow-insecure and should only be used behind a trusted tunnel or reverse proxy.

Token Usage and Cost Tracking

agentsview usage tracks token consumption and compute costs across all your coding agents -- not just Claude Code. Reports read from the same local SQLite archive that powers the UI.

# Daily cost summary (default: last 30 days)
agentsview usage daily

# Per-model breakdown
agentsview usage daily --breakdown

# Filter by agent and date range
agentsview usage daily --agent claude --since 2026-04-01

# One-line summary for shell prompts / status bars
agentsview usage daily --all --json
agentsview usage statusline

Features:

• Automatic pricing via LiteLLM and OpenRouter rates (with offline fallback)
• Authoritative Copilot CLI billing totals when session logs provide them
• Prompt-caching-aware cost calculation (cache creation / read tokens)
• Per-model breakdown with --breakdown
• Date filtering (--since, --until, --all), agent filtering (--agent)
• JSON output (--json) for scripting
• Timezone-aware date bucketing (--timezone)
• Works standalone -- no server required, just run the command

Per-Session Details

agentsview session usage <id> prints per-session token statistics plus a cost estimate for a single s