Local Agent Viewer

Your local long-term memory for AI agent interactions.
Every interaction you have with Claude Code, Codex CLI, Claude Desktop, and ChatGPT — parsed, classified, searchable, and visualized. Across all your machines.

Want to build your own AI agent?

If LocalAgentViewer sparked your curiosity about AI agents, you might want to go deeper.

AI, MAX Academy offers practical AI training born from 200+ real-world workshops with 2000+ professionals. One of the flagship courses is:

Your AI assistant. On your computer.

A hands-on course that walks you through building a personal AI assistant that works on your own files, knows your work, and stays where it belongs — with you. No cloud dependency, no black boxes. You learn how to think with AI, not just how to click buttons.

The course is currently in Italian, but an English version is on the way. First lesson is free.

The problem

You talk to AI agents every day. You solve bugs, design systems, refactor codebases, debug deployments. But those interactions vanish into scattered JSONL files buried in ~/.claude/, ~/.codex/, and platform-specific directories. No search. No analytics. No memory.

What if you could remember everything?

What LAV does

LocalAgentViewer turns your AI agent logs into a persistent, searchable knowledge base — entirely on your machine.

• Parse raw JSONL/JSON logs from multiple agents into a single SQLite database
• Classify interactions with AI (topics, sensitivity, people, clients, tags)
• Search by keyword (FTS5) or by meaning (Qdrant vector search)
• Visualize tokens, costs, tools, files, and activity patterns in a real-time dashboard
• Distribute across machines — each device parses locally, a central collector unifies everything

No cloud. No accounts. No external dependencies. Just pip install and go.

Supported Agents

Screenshots

Installation

1. Clone and install

git clone https://github.com/maxturazzini/local-agent-viewer.git
cd local-agent-viewer
pip install -e .

This installs the core package (zero external dependencies — stdlib only). All CLI commands become available immediately.

2. (Optional) Install extras

pip install -e ".[classifiers]"   # AI classification (openai)
pip install -e ".[qdrant]"        # Semantic search (qdrant-client, openai, anthropic)
pip install -e ".[mcp]"           # MCP server (fastmcp)
pip install -e ".[all]"           # Everything

3. (Optional) Configure environment

Copy the example and fill in what you need:

cp .env.example .env

# Only needed for optional features — core works without any of these
OPENAI_API_KEY=sk-...            # AI classification (lav-classify) + embeddings (lav-index)
ANTHROPIC_API_KEY=sk-ant-...     # Qdrant KB auto-tagging via Haiku
QDRANT_URL=http://localhost:6333 # Remote Qdrant server (omit for local file storage)
CHATGPT_EXPORT_PATH=             # Path to ChatGPT conversations.json

# Auth for CLI (lav) and MCP server (lav-mcp)
# LAV_API_KEY=your-secret-key        # Required for write operations (sync, kb index, pricing add)
# LAV_READ_API_KEY=your-read-key     # Optional — if set, read operations require this key

# Classification config (optional — defaults work with OpenAI)
# LAV_CLASSIFY_MODEL=gpt-4.1-mini
# LAV_CLASSIFY_BASE_URL=http://localhost:11434/v1  # Ollama, vLLM, Azure, etc.
# LAV_CLASSIFY_SYSTEM_PROMPT=/path/to/prompt.txt   # or inline text

Quick Start

# Parse interactions from this machine
lav-parse

# Start the server
lav-server

Open http://localhost:8764 — that's it.

The database is created automatically at ~/.local/share/local-agent-viewer/local_agent_viewer.db. No configuration required for core functionality.

CLI Commands

Unified CLI (lav)

The lav command provides direct access to queries, KB management, sync, and pricing — no server or MCP required.

# Search interactions (SQLite FTS5)
lav search "newsletter pipeline"
lav search "newsletter" --project miniMe --limit 5 --start 2026-03-01

# Show full transcript
lav show <session_id>

# Semantic search (Qdrant KB)
lav kb search "how does the blog publisher work"
lav kb search "debugging MCP" --classification development

# KB management
lav kb status <session_id>
lav kb index <session_id> --tags "blog,newsletter"
lav kb remove <session_id>
lav kb tags <session_id> --set "new,tags"

# Sync & pricing
lav sync
lav sync --scope project --project miniMe --full
lav pricing list
lav pricing add --model gpt-5.4 --input 2.0 --output 8.0 --from-date 2026-04-01

Output formats: JSON (default, for piping/scripting), --format table (human-readable), --format brief (one line per result).

