---

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:[email protected]: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 session. The output reports the session's total output tokens and peak context tokens, plus a cost estimate (cost) when pricing is available for the session's model(s) (has_cost). Cost is computed from input/output and cache tokens internally, but only the output-token and peak-context totals are reported alongside the cost.

# Print token usage and cost for a specific session
agentsview session usage <id>

# JSON output for scripting
agentsview session usage <id> --format json

The same per-session usage data is available from the REST API:

GET /api/v1/sessions/{id}/usage

The response includes the session_id, agent, project, total_output_tokens, peak_context_tokens, has_token_data, cost, has_cost, models, and unpriced_models fields from the CLI JSON schema. Machine-readable money is always an integer microdollar object, for example {"cost":{"microdollars":2410000}}; CLI tables and labels render that value as ordinary dollars. HTTP responses also include server_running: true. Existing sessions return 200 even when token or cost data is absent; missing sessions return 404.

The deprecated alias agentsview token-use <id> remains available for compatibility and now also reports cost estimates.

For one exact non-interactive claude -p or codex exec --json execution in CI, use agentsview capture run. It preserves the child streams and exit outcome, writes a separate versioned usage result, and starts no daemon, web server, or watcher. See One-shot CI capture.

Session Stats

agentsview stats emits window-scoped analytics over recorded sessions: totals, archetypes (automation vs. quick/standard/deep/marathon), distributions for session duration, user-message count, peak context, and tools-per-turn, plus cache economics, tool/model/agent mix, and a temporal hourly breakdown. The --format json output follows a versioned v1 schema (schema_version: 1) suitable for downstream consumers.

By default, stats only reads the local SQLite archive. Git-derived outcome metrics are opt-in because they can be slow or brittle on large/missing repos: use --include-git-outcomes for commits/LOC/files changed, and --include-github-outcomes for GitHub PR counts via gh (this also enables git outcomes).

# Human-readable summary over the last 28 days
agentsview stats

# Machine-readable JSON over a fixed date range
agentsview stats --format json --since 2026-04-01 --until 2026-04-15

# Restrict to one agent and inspect the schema
agentsview stats --format json --agent claude | jq '.schema_version'

# Include expensive local git outcome metrics explicitly
agentsview stats --include-git-outcomes

Session Browser

Dashboard	Session viewer

Search	Activity heatmap

• Full-text search across all message content (FTS5), with project and date filters in the command palette and optional CJK character and phrase search for Chinese, Japanese, and Korean text in SQLite, including Chinese word segmentation through simple/cppjieba
• Semantic search (opt-in) -- index session content with any OpenAI-compatible embeddings endpoint and search by meaning with agentsview session search --semantic or --hybrid; every content-search match cites the conversation unit it came from (docs)
• Token usage and cost dashboard -- per-session and per-model cost breakdowns, total and uncached input counts, and daily spend charts with Smooth, Lines, and Bars views
• Analytics dashboard -- activity heatmaps, tool usage, velocity metrics, project breakdowns, message roles, and Git outcome totals
• Activity dashboard -- concurrency, user-message and assistant-message frequency, active time, and cost over the selected dates
• Tool sequences -- follow errors, retries, tool switches, and recovery back to the recorded calls, with no model calls or token charges
• Recent Edits feed -- the files your agents changed most recently across every session, grouped by project and path, each linking to the message that made the change
• Project mapping -- manage worktree rules from Data. An opt-in workspace adds folder suggestions, session previews, and bulk corrections
• Recall corpus browser -- approve or archive experimental extracted knowledge and jump from entries to their supporting transcript evidence
• Conversation memory -- native Claude Code and Codex plugins let agents search past decisions and cite source messages; see MCP memory setup
• Eight interface languages -- Azerbaijani, English, French, Japanese, Korean, Spanish, Simplified Chinese, and Traditional Chinese
• Live updates via SSE as active sessions receive new messages
• Keyboard-first navigation (j/k/[/], Ctrl/Cmd+K search, to open a session by ID or UUID, for all shortcuts)

