Configuration

Data Directory

AgentsView stores all persistent data under a single directory, defaulting to ~/.agentsview/. Override with the AGENTSVIEW_DATA_DIR environment variable.

Note

AGENT_VIEWER_DATA_DIR is still accepted as a legacy fallback when AGENTSVIEW_DATA_DIR is unset, but new setups should use AGENTSVIEW_DATA_DIR.

~/.agentsview/
├── sessions.db     # SQLite database (WAL mode)
├── config.toml     # Configuration file
└── uploads/        # Uploaded session files

Config File

The config file at ~/.agentsview/config.toml is auto-created on first run. It stores persistent settings that survive restarts.

Note

The config format changed from JSON to TOML. Existing config.json files are automatically migrated to config.toml on first run (the JSON file is renamed to config.json.bak).

cursor_secret = "base64-encoded-secret"
github_token = "ghp_xxxxx"
require_auth = true

Field	Description
cursor_secret	Auto-generated HMAC key for pagination cursor signing
github_token	GitHub personal access token for Gist publishing
result_content_blocked_categories	Tool categories whose result content is not stored (default: ["Read", "Glob"])
require_auth	Require bearer-token authentication for API access
auth_token	Auto-generated 256-bit bearer token for remote access
public_url	Public URL for hostname/proxy access and origin validation
public_origins	Array of additional trusted CORS origins
[proxy]	Managed proxy configuration table — see Remote Access
disable_update_check	Disable the automatic update check (see Privacy)
[pg]	PostgreSQL sync configuration — see PostgreSQL Sync
[automated]	Custom automated-session patterns — see Automated Session Detection
[custom_model_pricing]	Per-model price overrides for usage reports — see Custom Model Pricing

The cursor_secret is generated automatically on first run. The github_token can be set via the web UI Settings page or the API endpoint POST /api/v1/config/github. Remote access fields can be configured via the Settings page or CLI flags — see Remote Access for details.

Note

Older configs may still contain remote_access = true. AgentsView still reads that legacy key for backward compatibility, but new setups should use require_auth = true.

Session Discovery

AgentsView auto-discovers session files from twenty-seven agent types:

Agent	Default Directory	File Format
Claude Code	~/.claude/projects/	JSONL per session
Codex	~/.codex/sessions/ and ~/.codex/archived_sessions/	JSONL per session
Copilot CLI	~/.copilot/	JSONL per session under session-state/
Cursor	~/.cursor/projects/	JSONL or plain-text transcripts
Gemini CLI	~/.gemini/	JSONL in tmp/ subdirectory
OpenCode	~/.local/share/opencode/	SQLite DB or storage/ JSON files
OpenHands CLI	~/.openhands/conversations/	Per-conversation base_state.json + events/*.json
Amp	~/.local/share/amp/threads/	JSON per thread
VS Code Copilot	(platform-specific, see below)	JSON / JSONL per session
Positron Assistant	(platform-specific, see below)	JSON / JSONL per session
OpenClaw	~/.openclaw/agents/	JSONL per session
QClaw	~/.qclaw/agents/	JSONL per session
Pi	~/.pi/agent/sessions/	JSONL per session
iFlow	~/.iflow/projects/	JSONL per session
Zencoder	~/.zencoder/sessions/	JSONL per session
Kimi	~/.kimi/sessions/	JSONL per session
Qwen Code	~/.qwen/projects/	JSONL per session
WorkBuddy	~/.workbuddy/projects/	JSONL per session
Warp	(platform-specific, see below)	SQLite database
Hermes Agent	~/.hermes/sessions/	JSONL / JSON per session
Cortex Code	~/.snowflake/cortex/conversations/	JSON / JSONL per session
Kiro CLI	~/.kiro/sessions/cli/ and ~/.local/share/kiro-cli/	JSONL per session and SQLite database
Kiro IDE	(platform-specific, see below)	JSON / chat files
Forge	~/.forge/	SQLite database (.forge.db)
Piebald	~/.local/share/piebald/	SQLite database (app.db)
Antigravity (IDE)	~/.gemini/antigravity/	SQLite database per session
Antigravity CLI	~/.gemini/antigravity-cli/	SQLite conversations/<uuid>.db, <uuid>.trajectory.json sidecars, or encrypted .pb files plus brain/ and history.jsonl

VS Code Copilot default directories vary by platform:

• macOS: ~/Library/Application Support/Code/User/
• Linux: ~/.config/Code/User/
• Windows: %APPDATA%/Code/User/

Code Insiders and VSCodium variants are also discovered automatically.

Positron Assistant default directory (macOS only):

• macOS: ~/Library/Application Support/Positron/User/

Positron is an IDE built on VS Code, so sessions use the same workspaceStorage/<hash>/chatSessions/ layout as VS Code Copilot. As of v0.20.0, Positron Assistant has a built-in default path only on macOS — on Linux and Windows, set POSITRON_DIR or positron_dirs to point at your Positron user directory (for example, ~/.config/Positron/User on Linux or %APPDATA%\Positron\User on Windows).

OpenHands CLI shallow watch: OpenHands stores each conversation in its own subdirectory, which would consume one recursive file watch per session and can exhaust inotify limits on Linux. AgentsView watches the root ~/.openhands/conversations/ directory non-recursively and relies on the 15-minute periodic sync to pick up changes inside existing conversations. New conversation directories are still detected immediately. The server’s startup log reports how many directories are watched this way:

Watching 74 directories for changes (2 shallow) (76ms)

OpenCode storage backend: As of 0.24.0, AgentsView reads both of OpenCode’s layouts. If a storage/session/ directory exists under the OpenCode root, sessions are parsed from the per-file JSON layout (storage/session, storage/message, storage/part); otherwise the legacy opencode.db SQLite file is used. Detection is automatic and requires no configuration. In storage mode, the file watcher scopes itself to the storage/ subtree rather than the entire OpenCode directory, so unrelated OpenCode state like binaries, logs, and caches no longer trigger sync events. In SQLite mode, it watches the opencode.db parent.

Warp default directories vary by platform:

• macOS: ~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/
• Linux: ~/.local/state/warp-terminal/
• Windows: ~/AppData/Local/warp/Warp/data/

Kiro IDE default directories vary by platform:

• macOS: ~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/
• Linux: ~/.config/Kiro/User/globalStorage/kiro.kiroagent/
• Windows: ~/AppData/Roaming/Kiro/User/globalStorage/kiro.kiroagent/

Antigravity CLI transcript sources: Antigravity CLI has used both SQLite databases and AES-encrypted .pb files. AgentsView reads whichever source is richest, in this order:

1. SQLite trajectory database. Newer Antigravity CLI releases write conversations/<uuid>.db. AgentsView opens the database read-only and parses the trajectory steps directly. If both conversations/<uuid>.db and conversations/<uuid>.pb exist, the SQLite database wins. Change detection also factors in <uuid>.db-wal and <uuid>.db-shm so active sessions resync as SQLite sidecar files move.
2. Decrypted trajectory sidecar. For older encrypted .pb sessions, if a <uuid>.trajectory.json file sits next to the .pb file (under conversations/ or implicit/), AgentsView uses it as the source of truth for messages, tool calls, and tool results. These sidecars are written out-of-process by agy-reader, which performs the decryption; AgentsView reads the resulting plain JSON as untrusted input and needs no ANTIGRAVITY_KEY in this mode.
3. In-process .pb decryption. With no sidecar present, set ANTIGRAVITY_KEY (base64-encoded AES key, 16/24/32 bytes after decoding) before starting AgentsView and it decrypts the .pb payloads itself, mirroring the upstream Python tool antigravity_decryptor.
4. Plaintext summary mode. Otherwise AgentsView reads only history.jsonl and the brain/ summaries — enough to populate session metadata and a high-level transcript.

Install agy-reader when you want high-resolution transcripts for older encrypted .pb sessions:

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

Override any default with an environment variable (single directory):

export CLAUDE_PROJECTS_DIR=~/custom/claude
export CODEX_SESSIONS_DIR=~/custom/codex
export COPILOT_DIR=~/custom/copilot
export CURSOR_PROJECTS_DIR=~/custom/cursor
export GEMINI_DIR=~/custom/gemini
export OPENCODE_DIR=~/custom/opencode
export OPENHANDS_CONVERSATIONS_DIR=~/custom/openhands
export AMP_DIR=~/custom/amp
export VSCODE_COPILOT_DIR=~/custom/vscode
export POSITRON_DIR=~/custom/positron
export OPENCLAW_DIR=~/custom/openclaw
export QCLAW_DIR=~/custom/qclaw
export PI_DIR=~/custom/pi
export IFLOW_DIR=~/custom/iflow
export ZENCODER_DIR=~/custom/zencoder
export KIMI_DIR=~/custom/kimi
export QWEN_PROJECTS_DIR=~/custom/qwen
export WORKBUDDY_PROJECTS_DIR=~/custom/workbuddy
export WARP_DIR=~/custom/warp
export HERMES_SESSIONS_DIR=~/custom/hermes
export CORTEX_DIR=~/custom/cortex
export KIRO_SESSIONS_DIR=~/custom/kiro
export KIRO_IDE_DIR=~/custom/kiro-ide
export FORGE_DIR=~/custom/forge
export PIEBALD_DIR=~/custom/piebald
export ANTIGRAVITY_DIR=~/custom/antigravity
export ANTIGRAVITY_CLI_DIR=~/custom/antigravity-cli

Multiple Directories

To scan more than one directory per agent — for example, when running Windows and WSL side by side — add array fields to ~/.agentsview/config.toml:

claude_project_dirs = [
  "~/.claude/projects",
  "/mnt/c/Users/you/.claude/projects",
]

codex_sessions_dirs = [
  "~/.codex/sessions",
]

The corresponding fields are claude_project_dirs, codex_sessions_dirs, copilot_dirs, cursor_project_dirs, gemini_dirs, opencode_dirs, openhands_dirs, amp_dirs, vscode_copilot_dirs, positron_dirs, openclaw_dirs, qclaw_dirs, pi_dirs, iflow_dirs, zencoder_dirs, kimi_dirs, qwen_project_dirs, workbuddy_project_dirs, warp_dirs, hermes_sessions_dirs, cortex_dirs, kiro_dirs, kiro_ide_dirs, forge_dirs, piebald_dirs, antigravity_dirs, and antigravity_cli_dirs. Each accepts an array of paths. When set, these take precedence over the single-directory environment variable and the default path.

All listed directories are discovered, watched, and synced independently.

Worktree Project Mappings

The parser infers a session’s project from its cwd, which works for standard layouts but not custom worktree conventions like ~/code/{project}.worktrees/feat/<branch>/ — those sessions otherwise group under <branch> rather than {project}. As of 0.29.0, you can register manual path-prefix → project rules from the Worktree Project Mappings section in Settings:

• Mappings are explicit; there is no auto-discovery.
• Each rule applies whenever a session’s cwd falls under the configured prefix, on both new sessions as they sync and (via the Apply button) already-imported sessions.
• Rules are stored in a worktree_project_mappings SQLite table scoped to the host machine, so a mapping created on one machine does not leak into another machine’s view of synced sessions.
• Excluded, trashed, and skipped session files are left alone.

Mappings only mutate the session’s project field; the rest of the session record is preserved through the bulk-resync rebuild-and-copy path.

Automated Session Detection

AgentsView classifies a session as “automated” when it has one or fewer real user messages and its first user message matches the automation classifier. Automated sessions (roborev reviews, title generation, warmup pings, changelog generation, and similar scripted runs) are filtered out of session lists, counts, and analytics by default — the Include automated toggle in the session filter dropdown opts them back in.

A set of built-in patterns covers the roborev family and AgentsView’s own internal prompts. To teach AgentsView about first-message prefixes unique to your own automation, add them to ~/.agentsview/config.toml:

[automated]
prefixes = [
  "You are summarizing a nightly batch run.",
  "INTERNAL-AUTOMATION:",
]

User-configured entries use a case-sensitive HasPrefix check against the session’s first user message. Entries are trimmed, deduplicated, and capped at 1024 characters; prefixes that duplicate a built-in pattern are silently dropped.

Reclassification on config change. AgentsView stores a hash of the active classifier (built-in patterns + your configured prefixes) with the database. On startup, it rechecks stored is_automated values against the active classifier and re-stamps the hash, so edits to [automated] prefixes apply to history immediately — no manual resync required. The same backfill also corrects rows pulled in from PostgreSQL sync or copied from other archives.

Database

The SQLite database uses WAL mode for concurrent reads and includes FTS5 full-text search indexes on message content.

Schema tables:

Table	Purpose
sessions	Session metadata (project, agent, timestamps, file info, user message count)
messages	Message content with role, ordinal, timestamps
tool_calls	Tool invocations with normalized category taxonomy
tool_result_events	Chronological status events for tool calls (e.g. Codex subagent updates)
insights	AI-generated session analysis and summaries
starred_sessions	Server-side star persistence (replaces localStorage)
pinned_messages	Pinned message references with session linkage
stats	Aggregate counts (session_count, message_count)
skipped_files	Cache of non-interactive session files
messages_fts	FTS5 virtual table for full-text search

The database is automatically migrated on startup when the schema changes.

Sync Behavior

AgentsView keeps the database in sync with session files through two mechanisms:

1. File watcher — uses fsnotify to detect file changes in real time (500ms debounce). Common dependency and build folders (node_modules, __pycache__, .git, vendor, dist, etc.) are automatically skipped to reduce noise and overhead.
2. Periodic sync — full directory scan every 15 minutes as a safety net

Change detection uses file size, mtime, inode, and device tracking to validate incremental parses more reliably. A pool of 8 workers processes files in parallel during sync.

Files that fail to parse or contain no interactive content are cached in the skipped_files table and skipped on subsequent syncs until their mtime changes.

Large Watch Trees

The recursive watcher has a hard budget of 8192 directories per process. If a session root is larger than the remaining budget, or if registering watches hits the operating system’s inotify or file-descriptor limit (ENOSPC / EMFILE), as of 0.27.0 AgentsView degrades that root to polling instead of aborting startup. The HTTP listener is now bound before any watches are registered, so the server still comes up cleanly.

Roots that fall back to polling are picked up by:

• the existing 15-minute periodic full sync, plus
• a new 2-minute fallback sync loop that runs whenever any roots are unwatched (it re-syncs all configured roots, not just the unwatched ones)

Startup logs make degradation explicit. Per-root and summary lines look like:

Couldn't watch 12500 directories under /home/me/.claude/projects, will poll every 2m0s
Polling 1 roots every 2m0s for changes

No configuration is required, but on Linux you can still raise the global cap to keep more roots watched in real time:

sudo sysctl fs.inotify.max_user_watches=524288

Manual Sync

Trigger a sync from the API:

curl -X POST http://127.0.0.1:8080/api/v1/sync

Trigger a full resync (re-parses all session files from scratch):

curl -X POST http://127.0.0.1:8080/api/v1/resync

Both endpoints stream progress via Server-Sent Events when accessed from a browser or SSE-capable client.

Check sync status:

curl http://127.0.0.1:8080/api/v1/sync/status

Privacy and Telemetry

AgentsView has no telemetry, analytics, crash reporting, or diagnostics. By default, all session data stays on your local machine in SQLite.

Optional features that send data externally when you enable them:

• PostgreSQL sync (pg push) sends session data to a PostgreSQL database you configure.
• Session Insights sends session content to an AI provider (Claude, Codex, Copilot, or Gemini) to generate summaries.
• Publish to Gist uploads a session to GitHub.

The only automatic outbound requests are update checks:

• CLI and web UI — on startup, the server contacts the GitHub API to check for new releases. No identifying information is sent beyond what a standard GitHub API request includes (IP address, user-agent).
• Desktop app — uses Tauri’s native updater, which checks the GitHub release feed independently.

Disabling Update Checks

Disable the CLI/web UI update check with any of:

Method	Value
Config file	disable_update_check = true in ~/.agentsview/config.toml
Environment variable	AGENTSVIEW_DISABLE_UPDATE_CHECK=1
CLI flag	--no-update-check

The desktop app’s auto-updater is controlled separately via AGENTSVIEW_DESKTOP_AUTOUPDATE=0.