Auth: write operations (sync, kb index/remove/tags, pricing add) require LAV_API_KEY env var. Read operations are open by default, or gated by LAV_READ_API_KEY if set.

Parser options

lav-parse                        # incremental (default, fast)
lav-parse --project myProject    # parse one project only
lav-parse --full                 # force full reparse

lav-parse-chatgpt               # parse ChatGPT export
lav-parse-chatgpt --full        # full reparse

Data Pipeline

Three layers turn raw agent logs into a searchable, classified knowledge base:

JSONL / JSON logs
    │
    ▼
┌─────────────────────────────────────────────────┐
│  1. PARSE → SQLite                              │
│  Raw interactions: sessions, messages, tokens,  │
│  file ops, tool calls, costs, models            │
│  ─ lav-parse / lav-parse-chatgpt                │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│  2. CLASSIFY → interaction_metadata (optional)  │
│  AI classification via gpt-4.1-mini:            │
│  summary, topics, people, clients, sensitivity, │
│  process type, tags                             │
│  ─ lav-classify (or auto after sync)            │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│  3. INDEX → Qdrant vector DB (optional)         │
│  Semantic embeddings for meaning-based search.  │
│  Reuses SQL metadata when available (no extra   │
│  LLM call). Enables KB search in dashboard.     │
│  ─ lav-index                                    │
└─────────────────────────────────────────────────┘

Each layer is independent — the core works with just layer 1. Classification adds structured metadata. Qdrant adds semantic search on top.

Features

Analytics Dashboard

• Overview — sessions, messages, tokens, costs across time
• Tokens — input/output/cache breakdown by model and day
• Files — most-modified files, operations heatmap
• Tools — tool call frequency and distribution
• Timeline — activity patterns and session duration
• Users — per-user drill-down with 7 views
• Knowledge Base — semantic search across interactions

4D Filtering

Every query supports four independent dimensions:

Search

• Full-text search via SQLite FTS5 — fast, no external dependencies
• Semantic search via Qdrant vector DB (optional, layer 3)
• Classification filters — search by topic, sensitivity, process type (layer 2)

AI Classification (optional)

# Requires OPENAI_API_KEY in .env
lav-classify              # classify unclassified interactions
lav-classify --full       # reclassify everything
lav-classify --dry-run    # preview

Also runs automatically after each sync when OPENAI_API_KEY is set.

Configuration — all optional, set in .env:

The --model CLI flag overrides LAV_CLASSIFY_MODEL for a single run.

Note on small models: The built-in prompt is optimized for small local models (phi4-mini, etc.). Avoid uppercase/NOT-heavy custom prompts — some small models enter degenerate repetition loops. See tests/evals/ for model comparison reports.

MCP Server

Expose your analytics to AI tools via the Model Context Protocol. This lets Claude Code, Claude Desktop, or any MCP-compatible client query your interaction history, search the knowledge base, and trigger syncs — all through natural language.

# Requires: pip install fastmcp
lav-mcp

Available tools:

Claude Code configuration (~/.claude/claude_code_config.json):

{
  "mcpServers": {
    "local-agent-viewer": {
      "command": "lav-mcp",
      "env": {
        "LAV_API_KEY": "your-write-api-key",
        "LAV_READ_API_KEY": "your-read-api-key"
      }
    }
  }
}

Write tools require LAV_API_KEY. Read tools require LAV_READ_API_KEY if set on the server — if not set, read access is open. Both keys are defined in .env and passed to MCP clients via config.

Multi-Machine Setup

Architecture

LocalAgentViewer supports a distributed agent/collector model. Each machine parses its own interactions locally. A central collector pulls from all agents into one unified database.

                  GET /api/export
┌──────────────┐◄──────────────────┌──────────────┐
│  Collector    │   (pull sessions) │  Agent       │
│  role: both   │                   │  role: agent │
│               │                   │              │
│  Dashboard    │                   │  Parse local │
│  Unified DB   │                   │  Local DB    │
│  All APIs     │                   │  Thin API    │
└──────────────┘                   └──────────────┘

Roles

Configuration

Each machine has a local config at ~/.local/share/local-agent-viewer/config.json (not synced via git):

Collector (the machine with the dashboard) — see config.collector.example.json:

{
  "role": "both",
  "port": 8764,
  "agents": [
    {
      "name": "laptop",
      "url": "http://laptop.local:8764",
      "fallback_url": "http://10.0.0.5:8764",
      "timeout_seconds": 10
    }
  ]
}

