Agentsview Local Agent Analytics

agentsview Local Agent Analytics

Skill by ara.so — AI Agent Skills collection.

agentsview is a local-first tool for browsing, searching, and tracking costs across 20+ AI coding agents including Claude Code, Codex, Cursor, Copilot, and more. Everything runs locally with no accounts or cloud dependencies. Built in Go with SQLite storage, it provides a web UI for session browsing, full-text search, token usage analytics, and cost tracking.

Installation

Quick Install

# macOS / Linux
curl -fsSL https://agentsview.io/install.sh | bash

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

Homebrew (macOS)

brew install --cask agentsview

Docker

docker run --rm -p 127.0.0.1:8080:8080 \
  -v agentsview-data:/data \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -v "$HOME/.codex/sessions:/agents/codex:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  -e CODEX_DIR=/agents/codex \
  ghcr.io/kenn-io/agentsview:latest

From Source

git clone https://github.com/kenn-io/agentsview.git
cd agentsview
go build -o agentsview ./cmd/agentsview
./agentsview serve

Core Commands

Server Management

# Start foreground server (blocks terminal)
agentsview serve

# Start background server
agentsview serve --background

# Check server status
agentsview serve status

# Stop background server
agentsview serve stop

# Serve on specific port
agentsview serve --port 9090

# Enable authentication (required for non-loopback)
agentsview serve --require-auth

Token Usage & Cost Tracking

# Daily cost summary (last 30 days)
agentsview usage daily

# Per-model breakdown
agentsview usage daily --breakdown

# Filter by agent and date range
agentsview usage daily --agent claude --since 2026-04-01 --until 2026-04-30

# All-time summary
agentsview usage daily --all

# JSON output for scripting
agentsview usage daily --all --json

# One-line statusline for shell prompts
agentsview usage statusline

# Per-session usage
agentsview session usage <session-id>
agentsview session usage <session-id> --format json

Session Analytics

# Human-readable stats (last 28 days)
agentsview stats

# JSON output with custom date range
agentsview stats --format json --since 2026-04-01 --until 2026-04-15

# Filter by agent
agentsview stats --agent claude

# Include git metrics (slow, opt-in)
agentsview stats --include-git-outcomes

# Include GitHub PR metrics (requires gh CLI)
agentsview stats --include-github-outcomes

Database Operations

# Sync agent sessions into SQLite
agentsview sync

# Export to DuckDB
agentsview duckdb push --full

# Serve DuckDB mirror read-only
agentsview duckdb serve

# PostgreSQL mode
agentsview pg serve

Configuration

Environment Variables

# Agent session directories (auto-detected by default)
export CLAUDE_PROJECTS_DIR="$HOME/.claude/projects"
export CODEX_DIR="$HOME/.codex/sessions"
export CURSOR_DIR="$HOME/.cursor/sessions"
export FORGE_DIR="$HOME/.forge"
export COPILOT_DIR="$HOME/.copilot"

# Database
export AGENTSVIEW_DATA_DIR="$HOME/.agentsview"
export AGENTSVIEW_PG_URL="postgres://user:pass@host:5432/agentsview?sslmode=require"
export AGENTSVIEW_DUCKDB_URL="quack:https://duckdb.example.com"
export AGENTSVIEW_DUCKDB_TOKEN="your-quack-token"

# Server
export AGENTSVIEW_PORT="8080"
export AGENTSVIEW_PUBLIC_URL="http://127.0.0.1:8080"

Remote Access Setup

For SSH port-forwarding, reverse proxies, or remote dev environments:

# Browser opens http://127.0.0.1:18080 via SSH tunnel
agentsview serve --public-url http://127.0.0.1:18080

# Codespaces, exe.dev, etc.
agentsview serve --public-url https://your-workspace.exe.dev

# Trust additional origins
agentsview serve --public-origin https://dev.example.com,https://staging.example.com

Docker Compose Production Setup

# docker-compose.prod.yaml
version: '3.8'

