Skip to content

Latest commit

 

History

History
1659 lines (1336 loc) · 89.5 KB

commands.md

File metadata and controls

1659 lines (1336 loc) · 89.5 KB
title CLI Reference
description All AgentsView commands, flags, and environment variables

Commands

agentsview capture

Capture and export the usage of one exact non-interactive automation run without starting the daemon, server, web interface, or watchers:

agentsview capture run \
  --provider claude \
  --occurrence build-42 \
  --capture-dir ./capture-build-42 \
  --result ./usage-build-42.json \
  -- claude -p "Diagnose the build failure."

agentsview capture report \
  --capture-dir ./capture-build-42 \
  --result ./usage-build-42.json

capture run supports direct claude -p and codex exec --json producer adapters. It leaves child standard input, output, error, and exit outcome intact. The result always uses a separate file; recovery-only capture report may use --result - for standard output. See One-shot CI capture for the result contract, retry behavior, failure codes, and a complete GitHub Actions job.


agentsview raw-sync

Capture supported local provider sources and upload their raw generations to hosted custody:

export AGENTSVIEW_RAW_SYNC_URL=https://agents.example.com
export AGENTSVIEW_RAW_SYNC_DEVICE_ID=device-id
export AGENTSVIEW_RAW_SYNC_CREDENTIAL=device-credential
agentsview raw-sync watch
agentsview raw-sync status

raw-sync watch runs an initial bounded audit, watches for filesystem changes, and retries interrupted uploads from its durable local checkpoint. The device credential is accepted only through AGENTSVIEW_RAW_SYNC_CREDENTIAL, never as a command-line flag. --server and --device-id override their corresponding environment variables.

Flag Default Description
--server environment Raw-sync server URL
--device-id environment Provisioned device ID
--allow-insecure-http false Allow HTTP for a loopback server only
--debounce 2s Coalescing window for filesystem changes
--interval 15m Interval between bounded provider audits
--audit-limit 128 Maximum source work in each provider audit

raw-sync status reads the checkpoint without creating one and prints path-free JSON containing capture, queue, retry, failure, and coverage state. S3 roots are not captured. A deployment operator must provision the device ID and credential; there is no public enrollment command yet. Accepted raw generations are not yet parsed into hosted sessions. See Hosted Raw Sync for the current boundary.


agentsview daemon

Manage the writable SQLite server. The daemon provides the web UI, API, session sync, and file watchers in one process. daemon start launches the same server as serve --background, using saved configuration and without opening a browser. It does not require a separate serve command.

agentsview daemon start
agentsview daemon status
agentsview daemon restart
agentsview daemon stop
Command Behavior
start Start the daemon, or report the existing writable daemon
status Show writable daemon state, URL, PID, version, and uptime
restart Stop and restart the writable daemon; start it if it is already stopped
stop Stop the writable daemon, or report that it is already stopped

daemon start and daemon restart load the normal effective configuration from config.toml and supported environment variables. They accept no serve-specific flags: persistent daemon settings belong in configuration. --no-sync is runtime-only and is not a config.toml setting. Use agentsview serve --background --no-sync when a one-off detached server must disable sync. Similarly, use agentsview serve --background --host <address> for a one-off unauthenticated non-loopback bind; a persistent non-loopback host in config.toml requires require_auth = true.

These commands manage only the writable SQLite daemon for the current data directory, including a foreground serve process or a daemon auto-started by a CLI command. daemon stop stops the web UI and background sync together. They ignore read-only agentsview pg serve and agentsview duckdb serve processes. If only read-only servers are running, daemon status reports that no daemon is running, and daemon stop and daemon restart leave those servers alive.

Status distinguishes running, starting, and stopped states. daemon start returns after its initial readiness wait if a long migration or sync is still running; the child continues in the background. daemon restart stays attached and prints phase, detail, and elapsed-time updates until the replacement daemon is ready. Canceling that wait with Ctrl+C leaves the child running. Use agentsview daemon status and inspect the reported serve.log when startup is slow. If startup state remains stuck, follow the error's guidance to verify the owning process before terminating it manually and retrying.


agentsview serve

Start the HTTP server with embedded web UI, session sync, and file watchers in the foreground. It remains attached to the terminal until you press Ctrl+C, unless --background is specified. This is the same writable server managed by agentsview daemon; the web UI and sync do not have separate lifecycles.

If a compatible server is already running, serve reports its URL and exits. Open that URL to use the web UI. Stopping the server with either daemon stop or serve stop also stops its sync and file watchers. --no-sync disables automatic sync in that process; it does not create a separate sync daemon.

agentsview serve [flags]

As of 0.23.0, starting the server requires the explicit serve subcommand. Running plain agentsview shows help instead of starting the web UI.

Flag Default Description
--host 127.0.0.1 Host to bind to
--port 8080 Port to listen on
--no-browser false Don't open browser on startup
--no-sync false Disable initial, watched, and periodic sync
--no-update-check false Disable automatic update checks
--require-auth false Require a bearer token for API requests
--background false Start agentsview serve as a managed background process
--replace false Replace a running local daemon before starting
--public-url Browser URL, also added to trusted origins
--public-origin Trusted browser origin (repeatable/comma-separated)
--proxy Managed proxy mode (caddy)
--caddy-bin caddy Caddy binary path
--proxy-bind-host 127.0.0.1 Interface for managed proxy
--public-port URL port or 8443 Managed Caddy HTTP/HTTPS listener and URL port
--tls-cert TLS certificate path
--tls-key TLS key path
--allowed-subnet Client CIDR allowlist (repeatable/comma-separated)

The server auto-discovers an available port if 8080 is busy. See Remote Access for details on the remote access and proxy flags.

Examples:

agentsview serve                                # defaults
agentsview serve --port 9090                    # custom port
agentsview serve --no-browser                   # disable browser auto-open
agentsview serve --background                   # start managed background server
agentsview serve --replace                      # replace an existing daemon
agentsview serve --public-url https://agents.example.com

On startup, the server:

  1. Loads or creates ~/.agentsview/sessions.db
  2. Runs initial sync across all discovered session directories
  3. Starts the file watcher (500ms event batching; watcher sync starts remain at least five seconds apart)
  4. Starts periodic sync (every 15 minutes)
  5. Serves the Svelte SPA and REST API

The server shuts down cleanly on Ctrl+C, flushing the database and stopping file watchers.

Background Mode

The existing serve background and lifecycle forms remain available:

agentsview serve --background
agentsview serve status
agentsview serve restart
agentsview serve stop

The parent command starts a detached agentsview serve process and waits for it to publish its runtime record. The five-second readiness window measures startup inactivity, so continuing startup progress can keep the parent waiting longer. It then prints the URL, PID, and log path. Background server output is written to ~/.agentsview/serve.log. serve status reports the preferred managed process, URL, version, uptime, and read-only mode when available. serve stop retains its broad lifecycle scope: it gracefully terminates confirmed writable SQLite and read-only PostgreSQL or DuckDB server processes for the data directory and cleans up their runtime records.

serve restart is intentionally narrower and config-driven. It restarts only the writable SQLite daemon, leaves read-only servers alive, and starts the writable daemon if it was stopped. It accepts no serve flags and uses the same effective configuration as daemon restart. It is not equivalent to the broader serve stop followed by a foreground serve start.