Supported Agents

agentsview discovers sessions from all of these. Aider is opt-in because it has no central session directory; set AIDER_DIR or agents.aider.dirs to enable it. Amp support is deprecated because current Amp releases may store threads server-side and leave only local stubs; agentsview can still parse historical local Amp thread JSON files.

Agent	Session Directory
Aider	<repo>/.aider.chat.history.md (per repo; opt in with AIDER_DIR or agents.aider.dirs)
Amp (deprecated)	~/.local/share/amp/threads/ (historical local thread JSON only)
Augure Code	~/.augure/sessions/
Augure Desktop	~/.augure-desktop/ (macOS/Linux), %LOCALAPPDATA%\augure-desktop\ (Windows)
Antigravity	~/.gemini/antigravity/, ~/.gemini/antigravity-ide/
Antigravity CLI	~/.gemini/antigravity-cli/ (see note below)
Cline CLI	~/.cline/data/sessions/ (CLI sessions only)
Claude Code	~/.claude/projects/
OpenClaude	~/.openclaude/projects/
Claude Cowork	~/Library/Application Support/Claude/local-agent-mode-sessions/ (macOS)
Codex	~/.codex/sessions/
Codex Cloud	Fetched from OpenAI (ChatGPT dot, Codex web and cloud tasks); off until [agents.codex-cloud] enabled = true
Copilot CLI	~/.copilot/
Devin CLI	~/.local/share/devin/ (Linux), ~/Library/Application Support/devin/ (macOS); point DEVIN_DIR / agents.devin.dirs at the root that contains cli/
Evener	~/.local/state/evener/projects/ (or $XDG_STATE_HOME/evener/projects/; semantic transcript v2)
Cortex Code	~/.snowflake/cortex/conversations/
Cursor	~/.cursor/projects/
DeepSeek TUI	~/.codewhale/sessions/, ~/.deepseek/sessions/
DeepSeek Harness	~/.dsh/sessions/ (or $DSH_HOME/sessions/)
Forge

Grok sessions are read from summary.json (title, timestamps, project), optional signals.json (token counters), and chat_history.jsonl when present for the full transcript (user turns, assistant replies, thinking, and tool calls). If chat_history.jsonl is missing, AgentsView falls back to summary-only mode. Set GROK_DIR or agents.grok.dirs to override the default directory.

Goose sessions are read from its shared SQLite sessions.db, including transcript content, thinking, tool calls and results, session relationships, models, token usage, and recorded costs. Set GOOSE_PATH_ROOT to a Goose path root (sessions are read from <root>/data/sessions/), or agents.goose.dirs to one or more data or sessions directories.

Crush sessions are read from each project's SQLite .crush/crush.db, including transcript content, thinking, tool calls and results, session relationships, models, and recorded session totals. Per-message tokens and cache breakdowns are not available. The project registry lives at ~/.local/share/crush/projects.json (macOS and Linux) or %LOCALAPPDATA%\crush\projects.json (Windows). Set CRUSH_DIR or agents.crush.dirs to one or more Crush data directories, .crush directories, or crush.db files.

Cline support covers the CLI, not the VS Code extension. Augure Code is tracked separately from Codex and resumes through the Augure CLI; its proprietary models remain unpriced. Augure Desktop support covers version 3 beta and does not include remote sync. See session discovery for provider details and limits.

Each directory can be overridden with an environment variable. See the configuration docs for details. Cursor attribution stats are a live, machine-local read from ~/.cursor/ai-tracking/ai-code-tracking.db by default and can be redirected with AGENTSVIEW_CURSOR_ATTRIBUTION_DB; they are not synced or aggregated through PostgreSQL.

Aider: per-repo Markdown logs

