Deploy agent-session-analytics to speck-vm with Tailscale

[evansenter]

Summary

Set up agent-session-analytics on speck-vm for multi-machine access, mirroring the agent-event-bus deployment pattern.

Tasks

Makefile targets (mirror agent-event-bus)

• Add install-server target (service + dependencies + MCP config)
• Add install-client target (CLI + MCP config with REMOTE_URL param)
• Add backwards-compatible install: install-server alias

Remote ingestion (push-based)

Session JSONL files live on each machine locally. Clients need to push their data to the central server.

New MCP tool:

• upload_session(session_id, entries: list[dict]) - accepts parsed entries, writes to DB
• Batch support for large sessions (chunk if needed)
• Deduplication via existing UUID logic

New CLI command:

• agent-session-analytics-cli push [--days N] - reads local JSONL, calls remote MCP
• Uses AGENT_SESSION_ANALYTICS_URL env var for server URL
• Progress output for large uploads

Hook integration:

• Update SessionStart:compact hook to call push after compaction events
• Or: periodic sync via cron/launchd

Documentation

• Create docs/TAILSCALE_SETUP.md (adapt from agent-event-bus)
• Document push-based ingestion workflow

Deployment

• Clone repo on speck-vm
• Run make install-server
• Transfer database from local (~245MB)
• Set up tailscale serve --bg 8081
• Run make install-client REMOTE_URL=https://speck-vm.tailac7b3c.ts.net/mcp on laptop

Design Notes

Why push-based?

• ingest_logs() reads from ~/.claude/projects/*.jsonl which are local to each machine
• Can't have server read client files without file sync infrastructure
• Push over MCP HTTP uses existing auth (Tailscale) and transport

Flow

[Client Machine]                    [Server (speck-vm)]
~/.claude/projects/*.jsonl  --->    upload_session() MCP tool
        |                                   |
   CLI reads local files              Writes to SQLite
   Parses entries                     Dedupes by UUID
   Calls remote MCP                   Updates session stats

Reference

• agent-event-bus TAILSCALE_SETUP.md: https://github.com/evansenter/agent-event-bus/blob/main/docs/TAILSCALE_SETUP.md
• PR feat: Add Tailscale authentication middleware #90: Tailscale auth middleware already added

[evansenter]

Completed

All tasks from this issue have been implemented:

PRs Merged

• feat: Add install-server and install-client Makefile targets #94 - Makefile install-server and install-client targets
• chore: Remove install alias #95 - Remove install alias
• feat: Add upload_entries MCP tool and push CLI command #96 - upload_entries, get_sync_status, CLI push command
• perf: Skip session stats update during batch upload #97 - Performance fix (skip stats during batch upload)
• feat: Store raw JSONL entries for future re-parsing #98 - Raw entries storage for future re-parsing

Deployment

• Server running on speck-vm via tailscale serve
• 215K entries synced (214K raw entries stored)
• 381 sessions across all projects

Documentation

• docs/TAILSCALE_SETUP.md - Complete deployment guide
• docs/SCHEMA.md - Updated with raw_entries table
• guide.md - Remote sync tools documented

Usage

# Set remote URL
export AGENT_SESSION_ANALYTICS_URL=https://speck-vm.tailac7b3c.ts.net/agent-session-analytics/mcp

# Push local data (incremental)
agent-session-analytics-cli push --days 365

# Force re-send all (repopulates raw_entries)
agent-session-analytics-cli push --days 365 --force