AgentsView
Local-First Session Intelligence
for AI Coding Agents

What Is AgentsView?

AgentsView is a local-first desktop and web application for browsing, searching, and analyzing AI agent coding sessions. It solves a real problem in the modern AI-assisted development workflow: as coding agents generate ever-larger volumes of session data across projects, finding, reviewing, and learning from that data becomes increasingly difficult.

AgentsView acts as a unified local intelligence layer on top of all your agent session files. It watches directories, parses JSONL (and other format) files from every supported agent, indexes them into a local SQLite database with FTS5 full-text search, and serves a rich Svelte SPA for review and analysis. Nothing leaves your machine.

Key Capabilities at a Glance

Wes McKinney

AgentsView is created and maintained by Wes McKinney — creator of Python pandas, co-creator of Apache Arrow and Ibis, Apache Member, and Principal Architect at Posit. McKinney is a General Partner at Composed Ventures and has a long track record of building high-quality, widely-used open-source infrastructure.

The project supersedes an earlier prototype (archived-agent-session-viewer) and has been actively maintained since early 2026. The GitHub repository has accumulated over 413 stars as of mid-March 2026. It is licensed under the MIT License.

Technical Architecture

AgentsView is built with a clean, minimal-dependency Go backend and a Svelte 5 SPA frontend. The entire application is distributed as a single statically-linked binary (with the frontend embedded) for maximum portability.

Data Pipeline

1. Discovery — on startup, the sync engine traverses all configured session directories for every supported agent type.
2. Parsing — each agent has a dedicated parser that reads JSONL, JSON, SQLite (OpenCode), or plain-text transcripts into a normalized internal format.
3. Ingestion — parsed messages, tool calls, and session metadata are upserted into SQLite tables using 8 parallel workers. File size and mtime comparisons skip unchanged files.
4. Indexing — message content is indexed in an FTS5 virtual table for full-text search.
5. Watching — fsnotify watches all session directories in real time (500ms debounce) and re-ingests changed files immediately.
6. Serving — the HTTP server exposes a REST+SSE API consumed by the embedded Svelte SPA.

Storage Schema

Supported AI Coding Agents

AgentsView auto-discovers session files from twelve agent types with zero manual path configuration required in the default setup.

// ~/.agentsview/config.json — multi-directory for Windows+WSL
{
  "claude_project_dirs": [
    "~/.claude/projects",
    "/mnt/c/Users/you/.claude/projects"
  ],
  "codex_sessions_dirs": [
    "~/.codex/sessions"
  ]
}

Web Interface Deep Dive

Session Browser

The left sidebar provides a virtually-scrolled session list that handles thousands of sessions without performance degradation. Each session entry is color-coded by agent, shows relative timestamps, user prompt count, and supports starring (persisted server-side, not just localStorage).

Sessions can be filtered by: Starred, Recently Active (last 24h), Agent, Min Prompts (2, 3, 5, 10+), and Hide Unknown. Filters sync bidirectionally with the analytics dashboard.

URL-Driven Deep Linking

# Filter by project + agent + date range
http://127.0.0.1:8080/#/sessions?project=myapp&agent=claude&date_from=2025-01-01

# Available parameters
project, agent, date, date_from, date_to,
min_messages, max_messages, min_user_messages,
active_since, exclude_project

Message Viewer

Selecting a session opens a message viewer with three rendering layouts (Default, Compact, Stream) cycleable with l. Messages are color-coded by role (blue = user, purple = assistant). Tool invocations appear as collapsible amber-bordered blocks showing tool name, arguments, and output.

Special Message Types

Keyboard Shortcuts

Analytics Dashboard

The analytics dashboard is the default landing view (no session selected). It provides a comprehensive overview of agent activity scoped by project and date range.

Session Insights

The Insights feature generates AI-powered summaries and analyses of your coding sessions using an AI agent CLI running locally on your machine. Your session data is processed locally — it flows through your agent's API call (Claude, Codex, or Gemini) and the generated markdown is stored in your local SQLite database. AgentsView does not manage or store API keys.

Insight Modes

How Insight Generation Works