Aider has no central session store; it writes one .aider.chat.history.md Markdown log per repository, and one log accumulates many runs (one per aider launch, delimited by # aider chat started at ... headers). agentsview indexes each run as its own session.

AgentsView does not scan for Aider logs by default. Earlier builds attempted an always-on bounded scan of the home directory, but that was not trustworthy: desktop launches and background usage refreshes could still trigger macOS privacy prompts for protected folders. To enable Aider, point AIDER_DIR (or the agents.aider.dirs config key) at a code root you explicitly want scanned. The scan descends at most four levels below each configured root, skips vendor/build/VCS directories by name (node_modules, target, .git, Library, go, .cargo, and similar), and stops after a two-second wall-clock budget. On macOS, broad home roots still skip protected top-level folders unless one of those folders is configured directly. The live file watcher only watches configured Aider roots shallowly; new repos are picked up by the periodic sync, which runs every 15 minutes.

Because the format is Markdown-derived, roles are reconstructed from line prefixes and there are no per-message timestamps; a run's start time comes from its # aider chat started at ... header (written in local time, assumed UTC).

JetBrains Copilot via exporter

JetBrains IDEs store Copilot chat in a Nitrite database that agentsview does not read directly. The supported path today is to export those sessions to Copilot JSONL with copilot-jetbrains-exporter, then point agentsview at that output directory.

# Export JetBrains Copilot sessions to JSONL
copilot-jetbrains-exporter --output ~/.copilot/jetbrains-sessions

# Tell agentsview to index the exported sessions
export COPILOT_DIR=~/.copilot/jetbrains-sessions

Or in ~/.agentsview/config.toml:

[agents.copilot]
dirs = ["~/.copilot/jetbrains-sessions"]

Re-run the exporter after new JetBrains Copilot sessions if you want agentsview to pick up fresh conversations from that source.

Antigravity CLI: high-resolution transcripts

Antigravity CLI sessions appear in two on-disk formats: newer releases store conversation trajectories as SQLite .db files, older releases used AES-GCM-encrypted .pb files. For either format, the full transcript -- structured tool calls, results, reasoning, and diffs -- comes from a <uuid>.trajectory.json sidecar. Without a covering sidecar, agentsview falls back to summary mode: a heuristic decode of the raw .db steps (prompts and tool-call names only), or for .pb sessions your prompts from history.jsonl plus any plain-text artifacts under brain/ (plans, walkthroughs, checkpoints). Summary-mode sessions show a "Summary mode" badge in the detail header that links here.

To unlock full transcripts for .db and .pb sessions alike, run agy-reader alongside agentsview. agy-reader talks to the local Antigravity daemon, decrypts each conversation, and writes a <uuid>.trajectory.json sidecar next to the source file. agentsview's file watcher detects the sidecar automatically and parses it in place of summary mode -- no agentsview restart needed.

go install github.com/mjacobs/agy-reader@latest

# Generate sidecars for existing sessions...
agy-reader --sync

# ...or keep them fresh as you work.
agy-reader --watch

agy-reader auto-discovers the Antigravity daemon URL by parsing ~/.gemini/antigravity-cli/cli.log. If discovery fails (e.g. the log has rotated), the command prints platform-specific instructions for locating the port and exporting ANTIGRAVITY_DAEMON_URL manually.

Sidecars stay on your machine. agentsview makes no outbound request to produce or read them, and treats sidecars as untrusted structured input -- see SECURITY.md for the trust model.

Kilo vs Kilo (legacy).

Kilo is the OpenCode-based CLI/editor core (~/.local/share/kilo/kilo.db); it covers both the Kilo CLI and the rebuilt Kilo Code VS Code extension (after March 2026), which shares that same database. Kilo (legacy) is the legacy RooCode-derived VS Code extension that wrote per-task JSON under kilocode.kilo-code/tasks/.

Filesystem Session Sync

Local imports use a persisted installation ID, so updates and network changes do not split sessions across machine identities. telemetry-install-id stores the ID independently of telemetry. The display label defaults to the current hostname; set local_machine_name in config.toml for a fixed label after a daemon restart. Upgrades adopt historical local sessions when the archive has saved ownership. Older archives keep historical keys until you select the local ones with agentsview db adopt-machine; see the upgrade guide.

One primary AgentsView instance can ingest native agent session directories copied or mounted from other machines without PostgreSQL:

[[session_sources]]
agent = "copilot"
dir = "/srv/session-archive/buildbox/copilot"
machine = "0123456789abcdef0123456789abcdef" # Peer installation ID

Structured sources are additive to existing agents.copilot.dirs, agents.claude.dirs, and other per-agent settings. They label sessions by source machine without namespacing native session IDs. Transport source session files only -- never copy sessions.db or its WAL files. Machine keys are captured at first ingestion; ordinary sync and agentsview sync --full preserve the stored key. Use a peer's ID from telemetry-install-id for remote roots. For local roots, omit machine, removing any existing hostname setting. Adopted old keys remain aliases for existing filters and URLs.

See the Filesystem Session Sync guide for Git, rsync, shared-mount, freshness, and operational guidance.

PostgreSQL Sync

Push session data to a shared PostgreSQL instance for team dashboards:

agentsview pg push             # push local data to the default PG target
agentsview pg push archive     # push to one named PG target
agentsview pg push --all       # push every configured PG target sequentially
agentsview pg status           # show status for the default PG target
agentsview pg status archive   # show status for one named PG target
agentsview pg status --all     # show status for every configured PG target
agentsview pg serve            # serve web UI from the default PG target (read-only)

AGENTSVIEW_DATA_DIR=/data agentsview pg serve --push-watch

Use --push-watch to ingest mounted sessions and serve them from PostgreSQL in one process; see PostgreSQL Sync for setup and shutdown.

Opt-in hosted raw processing lets pg serve parse uploaded sources directly into PostgreSQL. It requires explicit tenant/schema provisioning, a restricted runtime role, authentication and Linux isolation. Ordinary PG serving remains read-only; pg push refuses hosted-owned schemas.

Single-target configs still use the legacy [pg] block. To manage more than one PostgreSQL destination, define named [pg.NAME] blocks and set default_pg when more than one target exists:

default_pg = "work"

[pg.work]
url = "postgres://user:pass@work-db/agentsview"

[pg.archive]
url = "postgres://user:pass@archive-db/agentsview"
exclude_projects = ["scratch"]

Named target names are normalized case-insensitively. all, local, and the legacy [pg] field names url, schema, machine_name, allow_insecure, projects, exclude_projects, raw_tenant, raw_derivation, raw_poll_seconds, raw_attempt_seconds, and raw_max_attempts cannot be used for [pg.NAME].

AGENTSVIEW_PG_URL, AGENTSVIEW_PG_SCHEMA, and AGENTSVIEW_PG_MACHINE still work, but in named-target mode they apply only to the effective default target. They do not rewrite every named [pg.NAME] entry.

Automatic push (background service)

To keep a shared PostgreSQL database current without running pg push by hand, run the auto-push daemon. It watches your session directories and pushes shortly after new sessions are recorded, with a periodic floor as a safety net:

agentsview pg push --watch                 # foreground, Ctrl-C to stop
agentsview pg push archive --watch         # watch one named PG target
agentsview pg push --watch --debounce 1m   # custom coalesce window
agentsview pg push --watch --interval 5m   # custom floor interval

--watch follows the default PG target unless you pass one target name. --all --watch is rejected; multi-target background watch remains out of scope for now.

The daemon reads the same [pg] config as pg push, so the PostgreSQL DSN must be set in your config file (or an environment variable it expands). Protect the config file, since it holds credentials:

chmod 600 ~/.agentsview/config.toml

To run it unattended as an OS service (launchd on macOS, systemd --user on Linux):

agentsview pg service install     # generate the unit, enable + start it
agentsview pg service status      # show manager status
agentsview pg service logs -f     # follow the service log
agentsview pg service uninstall   # stop and remove

pg serve and pg service always use the effective default PG target. In named-target mode, set default_pg to choose which target those long-running commands use.

Linux headless machines: systemd --user services stop at logout and do not start at boot unless lingering is enabled for your user. install detects this and prints the command; you can also run it yourself:

loginctl enable-linger "$USER"

See PostgreSQL docs for setup and configuration.

ClickHouse Sync

Push session data to a ClickHouse instance. clickhouse push writes the copy; clickhouse serve queries it. SQLite stays the archive, the same operator story as PostgreSQL:

agentsview clickhouse push             # push local data to the default target
agentsview clickhouse push archive     # push to one named target
agentsview clickhouse push --all       # push every configured target sequentially
agentsview clickhouse status           # show status for the default target
agentsview clickhouse serve            # serve web UI from the default target (read-only)

Single-target configs use the legacy [clickhouse] block. To manage more than one destination, define named [clickhouse.NAME] blocks and set default_clickhouse when more than one target exists:

default_clickhouse = "work"

[clickhouse.work]
url = "clickhouse://user:pass@work-db:9440/agentsview?secure=true"

[clickhouse.archive]
url = "clickhouse://user:pass@archive-db:9440/agentsview?secure=true"
exclude_projects = ["scratch"]

Named target names are normalized case-insensitively. all, local, and the legacy [clickhouse] field names url, database, machine_name, allow_insecure, projects, and exclude_projects cannot be used for [clickhouse.NAME].

AGENTSVIEW_CLICKHOUSE_URL, AGENTSVIEW_CLICKHOUSE_DATABASE, and AGENTSVIEW_CLICKHOUSE_MACHINE still work, but in named-target mode they apply only to the effective default target.

agentsview clickhouse push --watch                 # foreground, Ctrl-C to stop
agentsview clickhouse service install              # launchd / systemd --user

--all --watch is rejected. clickhouse serve and clickhouse service always use the effective default target. Non-loopback URLs require verified TLS unless allow_insecure = true.

See ClickHouse docs for setup and configuration.

DuckDB Mirror and Quack

DuckDB support is a mirror backend, not a replacement for the local SQLite archive. agentsview serve still performs primary ingestion into SQLite. Use DuckDB when you want a portable analytics file, read-only local serving from a mirror, or remote read access through DuckDB's Quack protocol.

agentsview duckdb push          # mirror SQLite into DuckDB
agentsview duckdb status        # show mirror sync status
agentsview duckdb serve         # serve web UI from DuckDB (read-only)
agentsview duckdb quack serve   # expose the local DuckDB file over Quack

agentsview duckdb serve reads [duckdb].path or AGENTSVIEW_DUCKDB_PATH. To serve from a remote Quack endpoint, set AGENTSVIEW_DUCKDB_URL and AGENTSVIEW_DUCKDB_TOKEN instead. Quack is still a new DuckDB protocol, so agentsview keeps conservative defaults: local Quack serving binds to loopback, requires a token, and rejects non-loopback plain HTTP unless --allow-insecure is explicit. For remote use, prefer a TLS URL or put Quack behind an authenticated tunnel/proxy.

Backend modes:

• SQLite: primary local archive, file sync, FTS5 search, and writable UI.
• PostgreSQL: optional shared team backend; push from SQLite, serve read-only.
• ClickHouse: optional remote backend; push from SQLite, serve read-only.
• DuckDB: optional mirror file or Quack endpoint; push from SQLite, serve read-only.

Troubleshooting:

• If duckdb push fails to open the mirror, confirm the binary was built with the DuckDB Go driver for your platform and that AGENTSVIEW_DUCKDB_PATH points to a writable file location.
• If Quack commands fail with extension errors, update the agentsview binary so the embedded DuckDB runtime includes the Quack extension.
• If a remote attach fails, check the token, the quack: URL, TLS/proxy termination, and whether the server was intentionally started with --allow-insecure for plain non-loopback binds.
• DuckDB search currently uses substring/regex fallback behavior. SQLite FTS5 remains the indexed search path for primary local serving.

Privacy

agentsview sends limited anonymous telemetry to PostHog: a daemon_active ping at most once per UTC day while the server runs. The browser checks with app_opened once a day; reloads and focus don't repeat it that day, and a disabled reply stops reports and visit tracking. See the telemetry configuration for scope and delivery limits. The server also sends setup_finished once per installation when the archive first has a session in the default session list, including orphaned sessions and excluding automated sessions and trash. Existing installs with such a session send it on their first start after upgrading. The web UI sends visit_ended with surface: web and visible visit duration in fixed buckets: under_1m, 1_to_5m, 5_to_30m, or over_30m. The web UI also reports searches (search mode), session views (the session's agent type), screen views (screen name, once per installation per UTC day on the server), exports (format), generated insights (insight kind), and analytics page views (page name), each with one value from a fixed list in the server that drops anything else. All events use a stable random install ID as the event DistinctId. Feature outcomes also count empty searches, visible errors, and failed sync attempts. The events include application=agentsview, app version, commit, distribution (such as homebrew; empty for source builds), OS, and CPU architecture, with $process_person_profile=false and $geoip_disable=true. It does not include session, project, prompt, file path, account, or machine identity. Disable telemetry with AGENTSVIEW_TELEMETRY_ENABLED=0, TELEMETRY_ENABLED=0, or DO_NOT_TRACK=1. A build sends telemetry only when it has the PostHog project key and a release version such as 0.33.0. Release builds and the make build targets set the key at link time. Plain go build and go test binaries have no key and send nothing. Telemetry also stays off in CI.

