local-agent-viewer: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

LocalAgentViewer (LAV) — local long-term memory for AI agent interactions. Parses JSONL/JSON logs from Claude Code, Codex CLI, Claude Desktop, ChatGPT, and Anthropic claude.ai account exports into a single SQLite database with a web dashboard, AI classification, and optional vector search.

Commands

# Install (zero dependencies for core, extras for optional features)
pip install -e .              # core only
pip install -e ".[all]"       # everything (qdrant, openai, fastmcp)

# Parse & serve
lav-parse                     # incremental parse from local JSONL
lav-parse --project myProject # parse one project
lav-parse --full              # full reparse
lav-parse --since 2026-06-01  # bounded re-read (additive, insert-only; excl. --full)
lav-parse-chatgpt             # parse ChatGPT export
lav-parse-claude-ai           # parse Anthropic claude.ai export folder (data-*-batch-0000)
lav-parse-cowork-remote --list    # cloud session ids Claude Desktop knows (LAV-94)
lav-parse-cowork-remote --fetch   # teleport pending, then stale ones (max 3, idle >30 min), then parse
lav-parse-cowork-remote --id session_01…   # (re-)fetch one session
lav-parse-cowork-remote --refetch-all --max-fetch -1   # manual brute force: re-fetch every fetched session
lav-parse-cowork-remote           # parse only: re-reads cowork-remote/sessions/ (every node)
lav-server                    # start server on :8764

# Unified CLI — query & KB management (zero extra deps)
lav search "query"            # FTS5 full-text search
lav search "query" --project miniMe --limit 5 --format brief
lav show <session_id>         # full interaction transcript
lav kb search "semantic query" # Qdrant vector search
lav kb status <session_id>    # check if indexed
lav kb index <session_id> --tags "tag1,tag2"
lav kb remove <session_id>
lav kb tags <session_id> --set "new,tags"
lav sync                      # trigger sync (needs LAV_API_KEY)
lav sync --scope project --project miniMe
lav pricing list              # list active pricing
lav pricing add --model X --input 5.0 --output 25.0 --from-date 2026-01-01
lav backfill tool-outcomes    # stamp tool_call_id + outcome on historical tool rows
lav backfill tool-kind        # re-derive mcp_tool_calls.kind (--reclassify after a whitelist edit)
lav backfill claude-ai-outcomes  # recover claude.ai is_error from markers in messages (LAV-83)
lav backfill codex-titles     # rebuild Codex display/summary from state_<N>.sqlite (LAV-91)
lav backfill cache-ttl        # 1-hour cache-write split from transcripts (LAV-96; --dump-map / --map for the collector)
lav backfill codex-titles --state-db /tmp/agent_state_5.sqlite  # apply another node's titles

# Entity graph (LAV-93) — local DB only, run on the node that classifies
lav entities build --since 2026-09-14   # mentions from people/clients, involvement found in messages
lav entities import seed.json           # PRIVATE seed: roles, works_for, aliases (never commit it)
lav entities list --kind person --at 2026-09-15   # role at a date, counted once per root session
lav entities pending                    # proposals and mentioned entities with no role
lav entities confirm 42 --valid-from 2025-09-03   # or --reject / --valid-to to close a period

# Specialized CLIs (still available)
lav-classify                  # AI classification (needs OPENAI_API_KEY)
lav-index                     # Qdrant vector indexing
lav-mcp                       # MCP server (needs fastmcp)
lav-pricing list              # list model pricing (standalone)
lav-pricing add --model X ... # add/update pricing entry
lav-pricing seed              # insert default pricing data