services:
  agentsview:
    image: ghcr.io/kenn-io/agentsview:latest
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - agentsview-data:/data
      - ~/.claude/projects:/agents/claude:ro
      - ~/.codex/sessions:/agents/codex:ro
      - ~/.cursor/sessions:/agents/cursor:ro
    environment:
      - CLAUDE_PROJECTS_DIR=/agents/claude
      - CODEX_DIR=/agents/codex
      - CURSOR_DIR=/agents/cursor
    restart: unless-stopped

volumes:
  agentsview-data:

Run with:

docker compose -f docker-compose.prod.yaml up -d

REST API

Get Session Usage

# Fetch per-session token and cost data
curl http://127.0.0.1:8080/api/v1/sessions/<session-id>/usage

# Example response
{
  "session_id": "abc123",
  "agent": "claude",
  "project": "my-app",
  "total_output_tokens": 15420,
  "peak_context_tokens": 98765,
  "has_token_data": true,
  "cost_usd": 0.42,
  "has_cost": true,
  "models": ["claude-3.5-sonnet"],
  "unpriced_models": [],
  "server_running": true
}

Settings & Configuration

# Get settings
curl http://127.0.0.1:8080/api/v1/settings

# Search sessions (FTS5)
curl "http://127.0.0.1:8080/api/v1/search?q=refactor+authentication"

Common Patterns

Daily Cost Monitoring in Shell Prompt

Add to .bashrc or .zshrc:

# Show today's AI agent cost in prompt
function agent_cost() {
  agentsview usage statusline 2>/dev/null || echo "agentsview offline"
}

PS1='$(agent_cost) $ '

Automated Daily Reports

#!/bin/bash
# daily-agent-report.sh

DATE=$(date +%Y-%m-%d)
REPORT_FILE="$HOME/reports/agent-usage-$DATE.json"

agentsview usage daily --all --json > "$REPORT_FILE"
agentsview stats --format json >> "$REPORT_FILE"

echo "Report saved to $REPORT_FILE"

CI/CD Cost Tracking

# .github/workflows/agent-costs.yml
name: Track Agent Costs

on:
  schedule:
    - cron: '0 0 * * *' # Daily at midnight

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - name: Install agentsview
        run: curl -fsSL https://agentsview.io/install.sh | bash
      
      - name: Mount agent sessions
        run: |
          mkdir -p ~/.claude/projects
          # Sync from cloud storage or artifact
      
      - name: Generate report
        run: agentsview usage daily --all --breakdown --json > costs.json
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: agent-costs
          path: costs.json

Querying the SQLite Database Directly

# Open the database
sqlite3 ~/.agentsview/sessions.db

# Query recent sessions
SELECT 
  id, 
  agent, 
  project_name,
  started_at,
  message_count
FROM sessions
WHERE started_at > datetime('now', '-7 days')
ORDER BY started_at DESC
LIMIT 10;

# Get token stats by model
SELECT 
  model,
  SUM(total_tokens) as total,
  AVG(total_tokens) as avg_per_session
FROM session_usage
GROUP BY model
ORDER BY total DESC;

Export Sessions Programmatically

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type SessionUsage struct {
    SessionID          string   `json:"session_id"`
    Agent              string   `json:"agent"`
    TotalOutputTokens  int      `json:"total_output_tokens"`
    CostUSD            float64  `json:"cost_usd"`
    HasCost            bool     `json:"has_cost"`
}

func fetchSessionUsage(sessionID string) (*SessionUsage, error) {
    url := fmt.Sprintf("http://127.0.0.1:8080/api/v1/sessions/%s/usage", sessionID)
    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var usage SessionUsage
    if err := json.NewDecoder(resp.Body).Decode(&usage); err != nil {
        return nil, err
    }

    return &usage, nil
}

func main() {
    usage, err := fetchSessionUsage("your-session-id")
    if err != nil {
        panic(err)
    }

    fmt.Printf("Agent: %s\n", usage.Agent)
    fmt.Printf("Tokens: %d\n", usage.TotalOutputTokens)
    if usage.HasCost {
        fmt.Printf("Cost: $%.4f\n", usage.CostUSD)
    }
}

Background Server with Systemd