All session data stays on your machine. The server binds to 127.0.0.1 by default. The update check is optional and can be disabled with --no-update-check.

Documentation

Full docs at agentsview.io: Quick Start -- Usage Guide -- CLI Reference -- Configuration -- Filesystem Sync -- Architecture

---

Development

Requires Go 1.27.3+ (CGO), Node.js 24.22.1+.

make dev            # Go server (dev mode)
make frontend-dev   # Vite+ dev server (run alongside make dev)
make build          # build binary with embedded frontend
make install        # install to ~/.local/bin

make test           # Go tests (CGO_ENABLED=1 -tags "fts5")
make bench-backends # compare SQLite, DuckDB, and PostgreSQL store reads
make lint           # golangci-lint + NilAway
make nilaway        # NilAway through custom golangci-lint
make e2e            # Playwright E2E tests

make bench-backends requires Docker. It starts a PostgreSQL container with testcontainers, mirrors the same SQLite fixture into DuckDB and PostgreSQL, and benchmarks the shared db.Store read queries for relative comparison. The default fixture is 1,000 sessions and 64,000 messages; use BENCH_BACKENDS_SESSIONS and BENCH_BACKENDS_MESSAGES_PER_SESSION to scale it. When the Docker CLI uses a non-default socket, export DOCKER_HOST for that socket before running the benchmark.