1. AgentsView queries your session database for sessions matching the date range and optional project filter (up to 50 sessions).
2. A markdown prompt is built containing session metadata: IDs, projects, agents, timestamps, message counts, and first message previews.
3. The prompt is sent to the selected agent CLI (claude -p, codex exec, or gemini) running locally.
4. The response streams back via SSE, showing progress in the sidebar task list.
5. The completed insight is saved to the database and rendered as markdown in the content panel.

Full-Text Search

The command palette (Cmd+K) is the primary search interface. Queries of 3+ characters trigger FTS5 full-text search across all message content with a 300ms debounce. Results show role badge, matching snippet with highlighted terms, and project name. Selecting a result jumps to the session and scrolls to the matching message.

Session Upload API

Sessions from remote machines or other environments can be uploaded via the REST API:

# Upload a session JSONL file from another machine
curl -F "file=@session.jsonl" \
  "http://127.0.0.1:8080/api/v1/sessions/upload?project=myapp"

Uploaded files are stored in ~/.agentsview/uploads/ and synced into the database.

Installation

Desktop App (Recommended for Non-CLI Users)

Download the .dmg (macOS), .exe (Windows), or .AppImage (Linux) from GitHub Releases. Fully bundled, no dependencies, includes auto-update. Shares the same ~/.agentsview/ data directory as the CLI.

CLI — macOS / Linux

# One-line installer (verifies SHA-256 checksum)
curl -fsSL https://agentsview.io/install.sh | bash

# Verify
agentsview version

CLI — Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://agentsview.io/install.ps1 | iex"

Build from Source

# Requirements: Go 1.25+ with CGO, Node.js 22+
git clone https://github.com/wesm/agentsview.git
cd agentsview
make build
make install  # installs to ~/.local/bin

CLI Commands

agentsview / agentsview serve

Start the HTTP server with embedded web UI. Auto-discovers an available port if 8080 is busy.

agentsview [flags]
agentsview serve [flags]

Startup Sequence

1. Load or create ~/.agentsview/sessions.db
2. Run initial sync across all discovered session directories
3. Start file watcher (500ms debounce)
4. Start periodic sync (every 15 minutes)
5. Serve the Svelte SPA and REST API on the configured host:port

agentsview sync

Run the sync engine to populate the database, then exit. Useful for scripting, CI pipelines, or one-shot data refresh.

agentsview sync          # incremental sync and exit
agentsview sync -full    # full resync and exit

agentsview prune

Delete sessions matching filters. At least one filter required. Filters use AND logic.

# Safe dry-run first — always
agentsview prune -project "scratch" -dry-run

# Delete short sessions from before a date
agentsview prune -max-messages 2 -before 2025-01-01

# Delete sessions starting with "test" (skip confirmation)
agentsview prune -first-message "test" -yes

# Combine multiple filters (AND logic)
agentsview prune \
  -project "old-project" \
  -max-messages 5 \
  -before 2025-06-01

agentsview version / agentsview help

agentsview version   # prints version, git commit, build date
agentsview help      # prints usage

Configuration

Data Directory

~/.agentsview/
├── sessions.db     # SQLite database (WAL mode)
├── config.json     # Configuration file (0600 permissions)
└── uploads/        # Uploaded session files

Override the data directory with AGENT_VIEWER_DATA_DIR:

AGENT_VIEWER_DATA_DIR=/tmp/av-test agentsview

Config File (~/.agentsview/config.json)

{
  "cursor_secret": "base64-encoded-secret",   // auto-generated
  "github_token": "ghp_xxxxx",                // for Gist publishing
  "result_content_blocked_categories": ["Read", "Glob"],
  "remote_access": false,                      // enable remote connections
  "auth_token": "auto-generated-256bit-token",  // bearer token
  "public_url": "https://agents.example.com",
  "public_origins": ["https://agents.example.com"]
}

Environment Variables Reference

Remote Access

By default, agentsview binds to 127.0.0.1 — loopback only. Remote access can be enabled to reach the UI from other devices (phone, tablet, or another machine on your network) while the server and all data remain local.

Quick Enable

// ~/.agentsview/config.json
{ "remote_access": true }

When remote_access is true and no explicit -host is given, the server auto-binds to 0.0.0.0. A 256-bit bearer token is auto-generated and printed on first start.

