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.

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

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 database
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

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)

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

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, 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:

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.

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.