When a writable daemon is already running, a newer release binary automatically replaces an older compatible daemon before starting. Development builds, downgrades, and forward API/data-version conflicts do not auto-replace; use --replace when you deliberately want this invocation to stop the running daemon first. If the SQLite archive itself has a newer data version than the current binary can open, serve refuses before stopping the old daemon. serve status reports incompatible live daemons with their daemon and binary versions plus daemon restart or daemon stop guidance.

Background servers also act as the shared local daemon for the desktop app and CLI. The daemon owns local SQLite writes for its data directory, so common write and freshness-sensitive commands proxy to it instead of opening the archive as a second writer. A background daemon self-exits after the idle timeout when no external request or daemon-owned job is active. Periodic sync and file-watcher work prevent exit while they run, but do not keep the daemon alive forever by themselves.

CLI daemon behavior

Ordinary session commands, including session list, session get, and session messages, require a compatible local daemon and start one when needed. Use db adopt-machine --list to inspect historical machine keys or doctor sync for diagnostics. These dedicated commands read the archive without starting a daemon or changing configuration.

Commands that need fresh data or need to write auto-start the detached daemon when no compatible daemon is running. That includes local sync, session sync, token-use, normal usage refresh paths, pg push/pg push --watch, and duckdb push. If a writable daemon is known to own the archive but is not reachable, these commands refuse instead of writing directly.

Set AGENTSVIEW_NO_DAEMON=1 to disable daemon auto-start. Commands that require the daemon refuse while it is disabled. Direct write commands acquire the local write-owner lock before opening SQLite. If another process owns that lock, the command refuses and asks you to stop the daemon, wait for idle shutdown, or retry after the offline operation finishes.


agentsview sync

Refresh the local archive. For local sync, the CLI uses the running daemon or starts a detached daemon so SQLite writes stay owned by one process. That daemon also serves the web UI and remains running after the CLI exits, until stopped or its idle timeout expires. The command prints the server URL and how to stop it.

An incremental local-only sync through the default daemon waits when another sync or maintenance pass owns it, then runs its requested pass. It prints waiting status; Ctrl+C cancels the wait without stopping the existing work. This waiting message applies when no remote hosts are configured. Full resync, syncs that include remote hosts, and servers started with --no-sync also wait for exclusive access, but do not show this message. If the wait persists, inspect agentsview daemon status and serve.log. A daemon launched for this local sync skips its redundant startup sync.

For a one-shot offline sync, stop the writable daemon first, then run:

agentsview daemon stop
AGENTSVIEW_NO_DAEMON=1 agentsview sync

The environment variable disables daemon auto-start. It does not stop an existing daemon or bypass its write-owner lock. The offline command acquires that lock, syncs directly, and exits without leaving a server running.

agentsview sync [flags]
Flag Default Description
--full false Force a full resync regardless of data version
--target Exchange normalized artifacts with a trusted folder
--host SSH hostname for deprecated remote sync
--user SSH username for deprecated remote sync
--port 22 SSH port for deprecated remote sync

Examples:

agentsview sync           # incremental sync and exit
agentsview sync --full    # full resync and exit
agentsview sync --target /path/to/shared-folder
agentsview sync --host buildbox.local
agentsview sync --host buildbox.local --user wes --port 2222

After syncing, a summary of session and message counts is printed to stdout. With --target, AgentsView then performs one bounded normalized-artifact exchange. See Artifact Folder Sync for the trust model, first-use requirements, and exclusions. --target cannot be combined with --host.

When --host is set, AgentsView syncs only that remote host and fails fast on error. If the local daemon has a matching configured [[remote_hosts]] entry, the daemon uses that stored entry and its configured transport. Otherwise, --host performs an ad hoc SSH sync: it resolves the supported agent session directories on the remote machine, transfers the source session data locally, and indexes it into your local archive. SSH remote sync is deprecated and receives only critical fixes; use configured HTTP remote sync for new setups.

Local sync can also read configured Claude, Codex, and Cursor roots from S3-compatible object storage. Add s3:// entries to agents.claude.dirs, agents.codex.dirs, or agents.cursor.dirs in ~/.agentsview/config.toml, then run agentsview sync normally. This is not SSH remote sync: object storage is treated as a read-only session source, using object size and LastModified metadata to skip unchanged sessions and downloading only objects that need parsing. See Configuration — S3-Compatible Session Sources.

Configured Remote Hosts

As of 0.33.0, remote hosts can also be declared in ~/.agentsview/config.toml so a single bare agentsview sync covers a whole fleet:

[[remote_hosts]]
host = "buildbox.local"
transport = "ssh" # optional; default
user = "wes"      # optional
port = 2222       # optional, defaults to 22

[[remote_hosts]]
host = "devbox1"
transport = "http"
url = "http://devbox1.tailnet.ts.net:8080"
token = "remote-token"

With hosts configured, agentsview sync (no --host) includes local sources and configured HTTP hosts in one coordinated sync. During a full or automatic data-version rebuild, AgentsView prepares every HTTP mirror, bulk-ingests the local and HTTP sources into one temporary database with FTS updates suspended, rebuilds FTS once, and atomically swaps the completed archive into place. SSH hosts run through their existing active-archive path only after that swap.

--full reparses every discovered local and remote session, but it does not force unchanged manifest-capable files to transfer again. Directory-scoped and verbatim curated content still use delta transfer. Windsurf's sanitized curated export remains a separate full-archive transfer on every sync. HTTP collectors and spokes must use the same remote-sync protocol version; incompatible peers fail before exchanging targets or archive data. A configured HTTP host that is offline, unreachable, or times out is skipped; reachable HTTP hosts still join the combined rebuild. Other HTTP preparation or contributor failures abort the combined rebuild without replacing the active archive or running SSH. Ordinary incremental and post-swap SSH failures retain per-host reporting, and the command exits non-zero for any failure other than an unavailable configured HTTP host. See Incremental Sync.

agentsview sync --host X syncs one host, not the whole configured list. When the local daemon knows a configured host with that identity, it uses the stored entry and transport so HTTP hosts can be selected by host name. Without a matching configured host, --host remains an ad hoc SSH sync. SSH remote sync is deprecated and receives only critical fixes. It remains non-interactive in both forms — it requires key-based passwordless SSH and never prompts for a password. Prefer configured HTTP remote sync.

HTTP remote sync requires a reachable remote daemon, preferably over a private network such as Tailscale, and remote archive endpoints always require bearer auth. The per-host token is required and must match the remote daemon's auth_token; do not reuse the collector daemon's own token for untrusted remote endpoints. Ad hoc HTTP remotes are not supported. Hosts must be unique within the list, since remote sessions are namespaced by host.

During HTTP remote sync, the collector prints durable phase lines for resolving remote roots, fetching and comparing the manifest, transferring and extracting changed files, planning pending paths, processing affected sources, rebuilding FTS, and swapping the database. Pending paths can outnumber processed sources: deletions participate in recovery and cache invalidation but usually do not produce an import source. Provider fallback is identified explicitly, and its discovered sources determine the processing denominator.

