Configuration

Data Directory

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

~/.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.

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

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"]`)
`remote_access`	Enable remote connections — auto-binds to `0.0.0.0` and requires bearer token auth
`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

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.

Session Discovery

AgentsView auto-discovers session files from eighteen 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 database
Amp	`~/.local/share/amp/threads/`	JSON per thread
VS Code Copilot	(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

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.

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 AMP_DIR=~/custom/amp
export VSCODE_COPILOT_DIR=~/custom/vscode
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

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, amp_dirs, vscode_copilot_dirs, openclaw_dirs, pi_dirs, iflow_dirs, zencoder_dirs, kimi_dirs, warp_dirs, hermes_sessions_dirs, cortex_dirs, kiro_dirs, and kiro_ide_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.

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:

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.
Periodic sync — full directory scan every 15 minutes as a safety net

Change detection uses file size and mtime comparison to skip unchanged files. 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.

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 http://127.0.0.1:8080/api/trigger-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.