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 agent types:

Agent	Default Directory	File Format
Claude Code	~/.claude/projects/	JSONL per session
Codex	~/.codex/sessions/	JSONL per session
Copilot CLI	~/.copilot/session-state/	JSONL per session
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
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
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/	JSONL per session
Kiro IDE	(platform-specific, see below)	JSON / chat files
Forge	~/.forge/	SQLite database (.forge.db)

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/

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 PI_DIR=~/custom/pi
export IFLOW_DIR=~/custom/iflow
export ZENCODER_DIR=~/custom/zencoder
export KIMI_DIR=~/custom/kimi
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

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, pi_dirs, iflow_dirs, zencoder_dirs, kimi_dirs, warp_dirs, hermes_sessions_dirs, cortex_dirs, kiro_dirs, kiro_ide_dirs, and forge_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.

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.