agentsview

# 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`. Check the [changelog](https://agentsview.io/docs/changelog/) for released features.

## 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` 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`, and `duckdb 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 container image defaults to local `agentsview serve`. Set `PG_SERVE=1` to switch the startup command to `agentsview pg serve` instead. `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`). If you need to expose it beyond localhost, enable `--require-auth` and publish the port 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 PG_SERVE=1 \ -e AGENTSVIEW_PG_URL='postgres://user:[email protected]: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: ``` … ``` 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 ` 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 # JSON output for scripting agentsview session usage --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 ` 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 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`;