The final per-host line reports changed sessions, ordinary unchanged skips, and error-suppressed pending entries. A retained-journal line means recovery work will be replayed; cancellation, processing failure, cache-persistence failure, retirement failure, and a rebuild awaiting its database swap remain distinct. Individual source paths are omitted from normal output. Archive downloads also show live compressed-byte progress when the remote daemon provides a Content-Length header. These phases come from the collector; a spoke upgrade is needed only for manifest-delta transfer. If an upgraded binary does not show them, restart the local collector daemon.


agentsview prune

Delete sessions matching one or more filters. At least one filter is required.

agentsview prune [flags]
Flag Default Description
--project Sessions whose project contains this substring
--max-messages -1 Sessions with at most N messages
--before Sessions that ended before this date (YYYY-MM-DD)
--first-message Sessions whose first message starts with this text
--dry-run false Show what would be pruned without deleting
--yes false Skip confirmation prompt

Examples:

# Preview what would be deleted
agentsview prune --project "scratch" --dry-run

# Delete short sessions from before 2025
agentsview prune --max-messages 2 --before 2025-01-01

# Delete sessions starting with a specific message
agentsview prune --first-message "test" --yes

# Combine filters (AND logic)
agentsview prune --project "old-project" --max-messages 5 --before 2025-06-01

The prune command displays the number of sessions deleted and disk space reclaimed. Use --dry-run first to verify the filter matches what you expect.


agentsview db adopt-machine

Assign historical local machine keys to this installation. Use this when an upgrade could not establish which archived sessions are local, or to adopt additional old hostnames you own. Inspect the archive first, then stop the daemon:

agentsview db adopt-machine --list
agentsview daemon stop
agentsview db adopt-machine host-a.example host-b.example
agentsview daemon start

Use --list alone to print machine keys with session and worktree-rule counts. It does not start a daemon, write configuration, or adopt sessions.

Select only keys whose sessions belong to this installation. The command moves their sessions, worktree rules, and project and source metadata to the current installation ID. Session IDs, messages, stars, pins, and other curation stay intact. Old named keys remain aliases for filters and URLs. Conflicting worktree rules stop the command so you can reconcile them before retrying.

Keys that belong to other installations need no action. Legacy local rows always belong to this archive and are assigned to its installation ID at startup.

The command records ownership in the archive; changing local_machine_name only changes a display label. See Upgrading Historical Machine Keys for automatic adoption and mirror updates.


agentsview db compact

Rebuild the local SQLite archive into a staged, verified database and reclaim free pages. The command also truncates the WAL. It does not compress or deduplicate live tool-result payloads, so it does not change future growth from those payloads.

agentsview db compact [flags]
Flag Default Description
--staging-dir Filesystem location for the staged database
--dry-run false Report the estimate without changing the archive
--keep-backup false Keep the original database backup
--yes false Skip the confirmation prompt
--format human Use json for machine-readable output

JSON mode writes only the final result to stdout and requires --yes; prompts and human progress messages are written to stderr. When a writable daemon owns the archive, --staging-dir is not accepted because the daemon chooses its own staging location and the compact endpoint is restricted to localhost. The command probes for an existing daemon and never starts one: maintenance must not trigger a daemon's startup sync. When no daemon owns the archive, the command takes the direct write lock and compacts in process.

On a shared filesystem, peak additional space includes the original backup, the compacted candidate, a second candidate copy beside the live database, and a safety margin. With separate filesystems, staging needs the backup plus one candidate and the database filesystem needs the installation copy. The live source remains present until the final rename and is never credited as free space. For a large archive, use a separate volume with enough capacity:

agentsview db compact --dry-run
agentsview db compact \
  --staging-dir /mnt/cache/data-cache/agentsview-compact \
  --keep-backup --yes

When a writable daemon is running, the command sends the request to that daemon. Direct file access is refused while another daemon owns the archive. Reads continue during the staged build, while writes are refused with a retryable archive-maintenance error until the verified replacement is committed; connections pause only for the final swap. Compactions are serialized per archive: a compaction requested while a sync, resync, or another compaction is running fails immediately with a conflict instead of queueing.

If a compaction is interrupted or fails partway, the archive stays safe: a recovery manifest (compact-recovery.json beside the database) records the operation, and the next writable start finishes or rolls back the replacement before the archive opens. Until then the daemon may keep refusing writes and the error names the manifest; restarting the daemon resolves it. Once a compaction has committed, recovery only cleans up leftover staging files and never replaces the archive, so sessions ingested after a compaction are never at risk. Do not delete the manifest or the database files by hand.


agentsview db strip --images

Remove supported inline image payloads from stored tool-result rows. The command requires --images; it uses the existing direct maintenance write owner and confirmation prompt. It never changes provider source files or standalone image files. Run db compact separately when you need measured SQLite file-space reclamation. Changed sessions are automatically rescanned for secrets so detections reflect the remaining content.

agentsview db strip --images [flags]
Flag Default Description
--images false Required image cleanup operation
--project Sessions whose project contains this substring
--before Sessions that ended before this date (YYYY-MM-DD)
--dry-run false Preview selected sessions and byte counts
--yes false Skip confirmation
--format human Use json for machine-readable output

JSON apply requires --yes. Preview and a declined confirmation leave the archive unchanged. Reported stored-content bytes and decoded image bytes are content measurements, not reclaimed disk space.


agentsview db migrate --images

Move retained inline tool-result image payloads from currently stored archive rows into the asset store at {dataDir}/assets. Each payload is written as a content-addressed file named <sha256hex><ext>. Before the row changes, an existing object must have the expected byte count and SHA-256 digest. A missing or corrupt object is replaced while the source bytes remain available. The inline input_image block is replaced with an agentsview_image placeholder whose image_ref field holds the asset:// reference. The GET /api/v1/assets/{filename} route and renderMarkdown resolve these references from the local assets directory.

The image appears when a tool result's output is switched to formatted mode and every other block in that result is a text block. Raw mode shows the stored text, including the markdown reference, as it always has, and so does a result that still holds an unmigrated image block, such as an SVG or an image/bmp payload beside a migrated PNG. Under require_auth the asset route rejects the browser's image request, because an img element sends no Authorization header. Chat-imported images already carry that limit.

Migration changes currently stored rows. A later keep-mode reparse or full resync can restore inline bytes from provider source files. The tool_result_images = "drop" policy keeps supported images projected during future ingestion and full resync. The command requires --images and never changes provider source files. A separate serving host needs the matching {dataDir}/assets directory as well as the copied database content. Run db compact separately to measure SQLite file-space reclamation after migration. Back up the {dataDir}/assets directory together with the archive.

If a session transaction fails after writing assets, its rows remain unchanged but complete, unreferenced asset files remain on disk. Retrying the migration reuses matching files; there is no automatic cleanup of unreferenced assets. Both db migrate --images and db strip --images report the sessions that committed before a later failure.

JPEG assets now use .jpg filenames, including .jpeg files copied from chat imports. Existing asset://<hash>.jpeg references still resolve, but re-importing an export with those files can create a second copy under .jpg.