Direct HTTP (Custom Hostname)

agentsview \
  -host 0.0.0.0 \
  -port 8004 \
  -public-url http://viewer.example.test:8004

HTTPS Behind Your Own Reverse Proxy

agentsview \
  -host 127.0.0.1 \
  -port 8004 \
  -public-url https://viewer.example.test

Managed Caddy Mode (TLS + Subnet ACL)

agentsview \
  -public-url https://agents.example.com \
  -proxy caddy \
  -tls-cert /path/to/cert.pem \
  -tls-key  /path/to/key.pem \
  -proxy-bind-host 0.0.0.0 \
  -allowed-subnet 192.168.1.0/24 \
  -allowed-subnet 10.0.0.0/8

SSE / EventSource Auth

# EventSource API cannot set headers — pass token as query param
http://<host>:8080/watch?token=<your-bearer-token>

Sync Engine

The sync engine is the core of agentsview. It keeps the SQLite database synchronized with session files through two complementary mechanisms:

Change detection uses file size + mtime comparison to skip unchanged files. A pool of 8 workers processes files in parallel during sync. Non-parseable files are cached in skipped_files and skipped on subsequent syncs until mtime changes.

API Endpoints

# Trigger incremental sync
curl -X POST http://127.0.0.1:8080/api/v1/sync

# Trigger full resync (non-destructive)
curl http://127.0.0.1:8080/api/trigger-resync

# Check sync status
curl http://127.0.0.1:8080/api/v1/sync/status

Best Practices Guide

Setup & Configuration

• Always run a dry-run before pruning. Use agentsview prune -dry-run to preview affected sessions before any destructive operation.
• Pin your data directory. Set AGENT_VIEWER_DATA_DIR to a stable, backed-up location — especially when running agentsview as a service.
• Configure multi-directory for mixed environments. If you use Claude Code in both WSL and Windows natively, set claude_project_dirs as an array in config.json to capture both.
• Use the desktop app for daily browsing, CLI for automation. The desktop app handles startup and auto-updates. The CLI is better for scripting and server deployments. They share the same database.
• Do a full resync after upgrades. After upgrading agentsview, use the gear icon → Full Resync to ensure all sessions are re-parsed with the new parser versions.

Storage Management

• Prune throwaway sessions regularly. Short sessions (1–2 messages) from interrupted or test interactions add noise. Schedule periodic: agentsview prune -max-messages 2 -before [last-quarter] -yes
• Block result content for noisy categories. result_content_blocked_categories defaults to ["Read", "Glob"] — this significantly reduces database size by not storing file-read outputs, while preserving tool call metadata for analytics.
• Use project filters aggressively. When searching or generating insights, always scope by project first. Cross-project searches on large databases benefit from the project typeahead filter on the dashboard.

Search Effectiveness

• Use FTS5 prefix matching for partial identifiers. Search useCallback* to find all discussions of useCallback variants.
• Quote multi-word technical terms. "database migration" returns exact phrase matches rather than individual word hits.
• Star sessions with novel solutions immediately. The star feature (s) persists server-side. Star any session where an agent produced an unusually good pattern, architecture decision, or debugging approach — before you close the session.
• Use URL filters for recurring queries. Deep-link bookmarks like /#/sessions?agent=claude&min_messages=10&date_from=2025-01-01 make recurring analytical views instant to access.

Insights Generation

• Run daily digests at end of workday. The Daily Activity insight over the current date is the fastest way to summarize what was accomplished. Run it before closing your work session.
• Use Agent Analysis on a monthly cadence. The Agent Analysis mode surfaces workflow pattern changes over time — run it monthly on your most active project to identify optimization opportunities.
• Add specific context to the Prompt field. Generic insights are generic. Provide focused context: "We were migrating from REST to tRPC — what decisions did we make and why?"
• Queue multiple insights simultaneously. The task queue supports concurrent generation — trigger a daily digest and a date-range summary together rather than waiting for each.

Remote Access & Security

