---
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](https://agentsview.io/docs/) follow `main`.
The latest release is **v0.46.1**. Check the
[changelog](https://agentsview.io/docs/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](https://agentsview.io/docs/chat-import/#sync-claudeai-chats),
opt-in
[Codex cloud chats](https://agentsview.io/docs/configuration/#codex-cloud), and
Muse Code and fx sessions. Preserve a retired machine's history with
[local archives](https://agentsview.io/docs/commands/#agentsview-archive), or
sync a remote machine over
[SSH](https://agentsview.io/docs/remote-access/#ssh-remote-sync) 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.
<p align="center">
<img src="https://agentsview.io/assets/generated/screenshots/dashboard.png" alt="Analytics dashboard" width="720">
</p>
## Install
**macOS and Linux:**
```bash
curl -fsSL https://agentsview.io/install.sh | bash
```
**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://agentsview.io/install.ps1 | iex"
```
Or download the **desktop app** (macOS / Windows) from
[GitHub Releases](https://github.com/kenn-io/agentsview/releases) or via
homebrew: `brew install --cask agentsview`
On macOS, see
[Use the bundled CLI](https://agentsview.io/docs/quickstart/#macos-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:
```bash
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
```bash
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. `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](https://agentsview.io/docs/configuration/#session-discovery).
The same guide explains how to choose
[what content to archive](https://agentsview.io/docs/configuration/#archive-content).
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:
```bash
# 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](https://agentsview.io/remote-access/#public-url-and-trusted-origins)
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](https://agentsview.io/docs/configuration/#container-deployment)
for every variable.
`docker-compose.prod.yaml` is included as a production example:
```bash
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:
```bash
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:
```bash
# 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:
```bash
# 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.
```bash
# 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.
```bash
# 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:
```bash
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](https://agentsview.io/one-shot-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).
```bash
# 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](https://agentsview.io/semantic-search/))
- **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](https://agentsview.io/docs/data/#enable-the-project-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](https://agentsview.io/docs/mcp/#focused-memory-profile)
- **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,
`Ctrl/Cmd+G` to open a session by ID or UUID, `?` for all shortcuts)
- **Export** sessions as HTML or publish to GitHub Gist
## 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 | `~/.forge/` |
| Gemini CLI | `~/.gemini/` |
| Goose | `~/.local/share/goose/sessions/` (macOS and Linux), `%APPDATA%\\Block\\goose\\data\\sessions\\` (Windows) |
| Crush | `~/.local/share/crush/projects.json` registry pointing at per-project `~/<project>/.crush/crush.db` stores (macOS and Linux), `%LOCALAPPDATA%\\crush\\projects.json` (Windows) |
| gptme | `~/.local/share/gptme/logs/` |
| Grok | `~/.grok/sessions/` |
| Hermes Agent | `~/.hermes/sessions/` (macOS and Linux), `~/AppData/Local/hermes/sessions/` (Windows) |
| iFlow | `~/.iflow/projects/` |
| Junie | `~/.junie/sessions/` (CLI `SessionStore`; IDE-only conversations are not exposed by current JetBrains artifacts) |
| Kilo | `~/.local/share/kilo/` |
| Kilo (legacy) | `~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/` (macOS), `~/.config/Code/User/globalStorage/kilocode.kilo-code/` (Linux) |
| Kimi | `~/.kimi/sessions/` |
| Kimi Work | `~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/home/sessions/` (macOS) |
| Kiro CLI | `~/.kiro/sessions/cli/`, `~/.local/share/kiro-cli/` |
| Kiro IDE | `~/Library/Application Support/Kiro/` (macOS) |
| MiMoCode | `~/.local/share/mimocode/` |
| Mistral Vibe | `~/.vibe/logs/session/` |
| Muse Code | `~/.local/share/muse/sessions/` (`$XDG_DATA_HOME/muse/sessions/` when `XDG_DATA_HOME` is set) |
| OpenClaw | `~/.openclaw/agents/` |
| OpenCode | `~/.local/share/opencode/` |
| Open Code Review | `~/.opencodereview/sessions/` |
| OpenHands CLI | `~/.openhands/conversations/` |
| OMO | `~/.omo/agent/sessions/` |
| OhMyPi | `~/.omp/agent/sessions/` |
| Omnigent | `~/.omnigent/chat.db` |
| Pi | `~/.pi/agent/sessions/` |
| fx | `~/.fx/sessions/` |
| Tau | `~/.tau/sessions/` |
| Prime Agent | `~/.prime/agent/sessions/` |
| StepCode | `~/.stepcode/agent/sessions/` |
| Poolside | `~/Library/Application Support/poolside/trajectories/` (macOS), `~/.local/state/poolside/trajectories/` (Linux), `%APPDATA%\\poolside\\trajectories\\` (Windows) |
| Piebald | `~/.local/share/piebald/` |
| Posit Assistant | `~/.posit/assistant/workspaces/` |
| Positron Assistant | `~/Library/Application Support/Positron/User/` (macOS) |
| QClaw | `~/.qclaw/agents/` |
| Qoder | `~/.qoder/projects/`, `~/.qoderwork/projects/` |
| Qwen Code | `~/.qwen/projects/` |
| QwenPaw | `~/.copaw/workspaces/`, `~/.qwenpaw/workspaces/` |
| Reasonix | `~/.reasonix/`, `%APPDATA%\\reasonix\\` (Windows) |
| RooCode | `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/` (macOS), `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/` (Linux), `%APPDATA%\\Code\\User\\globalStorage\\rooveterinaryinc.roo-cline\\` (Windows) |
| VSCode Copilot | `~/Library/Application Support/Code/User/` (macOS) |
| Visual Studio Copilot | `%LOCALAPPDATA%\\Temp\\VSGitHubCopilotLogs\\traces\\` (Windows), `~/Library/Caches/VSGitHubCopilotLogs/traces/` (macOS), `~/.cache/VSGitHubCopilotLogs/traces/` (Linux) |
| Windsurf | `~/Library/Application Support/Windsurf/User/` (macOS), `~/.config/Windsurf/User/` (Linux), `%APPDATA%\\Windsurf\\User\\` (Windows) |
| Trae | `%APPDATA%\\Trae\\User\\` (Windows), `~/Library/Application Support/Trae/User/` (macOS), `~/.config/Trae/User/` (Linux) |
| TraeX (TRAE CLI) | `~/.trae/cli/sessions/`, `~/.trae/cli/archived_sessions/` |
| Warp | `~/.warp/` (platform-dependent) |
| WorkBuddy | `~/.workbuddy/projects/` |
| CodeBuddy CN | `%LOCALAPPDATA%\\CodeBuddyExtension\\Data\\` (Windows), `~/Library/Application Support/CodeBuddyExtension/Data/` (macOS), `~/.config/CodeBuddyExtension/Data/` (Linux) |
| ZCode | `~/.zcode/cli/db/`, `~/.zcode/cli/` |
| Zed | `~/Library/Application Support/Zed/` (macOS) |
| Zencoder | `~/.zencoder/sessions/` |
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](https://agentsview.io/docs/configuration/#session-discovery)
for provider details and limits.
Each directory can be overridden with an environment variable. See the
[configuration docs](https://agentsview.io/configuration/) 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](https://github.com/MCBoarder289/copilot-jetbrains-exporter),
then point agentsview at that output directory.
```bash
# 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`:
```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](https://github.com/mjacobs/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.
```bash
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](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](https://agentsview.io/configuration/#upgrading-historical-machine-keys).
One primary AgentsView instance can ingest native agent session directories
copied or mounted from other machines without PostgreSQL:
```toml
[[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](https://agentsview.io/filesystem-sync/)
for Git, rsync, shared-mount, freshness, and operational guidance.
## PostgreSQL Sync
Push session data to a shared PostgreSQL instance for team dashboards:
```bash
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)
```
Opt-in [hosted raw processing](docs/hosted-raw-sync.md) 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:
```toml
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:
```bash
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:
```bash
chmod 600 ~/.agentsview/config.toml
```
To run it unattended as an OS service (launchd on macOS, `systemd --user` on
Linux):
```bash
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:
```bash
loginctl enable-linger "$USER"
```
See [PostgreSQL docs](https://agentsview.io/postgresql/) 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:
```bash
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:
```toml
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.
```bash
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](https://agentsview.io/docs/clickhouse-sync/) 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.
```bash
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](docs/configuration.md#anonymous-daemon-telemetry) 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](docs/configuration.md#anonymous-daemon-telemetry) also count
empty searches, visible errors, and failed sync attempts. The events include
`application=agentsview`, app version, commit, 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`. Only release builds send telemetry, and it stays off in CI and
Go test binaries.
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](https://agentsview.io)**:
[Quick Start](https://agentsview.io/quickstart/) --
[Usage Guide](https://agentsview.io/usage/) --
[CLI Reference](https://agentsview.io/commands/) --
[Configuration](https://agentsview.io/configuration/) --
[Filesystem Sync](https://agentsview.io/filesystem-sync/) --
[Architecture](https://agentsview.io/architecture/)
______________________________________________________________________
## Development
Requires Go 1.27.3+ (CGO), Node.js 24.22.1+.
```bash
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
```
```bash
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](https://github.com/j178/prek): run
`make lint-tools` and `make install-hooks` after cloning (requires `prek` 0.5.7
or newer and `uv`).
### 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](https://github.com/andyfischer/ai-coding-tools/tree/main/claude-history-tool)
by Andy Fischer and
[claude-code-transcripts](https://github.com/simonw/claude-code-transcripts) by
Simon Willison.
## License
MIT