Only the four passive image media types are migrated: image/png, image/jpeg, image/webp, image/gif. Every other payload stays inline, including SVG, which the serving route refuses as active content, and near-misses such as the non-canonical image/jpg spelling. db strip --images is broader and replaces any image/* payload with a placeholder, so the two commands do not select the same rows.

agentsview db migrate --images [flags]
Flag Default Description
--images false Required image migration operation
--project Sessions whose project contains this substring
--before Sessions that ended before this date (YYYY-MM-DD)
--dry-run false Preview selected sessions and byte counts
--yes false Skip confirmation
--format human Use json for machine-readable output

JSON apply requires --yes. Preview and a declined confirmation leave the archive and assets directory unchanged. Reported stored-content bytes and decoded image bytes are content measurements, not reclaimed disk space.


agentsview version

Print the version, git commit, and build date. Use --json for a stable, machine-readable response that does not require a running daemon, configuration, or database.

agentsview version
agentsview version --json
agentsview version --format json
agentsview v0.38.0 (commit 5b42bf1c, built 2026-07-13T15:37:17Z)
{
  "schema_version": 1,
  "name": "agentsview",
  "version": "v0.38.0",
  "commit": "5b42bf1c",
  "build_date": "2026-07-13T15:37:17Z"
}

The JSON contract uses these fields:

Field Type Meaning
schema_version integer Version of this JSON contract; currently 1
name string Canonical tool name, always agentsview
version string Build version
commit string Source commit recorded at build time
build_date string UTC build timestamp, or an empty string

Consumers should require the expected schema_version and ignore unknown fields. Adding an optional field does not require a schema bump; removing or renaming a field, changing a field's type or meaning, or making a previously valid response invalid does.


agentsview usage daily

Report token usage and estimated cost aggregated by local-time day, scoped to the last 30 days by default. See Token Usage & Costs for a full write-up on reporting behavior and agent coverage.

The report reads committed archive data. If it starts the daemon, session sync runs in the background; run agentsview sync first when new source changes must be included. An older archive that requires reparsing is upgraded before the daemon starts serving, with startup progress shown in the terminal. A cold usage cache prepares the sessions needed for the report without waiting for the full archive backfill. Slow reports print the current preparation phase and elapsed time to stderr, including with --json. Usage preparation is not subject to the server's normal write timeout. Press Ctrl+C to stop waiting; shared cache work can continue in the daemon.

Restart older daemons after upgrading so they provide the usage progress endpoint. session usage, token-use, and usage statusline still wait for initial sync, including when they reuse a daemon started by daily usage. Statusline limits the complete wait and report request to 30 seconds.

agentsview usage daily [flags]
Flag Default Description
--format human Output format: human or json
--json false Alias for --format json
--since 30 days ago Start of window, a duration like 28d or a YYYY-MM-DD date, inclusive
--until End of window, a duration like 28d or a YYYY-MM-DD date, inclusive
--all false Scan all history; overrides the default 30-day window
--agent Filter by agent name
--breakdown false Show per-model rows and populate detailed JSON breakdown arrays
--offline false Read the archive directly without sync or pricing fetches
--no-sync false Skip source refresh; a new daemon starts without automatic sync
--timezone system IANA timezone name for date bucketing

Examples:

agentsview usage daily                           # last 30 days
agentsview usage daily --all                     # full history
agentsview usage daily --since 14d               # last 14 days
agentsview usage daily --since 2026-04-01 --breakdown
agentsview usage daily --json --agent claude

agentsview usage statusline

Print today's total estimated cost as a single line, for shell prompts and tmux status lines.

agentsview usage statusline [flags]
Flag Default Description
--format human Output format: human or json
--json false Alias for --format json
--agent Filter by agent name
--offline false Read the archive without sync or pricing fetches
--no-sync false Skip source refresh

Example:

$ agentsview usage statusline
$9.61 today
$ agentsview usage statusline --json
{
  "date": "2026-08-04",
  "cost": {
    "microdollars": 9610000
  }
}

See Token Usage & Costs for integration examples (Starship, tmux).


agentsview usage cursor

Fetch Cursor Admin API usage events and store them in the local archive so they contribute to the Usage dashboard and daily reports.

agentsview usage cursor [flags]
Flag Default Description
--since 30 days ago Start date (YYYY-MM-DD), inclusive
--until today End date (YYYY-MM-DD), inclusive
--all false Include all history
--page-size 100 Events requested per Cursor API page
--email config Filter by Cursor team member email
--user-id config Filter by Cursor team member user ID

Examples:

agentsview usage cursor
agentsview usage cursor --since 2026-05-01 --until 2026-05-31
agentsview usage cursor --all --email [email protected]

See Cursor Admin Usage Events for setup and reporting behavior.


agentsview activity report

Report active time, concurrency, cost, token, breakdown, and session rows for a resolved date range. The command uses the same report model as the web UI's Activity page.

agentsview activity report [flags]
Flag Default Description
--preset Range preset: day, week, month, or custom
--date today Anchor date for day/week/month presets (YYYY-MM-DD)
--from Start instant for custom range (RFC3339)
--to End instant for custom range (RFC3339)
--timezone system IANA timezone for range bucketing
--bucket automatic Bucket size: 5m, 15m, 1h, 1d, or 1w
--project Filter by project
--agent Filter by agent name
--machine Filter by machine name
--format human Output format: human or json
--json false Alias for --format json
--no-sync false Skip on-demand sync before querying
--offline false Use fallback pricing only

Examples:

agentsview activity report --preset day --date 2026-06-20
agentsview activity report --preset week --date 2026-06-20 --json
agentsview activity report --preset custom \
  --from 2026-06-20T14:00:00Z \
  --to 2026-06-20T18:00:00Z \
  --bucket 15m

The human output prints totals, peak concurrency, top project/model/ agent breakdowns, and top sessions. JSON output includes the dense bucket timeline and session rows used by the web UI.


agentsview token-use

!!! note "Deprecated"

As of 0.30.0, `agentsview token-use` is a deprecated alias for
[`agentsview session usage`](/docs/session-api/#agentsview-session-usage). Both
commands accept the same `<session-id>` argument. `token-use` always emits the
same JSON shape that `session usage --format json` emits (now extended with a
cost estimate). New scripts should use `agentsview session usage`.

Print machine-readable token usage data and a cost estimate for a single session.

agentsview token-use <session-id>

Session ID format depends on the agent. For example, Claude root sessions usually use UUIDs like 550e8400-e29b-41d4-a716-446655440000, Claude subagents use IDs like agent-a86574e, and some other agents use prefixes such as codex:my-session-id. Raw session IDs emitted by the underlying agent are also accepted when AgentsView can resolve them back to the canonical stored session.

If the AgentsView server is already running, the command reads the current database state. If no server is running, it performs an on-demand sync for the requested session first.

As of 0.40.0, the reported totals include every subagent transcript the session spawned, so the cost matches what the session actually spent. token-use has no opt-out; use agentsview session usage <id> --own-only for own-session numbers.

Example:

agentsview token-use 550e8400-e29b-41d4-a716-446655440000
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent": "claude",
  "project": "my-project",
  "total_output_tokens": 15230,
  "peak_context_tokens": 84000,
  "has_token_data": true,
  "cost": {"microdollars": 2410000},
  "has_cost": true,
  "cost_usd": 2.41,
  "models": ["claude-opus-4-7"],
  "server_running": false
}

cost_usd is a deprecated compatibility alias for cost.microdollars / 1e6 and will be removed in a future release; new consumers should read cost.microdollars directly.

See agentsview session usage for the full field reference and exit-code contract.


agentsview pg push

Sync sessions from local SQLite to PostgreSQL. See PostgreSQL Sync for full documentation.

agentsview pg push [target] [flags]
Flag Default Description
--full false Force full local resync and re-push
--no-vectors false Skip the semantic-search vector phase for this run
--projects Comma-separated projects to push (inclusive)
--exclude-projects Comma-separated projects to exclude from push
--all-projects false Ignore configured project filters for this run
--all false Push every configured PostgreSQL target sequentially
--watch false Run continuously, pushing on change plus a periodic floor
--debounce 30s Coalesce window after a change before pushing (--watch only)
--interval 15m Periodic floor push interval (--watch only)

See PostgreSQL Sync — Project Filtering for details on how filtering interacts with the push watermark.


agentsview pg status

Show PostgreSQL sync status.

agentsview pg status [target] [flags]
Flag Default Description
--all false Show status for every configured PostgreSQL target
--projects Comma-separated projects whose push status to show
--exclude-projects Comma-separated excluded projects whose push status to show
--all-projects false Ignore configured project filters for this status

agentsview pg serve

Start a read-only session web UI backed by PostgreSQL. On a writable PostgreSQL schema, the same server also registers the hosted raw-sync control plane. See PostgreSQL Sync for full server documentation.

agentsview pg serve [flags]

Accepts the same serve flags (--host, --port, --proxy, etc.) plus PostgreSQL configuration from config.toml. When the host's [vector] config matches a generation pushed to PostgreSQL, semantic and hybrid search are served from pgvector — see Semantic Search — PostgreSQL.


agentsview pg service

Install and manage the PostgreSQL auto-push service, which runs agentsview pg push --watch in the background. Supported service managers are launchd on macOS and systemd --user on Linux. See PostgreSQL Sync — agentsview pg service for setup notes.

agentsview pg service install
agentsview pg service status
agentsview pg service logs [-f]
agentsview pg service start
agentsview pg service stop
agentsview pg service uninstall
Command Description
install Generate the service unit, enable it, and start it
status Show the service-manager status plus last successful push
logs -f Follow pg-watch.log under the AgentsView data directory
start Start the installed service
stop Stop the installed service
uninstall Stop and remove the service unit

agentsview pg vectors

Inspect and drop semantic-search embedding generations stored in PostgreSQL. See Semantic Search — Maintenance for details.

agentsview pg vectors list [flags]
agentsview pg vectors drop <id> [flags]
Command Description
list List generations with model, dimension, document/chunk counts, and contributing machines
drop <id> Drop a generation and all of its embeddings (prompts for confirmation)
Flag Default Description
--target PG target name (default: the default configured target)
--yes false Skip the confirmation prompt (drop only)

agentsview duckdb

Mirror the local SQLite archive into DuckDB and serve from it, locally or over the Quack remote protocol. See DuckDB Mirror for full documentation.

agentsview duckdb push          # mirror SQLite into sessions.duckdb
agentsview duckdb status        # show mirror sync status
agentsview duckdb serve         # read-only web UI from the mirror
agentsview duckdb quack serve   # expose the mirror over Quack

duckdb push accepts the same --full / --projects / --exclude-projects / --all-projects / --watch / --debounce / --interval flags as pg push. duckdb push always writes the local mirror file at [duckdb].path; it never targets a remote Quack endpoint. If [duckdb].url or AGENTSVIEW_DUCKDB_URL is configured, push fails immediately with an error to unset it and serve the mirror remotely with duckdb quack serve instead. duckdb status and duckdb serve do target the remote Quack endpoint when [duckdb].url or AGENTSVIEW_DUCKDB_URL is set, and the local mirror file otherwise. When [duckdb].path or AGENTSVIEW_DUCKDB_PATH is set, duckdb quack serve exposes that same mirror by default unless --path overrides it. duckdb serve accepts the same serve flags as pg serve. The DuckDB backend is unavailable on Windows ARM64 (the upstream bindings ship no prebuilt library for that platform); all other commands work normally there.


agentsview projects

List all projects in the local database with their session counts.

agentsview projects [flags]
Flag Default Description
--format human Output format: human or json
--json false Alias for --format json

Examples:

agentsview projects         # tabular output
agentsview projects --json   # JSON array

agentsview health

Inspect session intelligence in a human-friendly CLI view. See Session Intelligence for the scoring and signal model.

agentsview health [session-id] [flags]
Flag Default Description
--format human Output format: human or json
--json false Alias for --format json
--limit 20 Number of sessions to list when no session ID is given

Examples:

agentsview health
agentsview health --limit 50
agentsview health 550e8400-e29b-41d4-a716-446655440000
agentsview health agent-a86574e --json

Without a session ID, the command lists recent sessions with grade and outcome columns. With a session ID, it prints the detailed signal counts for that session.


agentsview stats

Experimental window-scoped workspace analytics across sessions and git activity. See Stats for the full write-up.

agentsview stats [flags]
Flag Default Description
--format human Output format: human or json
--json false Alias for --format json
--since 28d Start of window, either YYYY-MM-DD or a compact duration like 28d
--until End of window as YYYY-MM-DD
--agent all Restrict to one agent or use all
--include-project Repeatable project allowlist
--exclude-project Repeatable project blocklist
--timezone local Timezone used for temporal reporting

Examples:

agentsview stats
agentsview stats --format json --since 2026-04-01 --until 2026-04-15
agentsview stats --agent claude --include-project agentsview

The command is experimental. The exact human output may change, and the JSON output should be treated as a moving surface even though it currently carries schema_version: 1.


agentsview doctor sync

Collect read-only diagnostics for startup sync decisions. This command does not create or migrate config files; it loads the current config read-only, inspects the SQLite archive, checks configured agent roots, and prints recent sync-related debug.log lines.

agentsview doctor sync

The report includes:

  • data directory and SQLite database path
  • whether the database exists and is readable
  • SQLite user_version and the binary data version
  • the startup sync decision
  • session counts by stored data version
  • leftover resync temp files
  • configured/default agent roots and whether each exists
  • recent debug lines mentioning sync, data versions, warnings, or failures
  • Antigravity CLI summary-mode counts and Antigravity sessions decoded from unrecognized agy-schema: fingerprints
  • a likely-cause summary when startup sync behavior looks abnormal

agentsview parse-diff

Validate parser changes against the real session archive already in your local SQLite database. The command re-parses source files with the current binary, normalizes them through the sync path, and reports field-level differences from the stored rows without writing updated session data.

agentsview parse-diff [flags]
Flag Default Description
--agent Restrict to one agent; repeatable
--limit 0 Maximum number of source files to inspect, newest first (0 means all)
--fail-on-change false Exit non-zero when changes or parse errors are found
--format human Output format: human or json
--json false Alias for --format json
--verbose / -v false Include more detail in the human report

Examples:

agentsview parse-diff --agent claude --limit 100
agentsview parse-diff --agent codex --fail-on-change
agentsview parse-diff --json > parser-report.json

parse-diff is intended for parser development and release QA. Run it against a quiescent, freshly synced archive for the clearest signal. Import-only sources are skipped because there is no source file to re-parse. Provider-backed stores with authoritative local sources, including Warp, Forge, Piebald, and Devin, are covered alongside normal file-backed agents.

The report distinguishes parser drift from comparison-basis skew:

  • raced means the source changed while parse-diff was running. It is reported for review but does not fail --fail-on-change.
  • incremental_skew means the stored row was last written by an incremental-append sync, so a fresh full re-parse can legitimately differ on append-path metadata. It is also reported but excluded from --fail-on-change.
  • pending_resync means the stored data version is behind the running binary; the next data-version resync rewrites those rows.

If the report includes incremental_skew, run a full resync before treating the archive as a clean parser-drift baseline. A full resync rewrites those rows through the normalization path and restores strict parse-diff scrutiny.


agentsview import

Import Claude.ai, ChatGPT, or Gemini Apps conversations into the local database. See Chat Import for full documentation.

agentsview import --type <type> <path>
Flag Default Description
--type Import type: claude-ai, chatgpt, or gemini-apps (required)

The path can be a .zip file, a conversations.json file (Claude.ai only), a Gemini Apps MyActivity.html file, or a directory containing the extracted export.

Examples:

agentsview import --type claude-ai ~/Downloads/claude.zip
agentsview import --type chatgpt ~/Downloads/chatgpt.zip
agentsview import --type claude-ai ./conversations.json
agentsview import --type gemini-apps ~/Downloads/takeout.zip

agentsview export sessions

Export content-free session summaries from the local archive. See Session Export for the full JSON/NDJSON contract, cursor semantics, pricing provenance, and project identity rules.

agentsview export sessions [flags]
Flag Default Description
--format json Output format: json or ndjson
--limit 500 Maximum sessions to return; max db.MaxSessionLimit
--cursor Opaque cursor from a previous response
--all false Export every eligible page as one output stream
--project Filter by exact project name
--exclude-project Exclude sessions from the given project
--machine Filter by machine name
--git-branch Filter by project/branch token
--agent Filter by agent name
--date Include sessions active on YYYY-MM-DD
--date-from Include sessions active on or after YYYY-MM-DD
--date-to Include sessions active on or before YYYY-MM-DD
--active-since Include sessions active since an RFC3339 timestamp
--min-messages 0 Minimum total message count
--max-messages 0 Maximum total message count
--min-user-messages 0 Minimum user message count
--include-one-shot false Include one-shot sessions, which are excluded by default
--include-automated false Include automated sessions, which are excluded by default
--include-children false Include subagent/child sessions
--outcome Comma-separated outcome filter
--health-grade Comma-separated health grade filter
--min-tool-failures Minimum tool-failure signal count
--has-secret false Only sessions with detected secret leaks

By default, one-shot and automated sessions are excluded, so token and cost totals can be lower than the full archive unless the corresponding include flags are used.

Examples:

agentsview export sessions --format json
agentsview export sessions --format ndjson --limit 100
agentsview export sessions --all --format ndjson --project agentsview

The JSON top level has schema_version, archive_id, database_id, cursor, pricing, projects, and sessions. NDJSON writes the same metadata as the first line, then one session row per following line. Current builds emit schema_version: 6; see Session Export for the v1 and transitional 0.38 release history. The default and maximum page size is db.MaxSessionLimit, currently 500.

When --cursor is present, only --format, --json, and --limit may be combined with it. Cursor reset errors write structured JSON to stderr, leave stdout empty, and exit with code 4:

{"error":"cursor_reset","message":"session export cursor is no longer valid; restart the export","database_id":"..."}

agentsview export hour|day|digest

Export canonical UTC-hour activity and usage documents, coherent UTC-day snapshots, or compact date-range digests from the local archive. See Reporting Export for the v3 wire schema, quiet-hour semantics, snapshot guarantee, and digest rules.

agentsview export hour 2026-07-28-13
agentsview export day 2026-07-28
agentsview export digest --from 2026-06-28 --to 2026-07-27

Hour and date keys must be exact, zero-padded UTC values. Open and future hours are rejected. The current UTC date contains only closed hours and has no day digest. Digest ranges are inclusive and limited to 31 dates. Integrations should validate the emitted schema_version: 3 and content digest before accepting a document. Version 3 is the default and the only accepted --schema-version; versions 1 and 2 are no longer emitted. Update consumers and refresh stored digests when upgrading.


agentsview session

Programmatic access to session data for scripts, automation agents, and CI jobs. See Session API for full documentation, including stability guarantees, transport auto-detection, and every subcommand.

agentsview session get <id>              # metadata + signals
agentsview session list [flags]          # filtered list
agentsview session list --resume         # recently-active resume table
agentsview session messages <id>         # paginated messages
agentsview session tool-calls <id>       # flat tool-call list
agentsview session export <id>           # stream raw source file
agentsview session sync <path-or-id>     # parse + insert
agentsview session watch <id>            # NDJSON event stream
agentsview session search <pattern>      # content search across sessions
agentsview session usage <id>            # token usage and cost estimate
agentsview session usage <id> --own-only # exclude subagent transcripts

session usage attributes each subagent transcript's spend to the session that spawned it, so a parent that delegated most of its work still reports the full cost. --own-only restores the older own-session output.

session search supports substring (default), --regex, --fts, --semantic, and --hybrid modes. Repeatable --exclude-session <id> drops matches from those sessions before --limit. Semantic and hybrid results can be scoped with --scope top|all|subordinate (default all) to include or exclude sidechain and subagent content — see Semantic Search. The human-readable table includes an AGE column derived from each match's timestamp, so recent evidence is visible without opening the session. Matches without a usable timestamp show —.

Structured response commands accept --format json; --json is a short alias for that scripting mode. session export and session watch are the exceptions: they stream raw bytes and NDJSON respectively, so they reject --format/--json. Use --server <url> to target an explicit running daemon, AGENTSVIEW_SERVER_TOKEN or --server-token-file <path> when that daemon requires auth, or --pg to read from configured PostgreSQL.

agentsview session list excludes one-shot and automated sessions by default. When that hides matching sessions on the first page, it reports the counts and the corresponding --include-one-shot or --include-automated flags on stderr. Stdout, including --format json, keeps its existing shape for pipelines.

AGENTSVIEW_PG_URL, a legacy [pg].url, or the effective default target from default_pg plus [pg.NAME] are sync configuration only; they do not change the default read path. Read commands use local SQLite unless --pg is supplied, in which case they fail fast if no connection URL is available. Mutating commands such as session sync and local-only raw source export continue to use the local archive.

Use agentsview health for a human-first signal view and Session API for the full programmatic contract, including daemon-first transport behavior and markdown export details.

agentsview session list renders a resume-oriented human table by default, including a recently-active marker, session ID, age, agent, project, branch, message count, title, and working directory. Pass --resume or its --active alias to show sessions active in the last 15 minutes; combine either flag with --active-since <RFC3339> to choose a wider or narrower window.


agentsview embeddings

Manage the local semantic search embedding index. Requires [vector] to be enabled in config. See Semantic Search for full documentation, including configuration and the search surface.

agentsview embeddings build           # build or refresh the index
agentsview embeddings list            # list embedding generations
agentsview embeddings activate <id>   # activate a generation
agentsview embeddings retire <id>     # retire a generation

agentsview recall

Inspect the experimental durable-knowledge layer over the local session archive. Recall is active research and its corpus may require rebuilding as the schema, scoring, and trust policy evolve. See Recall (Experimental) for its current guarantees and limitations.

agentsview recall list
agentsview recall get <id>
agentsview recall query <text>
agentsview recall brief <task>
agentsview recall stats
agentsview recall extract run [--session <id>] [--full] [--limit <n>]
agentsview recall extract status
agentsview recall extract activate
agentsview recall extract retire <fingerprint> [--force]
agentsview recall extract doctor
agentsview recall extract preview --session <id>
agentsview recall import <accepted-recall.jsonl> --dry-run

Model-backed extraction requires an enabled [recall.extract] config section — see Recall. preview replaces the earlier extract --session <id> --dry-run form, which still works as a fallback. The extraction subcommands operate on the local archive only and refuse --server; while a daemon owns the archive, it runs extraction passes itself and manual run/activate/retire are refused.

Use an isolated AGENTSVIEW_DATA_DIR for Recall population experiments. Import with --dry-run first; a write requires --yes, and a remote write also requires --allow-remote-import. Import against the default production directory is refused unless --allow-production-import is supplied explicitly. These flags do not bypass Recall's trust or evidence checks.

When --server <url> targets an explicit daemon, provide remote credentials with AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>. Recall never sends the local daemon token from config.toml to an explicitly supplied server.


agentsview mcp

Run a read-only Model Context Protocol server for assistant clients that can call MCP tools. The server exposes session search, listing, overview, message retrieval, content search, and usage-summary tools over the same service layer used by the CLI and HTTP API. See MCP Server for setup examples and operational guidance.

agentsview mcp
agentsview mcp --http 127.0.0.1:8085
agentsview mcp --server http://127.0.0.1:8080

By default, agentsview mcp speaks stdio, which is the expected transport for local MCP clients such as Claude Desktop, Claude Code, and Codex. --http <addr> serves StreamableHTTP instead. Bare ports and :PORT values bind to 127.0.0.1; non-loopback binds require --http-allow-insecure plus a configured bearer token.

Local MCP mode is daemon-backed. Each tool call resolves the local AgentsView daemon and starts it when needed, so a long-lived MCP server can keep working after the daemon exits due to idleness. The MCP server does not fall back to opening the local SQLite archive directly.

Use --server <url> to point at an explicit running daemon. When the daemon requires auth, provide AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>. Use --pg to read from configured PostgreSQL directly, or run agentsview pg serve and pass its URL with --server.

Flag Default Description
--http <addr> Serve StreamableHTTP instead of stdio
--http-allow-insecure false Allow non-loopback HTTP binds; requires bearer auth
--server <url> Explicit daemon URL for MCP tool calls
--server-token-file <path> Bearer token file for an explicit daemon URL
--pg false Read from configured PostgreSQL

agentsview secrets

Scan for and list detected secret leaks across sessions, with matches redacted by default. See Secret Scanning for the full detector set, storage shape, and HTTP API.

agentsview secrets scan [flags]   # scan sessions for leaks
agentsview secrets list [flags]   # list stored findings

secrets scan walks the archive, applies the full ruleset (definite + candidate tiers), and writes new findings to the secret_findings table. Pass --backfill to scan only sessions that haven't yet been scanned at the current ruleset version — the inline scan that runs during sync only stamps definite-tier findings, so --backfill is how you pick up the heuristic candidates without re-scanning the whole archive.

secrets list returns redacted findings by default. Pass --reveal to print the raw values — this only works against a localhost-bound daemon and emits a warning to stderr.

Flag Used by Description
--format both human or json (inherited from secrets)
--json both Alias for --format json (inherited from secrets)
--backfill scan Scan only sessions not yet scanned at the current ruleset version
--project both Limit to a project
--agent both Limit to an agent
--date-from both Sessions on or after YYYY-MM-DD
--date-to both Sessions on or before YYYY-MM-DD
--rule list Filter by rule name (e.g. aws-access-key)
--confidence list definite, candidate, or all (default definite)
--reveal list Show unredacted values (localhost-only)
--limit list Max findings (default 50, max 500)
--cursor list Pagination cursor from a previous response

agentsview skills

Install or list the bundled skill files that teach coding-agent harnesses (Claude Code, Codex, and other .agents/skills readers) to search AgentsView history. See Semantic Search for what the skill does and when to re-run it.

agentsview skills install [--harness claude|agents] [--project] [--force]
    [--server URL] [--server-token-file PATH]
agentsview skills list [--project] [--format json]
    [--server URL] [--server-token-file PATH]

install renders the embedded agentsview-finding-history skill for each --harness (default both) and writes SKILL.md under ~/.claude/skills/agentsview-finding-history/ and/or ~/.agents/skills/agentsview-finding-history/, or under .claude/skills/ / .agents/skills/ at the current git root with --project. It overwrites an unmodified generated file, refuses a hand-edited or foreign file unless --force is passed, and exits non-zero on any refusal. list reports HARNESS, LEVEL, STATE (missing, current, stale, modified, foreign), and PATH for every harness.

--server / --server-token-file (or AGENTSVIEW_SKILLS_SERVER / AGENTSVIEW_SKILLS_SERVER_TOKEN_FILE) bake those flags into every example command so a remote-daemon install does not teach the local SQLite default. Values are shell-quoted, so a token path with a space stays one argument.

Precedence is explicit flags, then whatever the installed file already bakes, then the environment. An installed file therefore decides even when it bakes no remote, so exporting AGENTSVIEW_SKILLS_SERVER never marks existing skills stale in list; the variables only seed a file that is not installed yet. Pass --server "" to un-bake a remote and go back to a local-SQLite skill.

These variables are skills-only and named apart from AGENTSVIEW_SERVER_TOKEN on purpose: they do not change the CLI's default read path, and session search still needs --server unless the baked examples supply it.


agentsview help

Print usage information.

agentsview help

Environment Variables

Variable Default Description
AIDER_DIR unset Aider discovery root; set this to opt into scanning a code root
AMP_DIR ~/.local/share/amp/threads Deprecated; historical local Amp thread JSON files only
ANTIGRAVITY_DIR ~/.gemini/antigravity Google Antigravity IDE sessions directory
ANTIGRAVITY_CLI_DIR ~/.gemini/antigravity-cli Google Antigravity CLI sessions directory
ANTIGRAVITY_KEY Optional key for decrypting Antigravity CLI .pb transcripts (defaults to summary mode without it)
CLAUDE_PROJECTS_DIR ~/.claude/projects Claude Code projects directory
CLAUDE_CONFIG_DIR unset Claude Code config home that re-roots the default projects/ discovery path
OPENCLAUDE_PROJECTS_DIR ~/.openclaude/projects OpenClaude projects directory
OPENCLAUDE_CONFIG_DIR unset OpenClaude config home that re-roots the default projects/ discovery path
COWORK_DIR (platform-specific) Claude Desktop cowork sessions directory
CODEX_SESSIONS_DIR ~/.codex/sessions Codex sessions directory
CODEX_HOME unset Codex home that re-roots the default sessions/ and archived_sessions/ discovery paths
COMMANDCODE_PROJECTS_DIR ~/.commandcode/projects Command Code projects directory
COPILOT_DIR ~/.copilot Copilot CLI sessions directory
CORTEX_DIR ~/.snowflake/cortex/conversations Cortex Code conversations directory
CURSOR_PROJECTS_DIR ~/.cursor/projects Cursor transcripts directory
DEEPSEEK_TUI_SESSIONS_DIR ~/.codewhale/sessions and ~/.deepseek/sessions DeepSeek TUI sessions directory
DEEPSEEK_HARNESS_SESSIONS_DIR ~/.dsh/sessions DeepSeek Harness sessions directory
DSH_HOME unset DeepSeek Harness home that re-roots the default sessions/ discovery path
FORGE_DIR ~/.forge Forge directory (contains .forge.db)
GEMINI_DIR ~/.gemini Gemini CLI directory
GOOSE_PATH_ROOT (platform-specific) Goose path root; sessions are read from <root>/data/sessions/sessions.db
GPTME_DIR ~/.local/share/gptme/logs gptme logs directory
GROK_DIR ~/.grok/sessions Grok sessions directory
HERMES_SESSIONS_DIR ~/.hermes/sessions Hermes Agent sessions directory
IFLOW_DIR ~/.iflow/projects iFlow projects directory
KILO_DIR ~/.local/share/kilo Kilo data directory
KILO_LEGACY_DIR (platform-specific) Kilo legacy VS Code extension data directory
KIMI_DIR ~/.kimi/sessions and ~/.kimi-code/sessions Kimi sessions directory
KIMI_WORK_DIR (platform-specific) Kimi Work (kimi-desktop daimon) sessions directory
KIRO_SESSIONS_DIR ~/.kiro/sessions/cli and ~/.local/share/kiro-cli Kiro CLI sessions directory (JSONL and SQLite)
KIRO_IDE_DIR (platform-specific) Kiro IDE sessions directory
MIMOCODE_DIR ~/.local/share/mimocode MiMoCode data directory
VIBE_SESSIONS_DIR ~/.vibe/logs/session Mistral Vibe sessions directory
OMP_DIR ~/.omp/agent/sessions OhMyPi sessions directory
OPENCLAW_DIR ~/.openclaw/agents and ~/.kimi_openclaw/agents OpenClaw agents directory
OPENCODE_DIR ~/.local/share/opencode OpenCode data directory
OPENCODEREVIEW_DIR ~/.opencodereview/sessions Open Code Review sessions directory
OPENHANDS_CONVERSATIONS_DIR ~/.openhands/conversations OpenHands CLI conversations directory
PI_DIR ~/.pi/agent/sessions Pi sessions directory
PI_CODING_AGENT_DIR unset Pi agent home that re-roots the default sessions/ discovery path
PI_CODING_AGENT_SESSION_DIR unset Pi session directory override; PI_DIR takes precedence
PRIME_AGENT_SESSION_DIR ~/.prime/agent/sessions Prime Agent sessions directory
PIEBALD_DIR ~/.local/share/piebald Piebald directory (contains app.db)
POOLSIDE_DIR (platform-specific) Poolside Agent CLI trajectory directory
POSIT_ASSISTANT_DIR ~/.posit/assistant/workspaces Posit Assistant workspaces directory
POSITRON_DIR (platform-specific) Positron Assistant user directory
QCLAW_DIR ~/.qclaw/agents QClaw agents directory
QODER_PROJECTS_DIR Legacy and platform-specific roots Qoder projects directory; see Session Discovery
QWEN_PROJECTS_DIR ~/.qwen/projects Qwen Code projects directory
QWENPAW_DIR ~/.copaw/workspaces QwenPaw workspaces directory
REASONIX_DIR ~/.reasonix and ~/AppData/Roaming/reasonix Reasonix data directory
ROOCODE_DIR (platform-specific) RooCode VS Code extension data directory
SHELLEY_DIR ~/.config/shelley Shelley data directory
TRAE_DIR (platform-specific) Trae editor user-data directory
VISUALSTUDIO_COPILOT_DIR (platform-specific) Visual Studio Copilot traces directory
VSCODE_COPILOT_DIR (platform-specific) VS Code Copilot sessions directory
WINDSURF_DIR (platform-specific) Windsurf user-data directory
WARP_DIR (platform-specific) Warp database directory
WORKBUDDY_PROJECTS_DIR ~/.workbuddy/projects WorkBuddy projects directory
ZCODE_DIR ~/.zcode/cli/db and ~/.zcode/cli ZCode data directory (contains db.sqlite)
ZED_DIR (platform-specific) Zed data directory (contains threads/threads.db)
ZENCODER_DIR ~/.zencoder/sessions Zencoder sessions directory
AGENTSVIEW_DATA_DIR ~/.agentsview Data directory (database, config)
AGENTSVIEW_AUTH_TOKEN Bearer token for require_auth; overrides auth_token in config.toml
AGENTSVIEW_SKILLS_SERVER Remote daemon URL baked into skills install examples; not a default for session commands
AGENTSVIEW_SKILLS_SERVER_TOKEN_FILE Token file path baked into skills install examples with AGENTSVIEW_SKILLS_SERVER
AGENTSVIEW_PG_URL PostgreSQL connection URL
AGENTSVIEW_PG_MACHINE Machine name for PG push sync
AGENTSVIEW_PG_SCHEMA agentsview PostgreSQL schema name
AGENTSVIEW_DUCKDB_PATH ~/.agentsview/sessions.duckdb DuckDB mirror file path
AGENTSVIEW_DUCKDB_URL Remote Quack endpoint URL for duckdb status and duckdb serve (read side only)
AGENTSVIEW_DUCKDB_TOKEN Quack authentication token
AGENTSVIEW_DUCKDB_MACHINE Machine name for DuckDB push
AGENTSVIEW_GITHUB_TOKEN GitHub token used for local Gist publishing fallback and agentsview stats PR aggregation
AGENTSVIEW_DISABLE_UPDATE_CHECK Set to 1 to disable the update check
AGENTSVIEW_ARCHIVE_CONTENT full Archive storage policy when config.toml sets none: full, transcripts, or usage
AGENTSVIEW_NO_DAEMON Set to 1, true, yes, or on to disable CLI daemon auto-start
AGENTSVIEW_DAEMON_IDLE_TIMEOUT 20m Override idle self-shutdown duration for detached background daemons
AGENTSVIEW_TELEMETRY_ENABLED Set to 0 to disable anonymous daemon telemetry

Environment variables override the built-in defaults. Set them in your shell profile or pass them inline:

AGENTSVIEW_DATA_DIR=/tmp/av-test agentsview serve

Ingest-time image offload

Set tool_result_images = "offload" to offload supported tool-result images on future ingestion. Run agentsview db migrate --images to retry retained inline images after an asset-write failure. The raw agentsview session export command continues to stream provider source bytes. See image storage for backup and remote-backend limits.