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.json     # Configuration file
└── uploads/        # Uploaded session files

Config File

The config file at ~/.agentsview/config.json 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"])

The cursor_secret is generated automatically on first run. The github_token can be set via the web UI settings or the API endpoint POST /api/v1/config/github.

Session Discovery

agentsview auto-discovers session files from nine 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

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

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.json:

{
  "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, and openclaw_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
insights	AI-generated session analysis and summaries
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)
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