• Never expose agentsview to the open internet without authentication. Always use remote_access: true (bearer token) and -allowed-subnet to restrict access to trusted CIDR ranges.
• Use managed Caddy mode for LAN access with TLS. For access from your phone or tablet on the local network, managed Caddy with a self-signed cert is the cleanest setup.
• For Tailscale / VPN setups, set public-url explicitly. Agentsview's DNS-rebinding protection requires knowing the trusted origin — always set -public-url to your Tailscale hostname.
• Rotate the auth token if exposed. Delete auth_token from config.json and restart — a new 256-bit token will be auto-generated.

Anti-Patterns to Avoid

• Don't skip dry-run on prune operations. The prune command operates on AND logic across all filters — a mismatch between intended and actual filter scope can delete valuable sessions permanently.
• Don't run agentsview as root. The config file is written at 0600 (owner-only). Running as root changes the config location and creates permission issues for the actual user's session files.
• Don't set remote_access without also setting a public_url. Without a public_url, host and origin validation falls back to weaker checks — always pair them.
• Don't block the Bash tool category in result_content_blocked_categories. Bash command output is often the most diagnostic content in a session — losing it makes retrospective debugging much harder.

LLM CLI Usage Guide

This section is written for LLMs (Claude Code, Gemini CLI, Codex, etc.) operating in agentic contexts where they may need to install, configure, query, or manage agentsview programmatically via shell. All commands are safe to run non-interactively unless noted.

1. Detect Whether AgentsView Is Running

# Check if server is up
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/api/v1/sync/status
# Returns 200 if running, connection refused if not

# Get version info
agentsview version 2>/dev/null || echo "not installed"

2. Install AgentsView (macOS/Linux)

# Non-interactive install — safe for automated scripts
curl -fsSL https://agentsview.io/install.sh | bash

# Verify binary is on PATH
which agentsview && agentsview version

3. Start Server in Background

# Start server on default port, log to file
nohup agentsview > ~/.agentsview/server.log 2>&1 &
echo "Started agentsview PID $!"

# Start on custom port (useful if 8080 is occupied)
nohup agentsview -port 9090 > ~/.agentsview/server.log 2>&1 &

# Wait for server to be ready (max 10s)
for i in $(seq 1 10); do
  curl -s http://127.0.0.1:8080/api/v1/sync/status >/dev/null 2>&1 && break
  sleep 1
done

4. Run Sync Without Starting Server

# Incremental sync — skips unchanged files (fast)
agentsview sync

# Full resync — re-parses all session files from scratch
agentsview sync -full

# Sync with custom session directories
CLAUDE_PROJECTS_DIR=/path/to/custom agentsview sync

5. Query Session Data via REST API

# List sessions (JSON)
curl -s http://127.0.0.1:8080/api/v1/sessions | jq '.'

# Filter sessions by project
curl -s "http://127.0.0.1:8080/api/v1/sessions?project=myapp" | jq '.'

# Get messages for a specific session ID
curl -s "http://127.0.0.1:8080/api/v1/sessions/<SESSION_ID>/messages" | jq '.'

# Full-text search across all sessions
curl -s "http://127.0.0.1:8080/api/v1/search?q=useCallback" | jq '.'

# Trigger incremental sync via API
curl -s -X POST http://127.0.0.1:8080/api/v1/sync

6. Upload Session Files from Remote or Non-Standard Locations

# Upload a JSONL session file — project param required
curl -F "file=@/path/to/session.jsonl" \
  "http://127.0.0.1:8080/api/v1/sessions/upload?project=my-project"

# Upload all Claude sessions from a non-default path
find /custom/claude/projects -name "*.jsonl" | while read f; do
  curl -s -F "file=@$f" \
    "http://127.0.0.1:8080/api/v1/sessions/upload?project=imported"
done

7. Prune Sessions (Non-Interactive)

# ALWAYS dry-run first, then execute
agentsview prune -max-messages 1 -before 2025-01-01 -dry-run
agentsview prune -max-messages 1 -before 2025-01-01 -yes

# Prune project-scoped junk sessions
agentsview prune \
  -project "scratch" \
  -max-messages 3 \
  -yes

8. Configure Custom Session Directories

# Inline env vars — no config file changes required
CLAUDE_PROJECTS_DIR=/custom/claude/sessions agentsview sync

