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"

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
[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 thirteen 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

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.

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

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, iflow_dirs, zencoder_dirs, and kimi_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 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