# ~/.config/systemd/user/agentsview.service
[Unit]
Description=agentsview local agent analytics
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/agentsview serve --port 8080
Restart=on-failure
RestartSec=5s
Environment="AGENTSVIEW_DATA_DIR=%h/.agentsview"

[Install]
WantedBy=default.target

Enable and start:

systemctl --user enable agentsview.service
systemctl --user start agentsview.service
systemctl --user status agentsview.service

Supported Agents & Session Paths

All paths are auto-detected. Override with environment variables if needed.

Troubleshooting

Server Returns 403 Forbidden

Symptom: API requests return 403 Forbidden when accessing through SSH tunnel, reverse proxy, or remote dev environment.

Cause: Host header validation fails when the browser's Host header doesn't match the server's expected origin.

Solution:

# Set public URL to match browser origin
agentsview serve --public-url http://127.0.0.1:18080

# Or trust multiple origins
agentsview serve --public-origin https://dev.example.com,https://codespaces.github.dev

Sessions Not Appearing

Symptom: Agent sessions don't show up in the UI.

Cause: Session directory not mounted (Docker) or not auto-detected.

Solution:

# Verify session directory exists
ls ~/.claude/projects/

# Docker: ensure volume is mounted
docker run -v "$HOME/.claude/projects:/agents/claude:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  ghcr.io/kenn-io/agentsview:latest

# Manual sync
agentsview sync

Cost Data Missing

Symptom: has_cost: false or cost_usd: 0.

Cause: Model pricing not available in LiteLLM database or no token data recorded.

Solution:

# Check if token data exists
agentsview session usage <id> --format json | jq '.has_token_data'

# Update agentsview to latest version
curl -fsSL https://agentsview.io/install.sh | bash

Background Server Not Starting

Symptom: agentsview serve --background fails or exits immediately.

Solution:

# Check logs
cat ~/.agentsview/serve.log

# Verify port not in use
lsof -i :8080

# Try foreground to see errors
agentsview serve

Slow Git Outcome Metrics

Symptom: agentsview stats --include-git-outcomes hangs or takes too long.

Cause: Large repositories or missing git history.

Solution:

# Omit git metrics (default)
agentsview stats

# Or limit date range
agentsview stats --include-git-outcomes --since 2026-06-01

Docker Permission Issues

Symptom: Root-owned files in ~/.agentsview after Docker run.

Solution:

# Use named volume instead of bind mount
docker run -v agentsview-data:/data ghcr.io/kenn-io/agentsview:latest

# Or pre-create with correct ownership
mkdir -p ~/.agentsview
docker run -v "$HOME/.agentsview:/data" ghcr.io/kenn-io/agentsview:latest

Advanced Usage

PostgreSQL Backend

# Set PostgreSQL URL
export AGENTSVIEW_PG_URL="postgres://user:pass@host:5432/agentsview?sslmode=require"

# Start PostgreSQL mode
agentsview pg serve

# Docker
docker run -e PG_SERVE=1 \
  -e AGENTSVIEW_PG_URL="$AGENTSVIEW_PG_URL" \
  ghcr.io/kenn-io/agentsview:latest

DuckDB Mirror

# Export SQLite to DuckDB
agentsview duckdb push --full

# Serve DuckDB read-only
agentsview duckdb serve

# Quack remote access
QUACK_TOKEN="$(openssl rand -base64 32)"
agentsview duckdb quack serve \
  --bind quack:0.0.0.0:9494 \
  --token "$QUACK_TOKEN" \
  --allow-insecure

# Connect to remote Quack
export AGENTSVIEW_DUCKDB_URL="quack:https://duckdb.example.com"
export AGENTSVIEW_DUCKDB_TOKEN="$QUACK_TOKEN"
agentsview duckdb serve

Custom Timezone for Reports

# Use specific timezone for daily bucketing
agentsview usage daily --timezone America/New_York

# Or set environment variable
export TZ=Europe/London
agentsview usage daily

Keyboard Shortcuts (Web UI)

• j / k — Navigate sessions
• [ / ] — Previous/next session
• Cmd+K / Ctrl+K — Open search
• ? — Show all shortcuts
• Esc — Close dialogs/modals

License

MIT