Pre-commit and pre-push hooks via prek: run make lint-tools and make install-hooks after cloning (requires prek 0.5.7 or newer and uv).

Shared Go build cache

make targets build and test Go code with -trimpath. Compiled packages then record module-relative source paths instead of the checkout's absolute path, so every clone and git worktree shares one Go build cache. Without it, each worktree compiles and stores its own copy of every package.

• Opt out for one command with make test GOFLAGS=-trimpath=false.
• Plain go commands outside make do not add the flag. Run go env -w GOFLAGS=-trimpath to make it your default; make keeps flags saved this way and appends -trimpath only when it is missing.

Trimmed binaries need a source mapping in Delve:

• dlv debug and dlv test inherit GOFLAGS and cannot find source files. Pass --build-flags=-trimpath=false. Debug builds disable optimizations, so they never shared cache entries with normal builds anyway.
• For dlv exec or dlv attach on a trimmed binary, start Delve from the repository root and run config substitute-path -guess (Delve 1.24 or newer). It maps the module path to your checkout, the standard library to GOROOT, and dependencies to the module cache.

Project Layout

cmd/agentsview/     CLI entrypoint
internal/           Go packages (config, db, parser, server, sync, postgres)
frontend/           Svelte 5 SPA (Vite+, TypeScript)
desktop/            Tauri desktop wrapper

Acknowledgements

Inspired by claude-history-tool by Andy Fischer and claude-code-transcripts by Simon Willison.

License

MIT