# Persistent multi-directory config for WSL + Windows
cat > ~/.agentsview/config.json << 'EOF'
{
  "claude_project_dirs": [
    "~/.claude/projects",
    "/mnt/c/Users/YourName/.claude/projects"
  ]
}
EOF
agentsview sync

9. Remote Access Setup (Automated)

# Enable remote access programmatically via config
python3 -c "
import json, pathlib
cfg_path = pathlib.Path.home() / '.agentsview/config.json'
cfg = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
cfg['remote_access'] = True
cfg_path.write_text(json.dumps(cfg, indent=2))
"

# Start with explicit public URL (required for Tailscale/reverse proxy)
agentsview \
  -public-url http://100.x.x.x:8080 \
  -host 0.0.0.0 &

10. Watch for Session Changes (SSE)

# Stream live session updates (bash + curl)
curl -N -H "Accept: text/event-stream" \
  http://127.0.0.1:8080/watch

# With auth token (remote access mode)
curl -N -H "Accept: text/event-stream" \
  "http://<host>:8080/watch?token=<bearer-token>"

11. Trigger Full Resync via API

# Full resync endpoint — streams SSE progress when called with Accept header
curl -s http://127.0.0.1:8080/api/trigger-resync

# Poll sync status until complete
while true; do
  STATUS=$(curl -s http://127.0.0.1:8080/api/v1/sync/status | jq -r '.status')
  echo "Sync status: $STATUS"
  [ "$STATUS" = "idle" ] && break
  sleep 2
done

12. Isolation / Testing Environments

# Use a temp data dir so no production data is affected
AGENT_VIEWER_DATA_DIR=/tmp/av-test \
  CLAUDE_PROJECTS_DIR=/path/to/test/sessions \
  agentsview sync

# Or start a fully isolated server
AGENT_VIEWER_DATA_DIR=/tmp/av-test \
  agentsview -port 18080

Workflow Patterns

Pattern 1: Session-Aware Development Loop

Run agentsview alongside your active development session to create a real-time audit trail and enable instant retrospection.

1. Start agentsview in one terminal / as a background service
2. Open a Claude Code session in your project directory
3. AgentsView detects and indexes the session in real time via fsnotify
4. After each major feature or bug fix, switch to agentsview and review the session — star any particularly good exchanges
5. At end of day, generate a Daily Activity insight to create a persistent summary

Pattern 2: Cross-Agent Benchmarking

Use the Agent Comparison dashboard to evaluate which agents are most effective for different task types.

1. For a given project type (e.g. frontend refactoring), intentionally use multiple agents across similar tasks
2. After 2–3 weeks, open the dashboard → Agent Comparison for that project
3. Compare: session count, average message count, tool usage patterns, velocity metrics, turn cycle time
4. Generate an Agent Analysis insight: "Compare Claude vs Gemini performance on this project over the past month"

Pattern 3: Session Knowledge Base

Use agentsview as a searchable knowledge base for architectural decisions made by or with AI agents.

1. Establish a convention: when an agent produces a good architecture decision, star the session immediately
2. Use URL filters to create bookmark links: /#/sessions?agent=claude&min_messages=5 (starred + substantive sessions)
3. Before starting a new feature, search agentsview for related past sessions: "authentication middleware"
4. Export particularly valuable sessions as HTML for team sharing or GitHub Gist for asynchronous review

Pattern 4: Multi-Machine Setup (Laptop + Dev Box)

Run agentsview on a dev box and access from a laptop using Tailscale.

# On dev box — start with Tailscale IP as public URL
agentsview \
  -host 0.0.0.0 \
  -public-url http://100.x.x.x:8080 \
  -allowed-subnet 100.64.0.0/10  # Tailscale CGNAT range

# Or use managed Caddy for TLS
agentsview \
  -proxy caddy \
  -public-url https://devbox.your-tailnet.ts.net \
  -tls-cert /path/to/cert.pem \
  -tls-key  /path/to/key.pem \
  -allowed-subnet 100.64.0.0/10

Security Model

Local-First by Default

The default binding is 127.0.0.1 — nothing is accessible from outside the machine. No data is sent to any external service. All AI Insights generation flows through your local agent CLI using your existing API subscription — AgentsView never sees your API keys.

Remote Access Security Layers