Agent (each remote machine) — see config.agent.example.json:

{
  "role": "agent",
  "port": 8764,
  "collector_url": "http://collector.local:8764"
}

Data flow

Agent machine (every 15 min via LaunchAgent)
  → lav-parse parses local ~/.claude/projects
  → notify_collector() → POST http://collector:8764/api/sync
  → Collector pulls from agent via GET /api/export
  → Canonical DB updated

Pull is on-demand (triggered by the agent after each parse), not periodic polling.

Setup

On the agent:

mkdir -p ~/.local/share/local-agent-viewer
cp config.agent.example.json ~/.local/share/local-agent-viewer/config.json
# Edit collector_url to point to your collector machine

lav-parse
lav-server  # or install as a service (see below)
curl http://localhost:8764/api/health

On the collector:

mkdir -p ~/.local/share/local-agent-viewer
cp config.collector.example.json ~/.local/share/local-agent-viewer/config.json
# Edit agents list with your remote machines

lav-parse
lav-server
curl -X POST http://localhost:8764/api/sync -H "Content-Type: application/json" -d '{"scope":"all"}'

What lives where

Running as a Service (macOS)

Run the server and parser automatically on login with auto-restart:

# Install services
bash utils/services/install.sh

# Activate
launchctl load ~/Library/LaunchAgents/com.aimax.lav-server.plist
launchctl load ~/Library/LaunchAgents/com.aimax.lav-parser.plist

# Verify
launchctl list | grep com.aimax.lav
curl http://localhost:8764/api/health

The parser LaunchAgent runs incremental parsing every 15 minutes.

After code changes:

bash utils/services/install.sh
launchctl unload ~/Library/LaunchAgents/com.aimax.lav-server.plist
launchctl load ~/Library/LaunchAgents/com.aimax.lav-server.plist

Logs: ~/.local/logs/lav-server.log and lav-server-err.log

API Reference

Universal endpoints (all roles)

Dashboard endpoints (role: both)

Query filters

All dashboard endpoints accept:

?project=myProject&user=john&host=laptop&client=claude_code&start=2026-01-01&end=2026-03-01

Database Schema

Single SQLite database with composite primary keys and 4 independent filter dimensions:

Reference tables: projects, users, hosts, session_sources.

Anti-duplicate on pull: INSERT OR IGNORE on composite PKs ensures idempotent ingestion across machines.

Project Structure

local-agent-viewer/
├── lav/                           # Main package
│   ├── __init__.py
│   ├── cli.py                     # Unified CLI (lav command)
│   ├── config.py                  # Paths, ports, runtime config
│   ├── queries.py                 # SQL queries with 4D filters
│   ├── pricing.py                 # Model pricing management + lav-pricing CLI
│   ├── server.py                  # HTTP server with role-based gating
│   ├── mcp_server.py              # FastMCP server for AI tool integration
│   ├── parsers/
│   │   ├── jsonl.py               # JSONL parser (Claude Code, Codex, Desktop)
│   │   └── chatgpt.py             # ChatGPT export parser
│   ├── classifiers/
│   │   ├── openai_classifier.py   # OpenAI Structured Outputs classifier
│   │   └── sql_classifier.py      # Batch CLI classifier (gpt-4.1-mini)
│   ├── qdrant/
│   │   ├── store.py               # Qdrant vector store client
│   │   ├── indexer.py              # Interaction indexer
│   │   └── kb_indexer.py           # CLI indexer (reuses SQL metadata)
│   └── static/                    # Frontend
│       ├── dashboard.html         # Analytics dashboard (Chart.js)
│       ├── interactions.html      # Interaction browser
│       └── tags.html              # Tag cloud + stats
├── scripts/
│   └── migrate.py                 # Migration from claude-parser
├── tests/
│   └── evals/
│       ├── eval_classify.py       # Classification model eval (multi-model comparison)
│       └── results/               # Eval reports (markdown)
├── config.agent.example.json      # Example config for agent machines
├── config.collector.example.json  # Example config for collector machine
├── pyproject.toml                 # Package config + CLI entry points
├── utils/services/                # LaunchAgent plists + install script
└── docs/
    └── CHANGELOG.md

Requirements

• Python 3.9+ — core functionality uses stdlib only
• Optional: openai for AI classification
• Optional: qdrant-client for semantic search
• Optional: fastmcp for MCP server

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

MIT — Max Turazzini