Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Session Sync & Management

Overview

The syncThe process of discovering new/changed session files and updating the database engine discovers sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from all configured AI coding agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) directories on disk, parses them using agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific parsers, sanitizes the extracted data, and writes it into the SQLiteEmbedded relational database used as the primary session archive database. It provides incremental and full resync modes, a file watcher for live updates, and supports remote syncSyncing sessions from other machines via SSH or HTTP from other machines via SSHSecure Shell and S3Simple Storage Service (Amazon S3-compatible)-compatible storage.

Stakeholders

Stakeholder	Interest
End user	Sessions are automatically discovered and indexed without manual intervention
Operator	Can trigger resyncs and monitor syncThe process of discovering new/changed session files and updating the database status
Developer	Extensible provider system for adding new agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) parsers

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall discover sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from all configured agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) directories on startup	Must	The system shall discover sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from all configured agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) directories on startup
FR-2MustThe system shall parse sessionA single conversation or interaction with an AI coding agent, typically one run/launch files using agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific parsers to extract messages, tool calls, and usage data	Must	The system shall parse sessionA single conversation or interaction with an AI coding agent, typically one run/launch files using agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific parsers to extract messages, tool calls, and usage data
FR-3MustThe system shall sanitize parsed data (clamp tokens, blank timestamps, coerce roles, strip control characters)	Must	The system shall sanitize parsed data (clamp tokens, blank timestamps, coerce roles, strip control characters)
FR-4MustThe system shall write parsed sessions to SQLiteEmbedded relational database used as the primary session archive in batches of 100 with 8 parallel workers	Must	The system shall write parsed sessions to SQLiteEmbedded relational database used as the primary session archive in batches of 100 with 8 parallel workers
FR-5MustThe system shall support incremental syncThe process of discovering new/changed session files and updating the database (only changed files) and full resync	Must	The system shall support incremental syncThe process of discovering new/changed session files and updating the database (only changed files) and full resync
FR-6MustThe system shall provide a file watcher using fsnotifyGo library for filesystem event notification with configurable debounce	Must	The system shall provide a file watcher using fsnotifyGo library for filesystem event notification with configurable debounce
FR-7MustThe system shall run a periodic full scan every 15 minutes	Must	The system shall run a periodic full scan every 15 minutes
FR-8MustThe system shall track failed/unparseable files by path and mtime via a skip cache	Must	The system shall track failed/unparseable files by path and mtime via a skip cache
FR-9ShouldThe system shall support syncing sessions from remote machines via SSHSecure Shell	Should	The system shall support syncing sessions from remote machines via SSHSecure Shell
FR-10ShouldThe system shall support S3Simple Storage Service (Amazon S3-compatible)-compatible object storage as a sessionA single conversation or interaction with an AI coding agent, typically one run/launch source	Should	The system shall support S3Simple Storage Service (Amazon S3-compatible)-compatible object storage as a sessionA single conversation or interaction with an AI coding agent, typically one run/launch source
FR-11ShouldThe system shall emit SSEServer-Sent Events notifications after each write pass for live UI updates	Should	The system shall emit SSEServer-Sent Events notifications after each write pass for live UI updates
FR-12ShouldThe system shall auto-start the daemon on demand for commands that need fresh data	Should	The system shall auto-start the daemon on demand for commands that need fresh data

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustSync should process at least 100 sessions per second	Must	Performance	Sync should process at least 100 sessions per second
NFR-2MustFailed parses must not crash the syncThe process of discovering new/changed session files and updating the database engine; errors are tracked and skipped	Must	Reliability	Failed parses must not crash the syncThe process of discovering new/changed session files and updating the database engine; errors are tracked and skipped

Acceptance Criteria

FR-1MustThe system shall discover sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from all configured agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) directories on startup
- Given agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) sessionA single conversation or interaction with an AI coding agent, typically one run/launch files exist on disk
- When the server starts
- Then all sessionA single conversation or interaction with an AI coding agent, typically one run/launch files are discovered and queued for parsing
FR-2MustThe system shall parse sessionA single conversation or interaction with an AI coding agent, typically one run/launch files using agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific parsers to extract messages, tool calls, and usage data
- Given a sessionA single conversation or interaction with an AI coding agent, typically one run/launch file for a supported agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)
- When the syncThe process of discovering new/changed session files and updating the database engine processes it
- Then messages, tool calls, and usage data are extracted
FR-5MustThe system shall support incremental syncThe process of discovering new/changed session files and updating the database (only changed files) and full resync
- Given a previously synced sessionA single conversation or interaction with an AI coding agent, typically one run/launch file is modified
- When the file watcher detects the change
- Then only that sessionA single conversation or interaction with an AI coding agent, typically one run/launch is re-parsed and updated
FR-6MustThe system shall provide a file watcher using fsnotifyGo library for filesystem event notification with configurable debounce
- Given the server is running
- When a new sessionA single conversation or interaction with an AI coding agent, typically one run/launch file is created
- Then it is detected and synced within the debounce window

Open Questions

What are the performance characteristics of S3Simple Storage Service (Amazon S3-compatible)-based sessionA single conversation or interaction with an AI coding agent, typically one run/launch discovery at scale?

Specification: Session Sync & Management

Overview

The syncThe process of discovering new/changed session files and updating the database engine (internal/syncThe process of discovering new/changed session files and updating the database/Engine) orchestrates sessionA single conversation or interaction with an AI coding agent, typically one run/launch discovery, parsing, and database writing. Discovery uses provider factories or legacy path resolution. Parsing delegates to per-agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) parsers in internal/parserCode that reads an agent-specific session file format and extracts structured data/. Writing batches sessions and messages into SQLiteEmbedded relational database used as the primary session archive with incremental update support.

Architecture

Agent Files (disk) → Provider Factory / Legacy Resolver
                         ↓
                   Agent-specific Parser
                         ↓
                   Sanitizer
                         ↓
                   Batch Writer → SQLiteEmbedded relational database used as the primary session archive DB
                         ↓
                   SSEServer-Sent Events Emitter → UI Clients

Data Models

ParsedSession

Field	Type	Description
ID	string	Unique sessionA single conversation or interaction with an AI coding agent, typically one run/launch identifier
AgentID	AgentType	Agent that created the sessionA single conversation or interaction with an AI coding agent, typically one run/launch
Project	string	Project name
StartTime	time.Time	Session start timestamp
Messages	[]ParsedMessage	Messages in the sessionA single conversation or interaction with an AI coding agent, typically one run/launch
ToolCalls	[]ParsedToolCall	Tool invocations
UsageEvents	[]ParsedUsageEvent	Token usage data

SkipCacheEntry

Field	Type	Description
Path	string	File path
ModTime	time.Time	Last modification time
Error	string	Parse error description

APIApplication Programming Interface Contracts

POST /api/v1/syncThe process of discovering new/changed session files and updating the database

Request: Empty Response: SSEServer-Sent Events stream of syncThe process of discovering new/changed session files and updating the database progress events

POST /api/v1/resync

Request: Empty Response: SSEServer-Sent Events stream of full resync progress events

GET /api/v1/syncThe process of discovering new/changed session files and updating the database/status

Response: JSON with syncThe process of discovering new/changed session files and updating the database state, last syncThe process of discovering new/changed session files and updating the database time, pending count

Sequences

File Change Detection

fsnotifyGo library for filesystem event notification → Debounce (500ms) → Parse Changed Files → Batch Write → SSEServer-Sent Events Notify

Periodic Scan

Timer (15min) → Discover All Paths → Diff Against Known → Parse New/Changed → Write

Technical Decisions

Decision	Choice	Rationale
Batch size	100 sessions, 8 workers	Balances throughput and memory
Debounce	500ms	Prevents thundering herd on bulk file changes
Skip cache	File path + mtime	Avoids re-parsing unchanged files
Provider factory	Per-agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) pluggable discovery	Supports diverse agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) directory structures

Risks and Unknowns

S3Simple Storage Service (Amazon S3-compatible)-backed discovery latency with many objects
File watcher scalability on directories with thousands of files

Test Plan: Session Sync & Management

Scope

Tests cover sessionA single conversation or interaction with an AI coding agent, typically one run/launch file discovery, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific parsing, sanitization, database writing, incremental and full resync, file watcher, periodic scanning, skip cache, remote syncSyncing sessions from other machines via SSH or HTTP via SSHSecure Shell, S3Simple Storage Service (Amazon S3-compatible)-based discovery, and SSEServer-Sent Events notification.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Engine discovers sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from configured directories	Provider config with sessionA single conversation or interaction with an AI coding agent, typically one run/launch files	All files discovered and queued
TC-2	Parser extracts messages, tool calls, usage from sessionA single conversation or interaction with an AI coding agent, typically one run/launch files	Agent-specific sessionA single conversation or interaction with an AI coding agent, typically one run/launch file	Structured ParsedSession output
TC-3	Sanitizer clamps tokens, blanks timestamps, coerces roles	ParsedSession with edge case values	Sanitized ParsedSession
TC-4	Skip cache tracks failed files by path and mtime	Failed parse result	Entry added to skip cache
TC-5	File watcher detects new/changed files via fsnotifyGo library for filesystem event notification	fsnotifyGo library for filesystem event notification event stream	Changed files dispatched to parserCode that reads an agent-specific session file format and extracts structured data
TC-6	CWDCurrent Working Directory, used for sync path filtering filter correctly scopes syncThe process of discovering new/changed session files and updating the database to working directory	CWDCurrent Working Directory, used for sync path filtering config + sessionA single conversation or interaction with an AI coding agent, typically one run/launch paths	Only matching paths synced
TC-7	Periodic scan discovers new files after startup	File added between scans	File discovered on next scan

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-8	Full syncThe process of discovering new/changed session files and updating the database engine integration with real directory	Session files on disk	Sessions parsed and written to DB
TC-9	Incremental resync updates changed sessions	Previously synced sessionA single conversation or interaction with an AI coding agent, typically one run/launch modified	Session re-parsed and updated
TC-10	Remote syncThe process of discovering new/changed session files and updating the database via SSHSecure Shell	SSHSecure Shell host configured	Remote sessions synced locally
TC-11	S3Simple Storage Service (Amazon S3-compatible)-compatible storage as sessionA single conversation or interaction with an AI coding agent, typically one run/launch source	S3Simple Storage Service (Amazon S3-compatible) bucket configured	Sessions discovered and synced from S3Simple Storage Service (Amazon S3-compatible)

Test Files

internal/syncThe process of discovering new/changed session files and updating the database/engine_test.go - Engine discovery, syncThe process of discovering new/changed session files and updating the database, and lifecycle tests
internal/syncThe process of discovering new/changed session files and updating the database/engine_integration_test.go - Integration tests with real directories
internal/syncThe process of discovering new/changed session files and updating the database/watcher_test.go - File watcher behavior tests
internal/syncThe process of discovering new/changed session files and updating the database/hash_test.go - File hashing for change detection
internal/syncThe process of discovering new/changed session files and updating the database/parsediff_*_test.go - Parse diff comparison tests
internal/syncThe process of discovering new/changed session files and updating the database/s3_test.go - S3Simple Storage Service (Amazon S3-compatible)-based discovery tests
internal/syncThe process of discovering new/changed session files and updating the database/secret_*_test.go - Secret scanning integration during syncThe process of discovering new/changed session files and updating the database
internal/parserCode that reads an agent-specific session file format and extracts structured data/*_test.go - Per-agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) parserCode that reads an agent-specific session file format and extracts structured data tests (50+ agents)
internal/parserCode that reads an agent-specific session file format and extracts structured data/provider_test.go - Provider factory tests
internal/parserCode that reads an agent-specific session file format and extracts structured data/discovery_test.go - Discovery path resolution tests
internal/syncThe process of discovering new/changed session files and updating the database/provider_process_test.go - Provider processing lifecycle
internal/syncThe process of discovering new/changed session files and updating the database/cwd_filter_test.go - CWDCurrent Working Directory, used for sync path filtering filter tests

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-12	Malformed sessionA single conversation or interaction with an AI coding agent, typically one run/launch file	Parsing error tracked, syncThe process of discovering new/changed session files and updating the database continues
TC-13	File removed during syncThe process of discovering new/changed session files and updating the database	Graceful skip, no crash
TC-14	Directory with thousands of files	File watcher handles volume

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall discover sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from all configured agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) directories on startup	TC-1, TC-8
FR-2MustThe system shall parse sessionA single conversation or interaction with an AI coding agent, typically one run/launch files using agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific parsers to extract messages, tool calls, and usage data	TC-2
FR-3MustThe system shall sanitize parsed data (clamp tokens, blank timestamps, coerce roles, strip control characters)	TC-3
FR-4MustThe system shall write parsed sessions to SQLiteEmbedded relational database used as the primary session archive in batches of 100 with 8 parallel workers	TC-8
FR-5MustThe system shall support incremental syncThe process of discovering new/changed session files and updating the database (only changed files) and full resync	TC-9
FR-6MustThe system shall provide a file watcher using fsnotifyGo library for filesystem event notification with configurable debounce	TC-5
FR-7MustThe system shall run a periodic full scan every 15 minutes	TC-7
FR-8MustThe system shall track failed/unparseable files by path and mtime via a skip cache	TC-4
FR-9ShouldThe system shall support syncing sessions from remote machines via SSHSecure Shell	TC-10
FR-10ShouldThe system shall support S3Simple Storage Service (Amazon S3-compatible)-compatible object storage as a sessionA single conversation or interaction with an AI coding agent, typically one run/launch source	TC-11

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Recall System

Overview

The recall system extracts reusable facts from sessionA single conversation or interaction with an AI coding agent, typically one run/launch history, ranks them by relevance, and assembles context for AI agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) prompts. It distills key information such as technical decisions, projectA named group of sessions, typically corresponding to a code repository conventions, environment setup, and solution patterns from past sessions into structured recall entries that can be queried and surfaced.

Stakeholders

Stakeholder	Interest
End user	Reuse past learnings and avoid repeating solved problems
AI agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) user	Provide context to AI coding assistants from sessionA single conversation or interaction with an AI coding agent, typically one run/launch history
Power user	Manually curate and review recall entries

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall extract structured recall entries from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages	Must	The system shall extract structured recall entries from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages
FR-2MustThe system shall rank recall entries by relevance to a given query	Must	The system shall rank recall entries by relevance to a given query
FR-3MustThe system shall assemble recall entries into a formatted context block	Must	The system shall assemble recall entries into a formatted context block
FR-4MustThe system shall support querying recall entries via the APIApplication Programming Interface	Must	The system shall support querying recall entries via the APIApplication Programming Interface
FR-5ShouldThe system shall support evidence tracking linking recall entries to source messages	Should	The system shall support evidence tracking linking recall entries to source messages
FR-6ShouldThe system shall support distillation configurations for extraction	Should	The system shall support distillation configurations for extraction

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustRecall queries should complete in under 1 second	Must	Performance	Recall queries should complete in under 1 second

Acceptance Criteria

FR-1MustThe system shall extract structured recall entries from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages
Given sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages exist
When recall extraction is run
Then structured recall entries are created with source evidence
FR-2MustThe system shall rank recall entries by relevance to a given query
Given a query string
When recall ranking is performed
Then results are ordered by relevance score

Open Questions

What is the optimal number of recall entries to include in context assembly?

Specification: Recall System

Overview

The recall system is implemented across internal/recall/ and internal/db/recall*.go. It extracts facts from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages, stores them in SQLiteEmbedded relational database used as the primary session archive with evidence links to source messages, ranks them by query relevance using embeddingA vector representation of text used for semantic search similarity and keyword matching, and assembles formatted context blocks.

Architecture

Session Messages
  → Extraction (distill facts into recall_entries)
  → Storage (SQLiteEmbedded relational database used as the primary session archive: recall_entries, recall_evidence)
  → Ranking (query → ranked results)
  → Context Assembly (formatted prompt block)

Data Models

recall_entries

Field	Type	Description
id	TEXT	Entry identifier
session_id	TEXT	Source sessionA single conversation or interaction with an AI coding agent, typically one run/launch
content	TEXT	Distilled fact content
type	TEXT	Entry type (decision, convention, pattern, etc.)
created_at	TEXT	Creation timestamp

recall_evidence

Field	Type	Description
entry_id	TEXT	Recall entry reference
message_id	TEXT	Source messageAn individual turn in a session (user prompt, assistant response, tool result) reference
relevance	REAL	Evidence relevance score

APIApplication Programming Interface Contracts

GET /api/v1/recall/search

Parameters: - q - query string - limit - max results

Response: Ranked list of recall entries with evidence

Technical Decisions

Decision	Choice	Rationale
Storage	SQLiteEmbedded relational database used as the primary session archive tables	Co-located with sessionA single conversation or interaction with an AI coding agent, typically one run/launch data
Ranking	Embedding + keyword hybrid	Balances semantic and exact matching

Test Plan: Recall System

Scope

Tests cover the ranking algorithm, type definitions, and extraction logic. Integration tests verify SQLiteEmbedded relational database used as the primary session archive persistence and query functionality.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Rank entries by query relevance	Recall entries + query	Ordered by score descending
TC-2	Type definitions validate correctly	Valid/invalid entry types	Correct validation behavior

Test Files

internal/recall/rank_test.go - Ranking algorithm tests
internal/recall/rank_internal_test.go - Internal ranking helper tests
internal/recall/types_test.go - Type definition tests

Coverage Matrix

Requirement	Test Cases
FR-2MustThe system shall rank recall entries by relevance to a given query	TC-1
FR-4MustThe system shall support querying recall entries via the APIApplication Programming Interface	TC-1

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Desktop App

Overview

The desktop app wraps the agentsview web server in a native application using TauriDesktop application framework wrapping web UIs, providing a native title bar, system tray integration, auto-start, and auto-update. It targets macOS (DMGApple Disk Image) and Windows, with the Go binary bundled as a sidecar process.

Stakeholders

Stakeholder	Interest
End user	Install and run agentsview as a native desktop application
macOS user	Prefer DMGApple Disk Image installation with automatic updates
Windows user	Native Windows experience

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall provide a TauriDesktop application framework wrapping web UIs-based desktop wrapper for agentsview	Must	The system shall provide a TauriDesktop application framework wrapping web UIs-based desktop wrapper for agentsview
FR-2MustThe system shall bundle the Go server binary as a TauriDesktop application framework wrapping web UIs sidecar	Must	The system shall bundle the Go server binary as a TauriDesktop application framework wrapping web UIs sidecar
FR-3MustThe system shall support auto-start on login	Must	The system shall support auto-start on login
FR-4MustThe system shall support system tray integration with status icon	Must	The system shall support system tray integration with status icon
FR-5MustThe system shall support auto-update checking and installation	Must	The system shall support auto-update checking and installation
FR-6ShouldThe system shall provide a macOS DMGApple Disk Image installer	Should	The system shall provide a macOS DMGApple Disk Image installer
FR-7ShouldThe system shall provide a Windows installer	Should	The system shall provide a Windows installer

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustDesktop app should use minimal system resources when idle	Must	Performance	Desktop app should use minimal system resources when idle

Acceptance Criteria

FR-1MustThe system shall provide a TauriDesktop application framework wrapping web UIs-based desktop wrapper for agentsview
Given the desktop app is installed
When the app is launched
Then the agentsview web UI opens in the default browser
FR-3MustThe system shall support auto-start on login
Given the desktop app is installed
When the user logs in
Then agentsview starts automatically

Open Questions

Should there be a Linux desktop build or is web-only sufficient?

Specification: Desktop App

Overview

The desktop app uses TauriDesktop application framework wrapping web UIs v2 to wrap the agentsview Go web server. The Go binary is built with the desktop build tag and embedded as a TauriDesktop application framework wrapping web UIs sidecar. The app provides a system tray icon, auto-start via platform-specific mechanisms, and auto-update via GitHub Releases.

Architecture

TauriDesktop application framework wrapping web UIs Shell (Rust)
  → Sidecar: agentsview server (Go)
  → System Tray Icon
  → Auto-start (LaunchAgent / Registry)
  → Auto-update (GitHub Releases APIApplication Programming Interface)

Technical Decisions

Decision	Choice	Rationale
Desktop framework	TauriDesktop application framework wrapping web UIs v2	Lightweight, cross-platform, Rust-based
Server integration	Sidecar process	Keep Go server as single binary
Auto-update	GitHub Releases	Reuses existing release infrastructure
Build	CI workflows	Separate workflows for macOS and Windows

Build Configuration

CI workflows: .github/workflows/desktop-*.yml
Desktop source: desktop/
Build artifacts: DMGApple Disk Image (macOS), NSIS installer (Windows)

Test Plan: Desktop App

Scope

Tests cover the desktop sidecar management and icon handling in the Go binary. Frontend TauriDesktop application framework wrapping web UIs UI tests are covered by E2E test suites.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Desktop icon configuration	Icon settings	Correct icon paths and formats
TC-2	Desktop sidecar management	Sidecar process state	Proper start/stop lifecycle

Test Files

desktop_icon_test.go - Desktop icon configuration tests
desktop_sidecar_test.go - Sidecar lifecycle tests

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall provide a TauriDesktop application framework wrapping web UIs-based desktop wrapper for agentsview	TC-2
FR-2MustThe system shall bundle the Go server binary as a TauriDesktop application framework wrapping web UIs sidecar	TC-2

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: ClickHouseColumnar analytics database supported as a remote mirror and read store Mirror

Overview

The ClickHouseColumnar analytics database supported as a remote mirror and read store mirror pushes sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from the local SQLiteEmbedded relational database used as the primary session archive archive to a remote ClickHouseColumnar analytics database supported as a remote mirror and read store instance, enabling team-wide dashboards and read-only queries at analytics scale. It parallels the PostgreSQLRelational database used as a shared sync target and read store syncThe process of discovering new/changed session files and updating the database and DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror features with incremental push, named targets, projectA named group of sessions, typically corresponding to a code repository filtering, watch mode, OS service management, and read-only serving of the web UI from ClickHouseColumnar analytics database supported as a remote mirror and read store.

Stakeholders

Stakeholder	Interest
Engineering manager	Team-wide visibility into agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) usage at scale
Team member	Access sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from ClickHouseColumnar analytics database supported as a remote mirror and read store-connected analytics tools
Operator	Configure multiple ClickHouseColumnar analytics database supported as a remote mirror and read store targets (work, archive) and run unattended push

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to ClickHouseColumnar analytics database supported as a remote mirror and read store incrementally	Must	The system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to ClickHouseColumnar analytics database supported as a remote mirror and read store incrementally
FR-2MustThe system shall support projectA named group of sessions, typically corresponding to a code repository filtering (include/exclude projects)	Must	The system shall support projectA named group of sessions, typically corresponding to a code repository filtering (include/exclude projects)
FR-3MustThe system shall use fingerprint-based change detection for incremental pushes	Must	The system shall use fingerprint-based change detection for incremental pushes
FR-4MustThe system shall support named ClickHouseColumnar analytics database supported as a remote mirror and read store targets (multiple destinations)	Must	The system shall support named ClickHouseColumnar analytics database supported as a remote mirror and read store targets (multiple destinations)
FR-5MustThe system shall serve the web UI read-only from ClickHouseColumnar analytics database supported as a remote mirror and read store	Must	The system shall serve the web UI read-only from ClickHouseColumnar analytics database supported as a remote mirror and read store
FR-6ShouldThe system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes	Should	The system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes
FR-7ShouldThe system shall support OS service management (systemd/launchd) for auto-push	Should	The system shall support OS service management (systemd/launchd) for auto-push
FR-8ShouldThe system shall syncThe process of discovering new/changed session files and updating the database pricing, usage, curation, and activity-report data to ClickHouseColumnar analytics database supported as a remote mirror and read store	Should	The system shall syncThe process of discovering new/changed session files and updating the database pricing, usage, curation, and activity-report data to ClickHouseColumnar analytics database supported as a remote mirror and read store
FR-9ShouldThe system shall report per-target push status (watermarks, pending counts)	Should	The system shall report per-target push status (watermarks, pending counts)

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustPush must be idempotent; re-running produces the same state	Must	Consistency	Push must be idempotent; re-running produces the same state
NFR-2MustPlain-text ClickHouseColumnar analytics database supported as a remote mirror and read store URLs are refused unless explicitly allowed	Must	Security	Plain-text ClickHouseColumnar analytics database supported as a remote mirror and read store URLs are refused unless explicitly allowed

Constraints

Push is one-way; ClickHouseColumnar analytics database supported as a remote mirror and read store content is never read back into SQLiteEmbedded relational database used as the primary session archive.
The mirror schema uses ReplacingMergeTree tables versioned per push.

Acceptance Criteria

Conflicts

None identified yet.

Open Questions

Should the ClickHouseColumnar analytics database supported as a remote mirror and read store reader support recall entries and semantic search, which it currently reports as unavailable?

Specification: ClickHouseColumnar analytics database supported as a remote mirror and read store Mirror

Overview

The ClickHouseColumnar analytics database supported as a remote mirror and read store integration has two modes: push syncThe process of discovering new/changed session files and updating the database and read-only serve. Push syncThe process of discovering new/changed session files and updating the database (internal/clickhouse/syncThe process of discovering new/changed session files and updating the database.go, push.go) incrementally copies sessions from SQLiteEmbedded relational database used as the primary session archive to ClickHouseColumnar analytics database supported as a remote mirror and read store using fingerprint comparison against the mirror. Read-only serve (internal/clickhouse/store.go) implements db.Store for ClickHouseColumnar analytics database supported as a remote mirror and read store-backed queries, including sessions, messages, analytics, usage, search, secrets, and activity reports. Named targets allow multiple ClickHouseColumnar analytics database supported as a remote mirror and read store destinations, and the clickhouse-go/v2 driver provides the transport.

Architecture

SQLiteEmbedded relational database used as the primary session archive DB → Sync engine (fingerprint diff) → ClickHouseColumnar analytics database supported as a remote mirror and read store (ReplacingMergeTree)
                  ↓
           Watch loop (change events + periodic floor)
                  ↓
           OS service (systemd/launchd via clickhouse service)
                  ↓
           Read-only serve (db.Store over ClickHouseColumnar analytics database supported as a remote mirror and read store)

Data Models

ClickHouseColumnar analytics database supported as a remote mirror and read store target config

Field	Type	Constraints	Description
url	string	required	ClickHouseColumnar analytics database supported as a remote mirror and read store DSNData Source Name (native or HTTP protocol)
database	string	optional	Mirror database name
allow_insecure	bool	optional	Permit plain-text HTTP URLs
projects	list	optional	Inclusive projectA named group of sessions, typically corresponding to a code repository filter
exclude_projects	list	optional	Exclusive projectA named group of sessions, typically corresponding to a code repository filter

Push options

Field	Type	Constraints	Description
full	bool	optional	Re-push every in-scope sessionA single conversation or interaction with an AI coding agent, typically one run/launch and remove stale mirror rows

Push result

Field	Type	Constraints	Description
sessions_pushed	int	not null	Sessions written in this push
messages_pushed	int	not null	Messages written in this push
skipped_unchanged	int	not null	Sessions skipped by fingerprint match
deleted_stale	int	not null	Stale mirror sessions removed
errors	int	not null	Sessions that failed to push

Mirror tables

Table	Purpose
sessions	Mirrored sessionA single conversation or interaction with an AI coding agent, typically one run/launch rows with fingerprints and archive identity
messages	Mirrored messageAn individual turn in a session (user prompt, assistant response, tool result) rows per sessionA single conversation or interaction with an AI coding agent, typically one run/launch
usage_events	Token and cost usage events
cursor_usage_events	Cursor usage APIApplication Programming Interface events
model_pricing	Pricing catalog snapshot
tool_calls	Tool call records for analytics
secret_findings	Secret scan findings
sync_metadata	Push cursors and schema version
source_archives	Contributing archive identities

APIApplication Programming Interface Contracts

`agentsview clickhouse push [target]`

Request

Flag	Type	Required	Description
--all	bool	no	Push every configured target sequentially
--full	bool	no	Force full local resync and push
--projects	string	no	Comma-separated inclusive projectA named group of sessions, typically corresponding to a code repository list
--exclude-projects	string	no	Comma-separated exclusive projectA named group of sessions, typically corresponding to a code repository list
--all-projects	bool	no	Ignore configured projectA named group of sessions, typically corresponding to a code repository filters
--watch	bool	no	Run continuously with debounce and interval floor

Response (200 OK)

Field	Type	Description
summary	text	Pushed/skipped/removed sessionA single conversation or interaction with an AI coding agent, typically one run/launch and messageAn individual turn in a session (user prompt, assistant response, tool result) counts

`agentsview clickhouse status [target]`

Request

Flag	Type	Required	Description
--all	bool	no	Show status for every configured target

Response (200 OK)

Field	Type	Description
status	text	Sync watermarks and pending work per target

`agentsview clickhouse serve`

Serves the web UI read-only from ClickHouseColumnar analytics database supported as a remote mirror and read store. Accepts --base-path and the shared serve flags.

`agentsview clickhouse service`

Installs and manages the OS service (systemd/launchd) for unattended watch push. Refuses to install when the URL is unset, comes from the environment, or uses unresolved variable expansion.

POST /api/v1/push/clickhouse

Request

Field	Type	Required	Description
target	string	no	Named target to push

Response (200 OK)

Field	Type	Description
result	object	Push result summary

Error Responses

Status	Code	Description
400	INVALID_INPUT	URL not configured or projectA named group of sessions, typically corresponding to a code repository filters invalid
400	INSECURE_TRANSPORT	Plain-text URL without explicit allowance

Sequences

Incremental push

CLICommand Line Interface → resolve target → CheckTransportSecurity → fingerprint local candidates
→ compare against mirror fingerprints → write changed batches with retry
→ syncThe process of discovering new/changed session files and updating the database machine metadata → update sync_metadata cursor

Watch push

File watcher event → debounce window → scoped push → progress report
→ periodic interval floor push even without events

Read-only serve

HTTP request → ClickHouseColumnar analytics database supported as a remote mirror and read store Store (db.Store) → SQL over mirror tables → web UI

Technical Decisions

Decision	Choice	Rationale
Change detection	Mirror-side fingerprint comparison	Avoids a monotonic local column and handles scope changes
Table engine	ReplacingMergeTree with push version	Idempotent re-pushes collapse to the latest version
Read serve	Implements `db.Store` interface	Same APIApplication Programming Interface handlers work for SQLiteEmbedded relational database used as the primary session archive, PGPostgreSQL, DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive, and ClickHouseColumnar analytics database supported as a remote mirror and read store
Driver	clickhouse-go/v2	Native protocol plus HTTP support in one maintained client
Transport guard	Refuse plain-text URLs by default	ClickHouseColumnar analytics database supported as a remote mirror and read store often holds full sessionA single conversation or interaction with an AI coding agent, typically one run/launch content

Risks and Unknowns

Schema drift between SQLiteEmbedded relational database used as the primary session archive and ClickHouseColumnar analytics database supported as a remote mirror and read store on version upgrade requires role privileges to create tables.
The ClickHouseColumnar analytics database supported as a remote mirror and read store reader does not implement recall queries or semantic search, so those surfaces stay unavailable in clickhouse serve mode.

Out of Scope

Bi-directional syncThe process of discovering new/changed session files and updating the database from ClickHouseColumnar analytics database supported as a remote mirror and read store back into SQLiteEmbedded relational database used as the primary session archive.
QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients-style remote protocol exposure (unlike the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror).

Test Plan: ClickHouseColumnar analytics database supported as a remote mirror and read store Mirror

Scope

Tests cover incremental push from SQLiteEmbedded relational database used as the primary session archive to ClickHouseColumnar analytics database supported as a remote mirror and read store, fingerprint-based change detection, projectA named group of sessions, typically corresponding to a code repository filtering, named targets, read-only serve parity, analytics and activity-report queries, usage and pricing syncThe process of discovering new/changed session files and updating the database, watch mode, transport-security guards, and schema management. Live-server tests use the chtest harnessThe runtime that executes an agent and persists its session files, such as DeepSeek Harness and file suffix _chtest_test.go. Out of scope are recall queries and semantic search, which the ClickHouseColumnar analytics database supported as a remote mirror and read store reader reports as unavailable.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Push syncs sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to ClickHouseColumnar analytics database supported as a remote mirror and read store	SQLiteEmbedded relational database used as the primary session archive sessionA single conversation or interaction with an AI coding agent, typically one run/launch data	ClickHouseColumnar analytics database supported as a remote mirror and read store has matching rows
TC-2	Fingerprint change detection identifies new/modified	Session fingerprint state	Correct incremental set
TC-3	Project filtering includes/excludes correctly	Include/exclude lists	Filtered push set
TC-4	Named target resolution correct	Config with named targets	Correct target selected
TC-5	Transport-security guard rejects plain-text URLs	`http://` URL without allowance	Security error returned
TC-6	Schema creation produces ReplacingMergeTree tables	Empty mirror database	Expected tables exist

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-7	Full push lifecycle	Live ClickHouseColumnar analytics database supported as a remote mirror and read store via chtest	Data replicated correctly
TC-8	Watch mode pushes on file change	Running watch loop	Auto-push on new sessionA single conversation or interaction with an AI coding agent, typically one run/launch
TC-9	Read-only serve from ClickHouseColumnar analytics database supported as a remote mirror and read store	ClickHouseColumnar analytics database supported as a remote mirror and read store with data	Web UI served from ClickHouseColumnar analytics database supported as a remote mirror and read store
TC-10	Store parity with SQLiteEmbedded relational database used as the primary session archive	Same data in both stores	Identical query results
TC-11	Analytics and activity reports query correctly	ClickHouseColumnar analytics database supported as a remote mirror and read store with usage data	Correct summaries and buckets

End-to-End Tests

ID	Description	Steps	Expected Outcome
TC-12	CLICommand Line Interface push and status round-trip	Run `clickhouse push` then `clickhouse status`	Status shows clean watermark

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-13	ClickHouseColumnar analytics database supported as a remote mirror and read store unreachable	Push fails with connect error
TC-14	Duplicate push (idempotency)	Same state, no duplicates
TC-15	Scope change triggers full push	All in-scope sessions re-pushed
TC-16	Stale mirror sessions removed	Sessions missing locally are deleted

Test Infrastructure

internal/clickhouse/chtest/ harnessThe runtime that executes an agent and persists its session files, such as DeepSeek Harness provisions live ClickHouseColumnar analytics database supported as a remote mirror and read store instances for _chtest_test.go files.
internal/clickhouse/testing.go provides fixture builders for mirror tests.
internal/config/config_clickhouse_test.go covers target resolution and precedence.

Test Files

internal/clickhouse/push_chtest_test.go - Push lifecycle tests (live server).
internal/clickhouse/store_chtest_test.go - Store query tests (live server).
internal/clickhouse/serve_chtest_test.go - Read-only serve tests (live server).
internal/clickhouse/analytics_chtest_test.go - Analytics query tests (live server).
internal/clickhouse/activityreport_chtest_test.go - Activity report tests (live server).
internal/clickhouse/usage_chtest_test.go - Usage syncThe process of discovering new/changed session files and updating the database tests (live server).
internal/clickhouse/project_identity_chtest_test.go - Project identity tests (live server).
internal/clickhouse/fixture_chtest_test.go - Shared fixtures for live tests.
internal/clickhouse/connect_test.go - Connection and target tests.
internal/clickhouse/schema_test.go - Schema management tests.
cmd/agentsview/clickhouse_test.go - CLICommand Line Interface push/status/serve tests.
internal/config/config_clickhouse_test.go - Named target config tests.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to ClickHouseColumnar analytics database supported as a remote mirror and read store incrementally	TC-1, TC-7
FR-2MustThe system shall support projectA named group of sessions, typically corresponding to a code repository filtering (include/exclude projects)	TC-3
FR-3MustThe system shall use fingerprint-based change detection for incremental pushes	TC-2
FR-4MustThe system shall support named ClickHouseColumnar analytics database supported as a remote mirror and read store targets (multiple destinations)	TC-4
FR-5MustThe system shall serve the web UI read-only from ClickHouseColumnar analytics database supported as a remote mirror and read store	TC-9, TC-10
FR-6ShouldThe system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes	TC-8
FR-8ShouldThe system shall syncThe process of discovering new/changed session files and updating the database pricing, usage, curation, and activity-report data to ClickHouseColumnar analytics database supported as a remote mirror and read store	TC-11
FR-9ShouldThe system shall report per-target push status (watermarks, pending counts)	TC-12
NFR-1MustPush must be idempotent; re-running produces the same state	TC-14
NFR-2MustPlain-text ClickHouseColumnar analytics database supported as a remote mirror and read store URLs are refused unless explicitly allowed	TC-5

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Raw Sync Mesh

Overview

The raw syncUpload of original session files to an operator-managed server for later hosted processing mesh preserves original provider sessionA single conversation or interaction with an AI coding agent, typically one run/launch files into a durable local outbox and uploads them to an operator-managed server for multi-device custody. It transports bytes without parsing them, so later server-side derivation can reconstruct browsable sessions from retained source files. It is separate from the parsed-sessionA single conversation or interaction with an AI coding agent, typically one run/launch remote syncSyncing sessions from other machines via SSH or HTTP in p1-sessionA single conversation or interaction with an AI coding agent, typically one run/launch-syncThe process of discovering new/changed session files and updating the database (SSHSecure Shell and S3Simple Storage Service (Amazon S3-compatible) sources), which moves already-parsed archive data rather than original provider files.

Stakeholders

Stakeholder	Interest
End user	Original sessionA single conversation or interaction with an AI coding agent, typically one run/launch files from every device end up in hosted custody without manual steps
Operator	Provisions device credentials, runs the raw-syncThe process of discovering new/changed session files and updating the database server, and inspects custody metadata
Developer	Extends capture to new providers and builds derivation on top of retained generations

Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Requirement
FR-1MustThe system shall capture original provider files into a durable local outbox without parsing their content	Must	The system shall capture original provider files into a durable local outbox without parsing their content
FR-2MustThe system shall record device identity and per-source acknowledged heads (manifest, receipt, generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files) in a local SQLiteEmbedded relational database used as the primary session archive checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced database	Must	The system shall record device identity and per-source acknowledged heads (manifest, receipt, generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files) in a local SQLiteEmbedded relational database used as the primary session archive checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced database
FR-3MustThe system shall negotiate missing objects with the server before uploading, so already-held bytes are never re-sent	Must	The system shall negotiate missing objects with the server before uploading, so already-held bytes are never re-sent
FR-4MustThe system shall upload objects resumably with content verification by exact SHA-256 and byte length	Must	The system shall upload objects resumably with content verification by exact SHA-256 and byte length
FR-5MustThe system shall commit one complete logical generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files per manifest with expected-parent receipt fencing, monotonic generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files assignment, and a durable receipt	Must	The system shall commit one complete logical generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files per manifest with expected-parent receipt fencing, monotonic generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files assignment, and a durable receipt
FR-6MustThe system shall authenticate devices via provisioned credentials exchanged for short-lived scoped tokens, with revocation that blocks issuance and invalidates outstanding tokens	Must	The system shall authenticate devices via provisioned credentials exchanged for short-lived scoped tokens, with revocation that blocks issuance and invalidates outstanding tokens
FR-7MustThe system shall provide a `raw-syncThe process of discovering new/changed session files and updating the database watch` daemon that performs an initial bounded audit, reacts to filesystem changes, repeats the audit every 15 minutes by default, and retries uploads every minute by default	Must	The system shall provide a `raw-syncThe process of discovering new/changed session files and updating the database watch` daemon that performs an initial bounded audit, reacts to filesystem changes, repeats the audit every 15 minutes by default, and retries uploads every minute by default
FR-8MustThe system shall provide a `raw-syncThe process of discovering new/changed session files and updating the database status` command that prints path-free JSON describing the local checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced, pending work, retry state, failures, and coverage	Must	The system shall provide a `raw-syncThe process of discovering new/changed session files and updating the database status` command that prints path-free JSON describing the local checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced, pending work, retry state, failures, and coverage
FR-9ShouldThe system shall claim server parse jobs, reconstruct their source files, parse them, and retry failures through an internal worker library	Should	The system shall claim server parse jobs, reconstruct their source files, parse them, and retry failures through an internal worker library
FR-10ShouldThe system shall serve the raw-syncThe process of discovering new/changed session files and updating the database HTTP control plane from `pg serve` only when the PostgreSQLRelational database used as a shared sync target and read store role holds every required raw-syncThe process of discovering new/changed session files and updating the database privilege	Should	The system shall serve the raw-syncThe process of discovering new/changed session files and updating the database HTTP control plane from `pg serve` only when the PostgreSQLRelational database used as a shared sync target and read store role holds every required raw-syncThe process of discovering new/changed session files and updating the database privilege
FR-11ShouldThe system shall scope custody by tenant, reject unrecognized or excluded providers before bytes enter custody, and exclude S3Simple Storage Service (Amazon S3-compatible) roots from laptop capture	Should	The system shall scope custody by tenant, reject unrecognized or excluded providers before bytes enter custody, and exclude S3Simple Storage Service (Amazon S3-compatible) roots from laptop capture
FR-12ShouldThe system shall expose an authenticated tenant-scoped status route reporting source heads, parse-job counts, devices, and open uploads	Should	The system shall expose an authenticated tenant-scoped status route reporting source heads, parse-job counts, devices, and open uploads

Non-Functional Requirements

Order rows by priority: Must first, then Should, then May.

ID	Priority	Category	Requirement
NFR-1MustThe system shall accept the device credential from the environment only, never from CLICommand Line Interface arguments	Must	Security	The system shall accept the device credential from the environment only, never from CLICommand Line Interface arguments
NFR-2MustThe system shall require HTTPS for the raw-syncThe process of discovering new/changed session files and updating the database server URL except for loopback hosts with an explicit insecure flag	Must	Security	The system shall require HTTPS for the raw-syncThe process of discovering new/changed session files and updating the database server URL except for loopback hosts with an explicit insecure flag
NFR-3MustThe system shall store only SHA-256 digests of device credentials and tokens in PostgreSQLRelational database used as a shared sync target and read store, never clear values	Must	Security	The system shall store only SHA-256 digests of device credentials and tokens in PostgreSQLRelational database used as a shared sync target and read store, never clear values
NFR-4MustThe system shall resume interrupted uploads and survive client restarts via durable checkpoints and persisted upload offsets	Must	Reliability	The system shall resume interrupted uploads and survive client restarts via durable checkpoints and persisted upload offsets
NFR-5ShouldThe system shall fail closed on stale parents, reused capture identities with different content, and conflicting object content	Should	Reliability	The system shall fail closed on stale parents, reused capture identities with different content, and conflicting object content
NFR-6ShouldThe system shall bound per-provider audit work (default 128 sources) and cap the local outbox (default 1 GiB)	Should	Performance	The system shall bound per-provider audit work (default 128 sources) and cap the local outbox (default 1 GiB)

Constraints

Raw syncThe process of discovering new/changed session files and updating the database transports original files only and never writes the normal local SQLiteEmbedded relational database used as the primary session archive sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive.
Hosted raw syncUpload of original session files to an operator-managed server for later hosted processing is not end-to-end encrypted because the server must read retained files to parse them.
Device enrollment and revocation are operator-managed; no public enrollment command or endpoint exists.
S3Simple Storage Service (Amazon S3-compatible) roots are excluded from laptop capture.

Acceptance Criteria

Every FR and NFR shall have at least one acceptance criterion.

Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).

Acceptance criteria verify how a requirement is proven done, they do not restate it. Write concrete, scenario-based criteria (happy path, edge cases and error states where applicable).

Conflicts

None identified yet.

Open Questions

When will public device enrollment and revocation endpoints replace the current operator-managed provisioning?
When will server-side derivation be connected to pg serve startup so retained generations become browsable sessions?
What are the retention, garbage-collection, and disaster-rebuild policies for the raw object repository?

Specification: Raw Sync Mesh

Overview

The laptop side (internal/rawcapture, internal/rawcheckpoint, internal/rawclient, internal/rawupload, internal/rawwatch, internal/rawpath) captures provider files into a SQLiteEmbedded relational database used as the primary session archive-backed outbox and drains generations through a token-scoped HTTP transport. The server side (internal/rawsync custody and device-auth services over internal/postgres raw tables) accepts objects and manifests transactionally, tracks source heads and parse jobs, and exposes tenant-scoped status. Server derivation (internal/rawderive) is an internal worker library that claims parse jobs and reconstructs sources, but pg serve does not start it yet.

Architecture

Provider roots → rawwatch worker → rawcapture → rawcheckpoint outbox (SQLiteEmbedded relational database used as the primary session archive + spool)
                                              ↓
rawupload → rawclient → HTTP transport → rawsync service → postgres metadata + object store
                                              ↓
                                    source heads, receipts, parse jobs → rawderive worker (library only)

Data Models

Raw manifest

Field	Type	Constraints	Description
manifest_id	string	PK, canonical JSON digest	Identity of the accepted generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
provider	string	not null	Provider that owns the source files
source_key	string	not null	Logical source within the provider
configured_root_id	string	not null	Configured source-root identity
capture_id	string	not null, unique per content	Capture identity, single-use per content
capture_time	timestamp	not null	Time the generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files was captured
snapshot	object	snapshot or tombstone	Ordered file-object references or deletion marker
parent_receipt	string	not null	Expected receipt of the preceding accepted generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files

Object reference

Field	Type	Constraints	Description
sha256	bytes	not null, exact	Content address of the raw object
length	int64	not null, exact	Byte length the content must match
logical_path	string	validated via rawpath	Cross-platform relative path of the source file

Source head

Field	Type	Constraints	Description
device_id	string	not null	Immutable device that owns the source
source_key	string	not null	Logical source identity
generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files	int64	monotonic	Accepted generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files counter
manifest_id	string	not null	Currently accepted manifest
receipt	string	not null	Durable receipt for the accepted generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
parse_pending	bool	not null	A parse job awaits claiming
parse_leased	bool	not null	A parse job is leased to a worker
parse_failed	bool	not null	The latest parse attempt failed

Device and token

Field	Type	Constraints	Description
device_id	string	PK, `dev_` prefixed	Immutable device identity
credential_digest	bytes	SHA-256, not null	Digest of the once-returned clear credential
device_name	string	display only	Human-readable name, never authorization identity
revoked	bool	not null	Revocation blocks issuance and invalidates tokens
token_digest	bytes	SHA-256, not null	Digest of the opaque short-lived token
token_scopes	int	fixed allowlist	One or more of negotiate, upload, commit, status
token_expiry	timestamp	max 24h, default 15m	Short-lived token validity window

Parse job

Field	Type	Constraints	Description
job_id	string	PK	Parse job for one accepted generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
manifest_id	string	FK	Generation to reconstruct and parse
state	enum	not null	Ready, leased, retrying, complete, failed, or superseded
attempts	int	not null	Claimed attempt counter for retries
error_code	string	allowlisted	Persisted stage-qualified code, never raw content or paths

Laptop checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced

Field	Type	Constraints	Description
device_id	string	not null	Locally pinned device identity
source_heads	rows	one per source	Last server-acknowledged receipt and generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
outbox_objects	rows	content-addressed spool	Captured objects awaiting upload, capped at 1 GiB
generations	rows	durable	Unacknowledged generations with failure classes
coverage	rows	one per root	Complete or degraded state with gap intervals

APIApplication Programming Interface Contracts

`agentsview raw-syncThe process of discovering new/changed session files and updating the database watch`

Request

Flag	Type	Required	Description
--server	string	yes, or AGENTSVIEW_RAW_SYNC_URL	Raw-syncThe process of discovering new/changed session files and updating the database server URL, HTTPS except loopback with flag
--device-id	string	yes, or AGENTSVIEW_RAW_SYNC_DEVICE_ID	Provisioned device ID
--allow-insecure-http	bool	no	Allow HTTP only for loopback servers
--debounce	duration	no, default 2s	Coalesce window for filesystem changes
--interval	duration	no, default 15m	Bounded full-source audit interval
--audit-limit	int	no, default 128	Maximum source work per provider audit

Response (200 OK)

Field	Type	Description
daemon	process	Runs until SIGINT or SIGTERM, retrying uploads every minute

Error Responses

Status	Code	Description
2	MISSING_CONFIG	Server URL, device ID, or credential is absent
2	INVALID_INPUT	Server URL invalid, contains credentials, or non-loopback HTTP without allowance
2	INVALID_INPUT	No configured provider supports raw captureLocal preservation of original provider session files into a durable upload outbox without parsing their content

`agentsview raw-syncThe process of discovering new/changed session files and updating the database status`

Prints path-free JSON with the local checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced, pending work, retry time, failures, and coverage. Reads the laptop checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced database only and never contacts the server.

`POST /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/tokens`

Request

Field	Type	Required	Description
device_id	string	yes	Provisioned device identity
credential	string	yes	Once-issued clear device credential
scopes	string[]	yes	Fixed names: negotiate, upload, commit, status

Response (200 OK)

Field	Type	Description
token	string	Opaque short-lived access token, default 15-minute TTL

`POST /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/objects/missing`

Request

Field	Type	Required	Description
provider	string	yes	Declared upload source for custody gating
objects	ObjectRef[]	yes, batches of 2048	Canonical object references to check

Response (200 OK)

Field	Type	Description
missing	ObjectRef[]	References not yet in custody

`POST /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/uploads`

Starts or resumes an object upload for the upload scope.

`HEAD /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/uploads/{id}`

Reads the accepted upload offset for the upload scope.

`PATCH /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/uploads/{id}`

Appends and finalizes object bytes for the upload scope.

Error Responses

Status	Code	Description
401	unauthorized	Missing, expired, revoked, or wrong-scoped token
404	not_found	Unknown upload or custody object
409	conflict	Conflicting content for an existing object
409	upload_offset_conflict	Resumed offset does not match the accepted offset
422	checksum_mismatch	Finalized bytes fail SHA-256 or length verification

`POST /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/manifests`

Request

Field	Type	Required	Description
manifest	object	yes	Canonical generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files envelope for the `commit` scope

Response (200 OK)

Field	Type	Description
manifest_id	string	Canonical digest of the accepted manifest
receipt	string	Durable receipt for this generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files	int64	Monotonically assigned generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files number

Error Responses

Status	Code	Description
409	head_conflict	Expected parent receipt does not match the current source head
422	missing_object	A referenced object is absent or fails verification

`GET /api/v1/raw-syncThe process of discovering new/changed session files and updating the database/status`

Returns source heads, parse-job counts, devices with last-seen times, and open-upload metadata for the authenticated tenant. Uses one read-only PostgreSQLRelational database used as a shared sync target and read store transaction and changes no raw-syncThe process of discovering new/changed session files and updating the database state.

Sequences

Capture and upload

Watcher event → rawwatch worker → rawcapture plans source → outbox spool + reservation
→ periodic drain → missing-object negotiation → resumable chunk uploads
→ manifest commit → server receipt → checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced acknowledgement → spool garbage collection

Device authentication

Operator provisions device → laptop stores credential in env
→ POST /tokens with credential → server checks digest, revocation, expiry
→ scoped token → per-route scope check → revocation invalidates outstanding tokens

Manifest acceptance

Commit arrives → verify every referenced object exists and checksums match
→ compare expected parent receipt with source head → record manifest, entries, references
→ assign generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files and receipt → create parse job → advance head, retire prior pending job

Bounded audit and retry

Startup audit (limit 128 sources) → filesystem watch with 2s debounce
→ 15m full audit tick → 1m upload retry and root re-registration tick
→ degraded coverage rows persist gap intervals until recovery

Server derivation (library only)

Worker claims ready parse job → materializes source files to scratch
→ parses into sessions → marks complete or records allowlisted error code
→ pg serve does not start this worker yet

Technical Decisions

Decision	Choice	Rationale
Transport unit	Whole logical generations with canonical manifests	Atomic custody handoff keeps multi-file sources consistent
Content identity	Exact SHA-256 plus byte length	Identical retries become no-ops while conflicts fail closed
Manifest identity	Canonical JSON digest	Stable IDs make replay detection and receipt binding exact
Auth model	Operator-provisioned credentials with short-lived scoped tokens	Limits blast radius per operation without public enrollment
Digest-only storage	SHA-256 of credentials and tokens in PostgreSQLRelational database used as a shared sync target and read store	A database leak never yields usable secrets
Manifest-last commits	Objects before manifests	A manifest can only reference verified custody
Laptop state	Dedicated SQLiteEmbedded relational database used as the primary session archive checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced database	Restart-safe retries without touching the sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
Outbox cap	1 GiB default with backpressure errors	Bounded laptop disk use under large or stuck generations
Path validation	Canonical relative paths via rawpath	Manifests stay portable across Windows, macOS, and Linux
Tombstones	First-class manifest variant	Source deletions propagate as custody facts rather than silence

Risks and Unknowns

Server derivation is unconnected to pg serve startup, so retained generations are not yet browsable sessions.
Retention, garbage collection, disaster rebuilds, and migration from pg push are undefined.
PostgreSQLRelational database used as a shared sync target and read store row-level security is a planned defense-in-depth layer and is not configured.
The HTTP surface is an internal laptop-to-server protocol with no compatibility policy for external integrators.

Out of Scope

Parsed-sessionA single conversation or interaction with an AI coding agent, typically one run/launch remote syncSyncing sessions from other machines via SSH or HTTP via SSHSecure Shell and S3Simple Storage Service (Amazon S3-compatible), which belongs to p1-sessionA single conversation or interaction with an AI coding agent, typically one run/launch-syncThe process of discovering new/changed session files and updating the database.
Public device enrollment and revocation endpoints.
End-to-end encryption of retained provider files.
Hosted embeddingA vector representation of text used for semantic search generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files and browsable hosted sessions.
Retention, garbage collection, disaster rebuilds, and pg push migration tooling.

Test Plan: Raw Sync Mesh

Scope

Tests cover laptop capture into the durable outbox, checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced persistence and acknowledgement, missing-object negotiation, resumable upload, manifest acceptance with parent fencing, device authentication with scoped tokens and revocation, the watch worker with bounded audits, server-side derivation jobs, CLICommand Line Interface watch and status commands, HTTP routes, and PostgreSQLRelational database used as a shared sync target and read store-backed custody stores. Out of scope are public enrollment, hosted browsing and embeddings, retention and garbage collection, and pg push migration, which are not implemented.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Capture stores provider files in the outbox without parsing	Provider source files on disk	Unpublished generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files with content-addressed objects
TC-2	Unchanged sources report unchanged and write nothing new	Unmodified source files	Unchanged status with no new outbox rows
TC-3	Checkpoint advances source heads only on durable receipts	Server commit result	Head updated, spool reclaimed on acknowledgement
TC-4	Outbox enforces capacity and reservation accounting	Oversized capture plan	Outbox-full error without partial writes
TC-5	Manifest canonicalization binds tenant and device identity	Manifest envelope	Stable digest used as manifest ID
TC-6	Custody verifies SHA-256 and length before registering	Object bytes	Matching content registers, conflicts rejected
TC-7	Stale parent receipts and reused capture identities fail closed	Conflicting commit	Rejection with head unchanged
TC-8	Device tokens carry fixed scopes and short TTLs	Credential exchange	Scoped token issued, wrong scope rejected
TC-9	Revocation blocks issuance and invalidates tokens	Revoked device	No new tokens, outstanding tokens unusable
TC-10	Upload offset tracking supports resume	Partial upload state	Retry continues from accepted offset
TC-11	Derivation worker claims jobs and records allowlisted error codes	Ready parse job	Complete state or stage-qualified code, no raw content persisted
TC-12	Watch config validation rejects bad URLs and missing credentials	Flag and env combinations	Precise refusal for each invalid combination
TC-13	Path validation accepts canonical relative paths only	Candidate logical paths	Invalid paths rejected across platforms

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-14	Client drains a generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files end to end against a live server	Laptop outbox plus raw-syncThe process of discovering new/changed session files and updating the database server	Receipt bound and checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced acknowledged
TC-15	Interrupted upload resumes after client restart	Partial upload with persisted offset	Completed object without re-sending held bytes
TC-16	Watch worker serializes capture, audit, and upload	Changed provider files	Single bounded work stream converges to clean status
TC-17	Bounded audit defers excess sources to later passes	More changes than the audit limit	Remaining sources reconcile on subsequent audits
TC-18	PostgreSQLRelational database used as a shared sync target and read store custody stores accept generations transactionally	Live PostgreSQLRelational database used as a shared sync target and read store with raw schema	Manifest, entries, head, and parse job in one transaction
TC-19	`pg serve` gates raw routes on role privileges	Read-only or under-granted role	Routes omitted with exact missing-privilege log
TC-20	Derivation pipeline materializes and parses retained sources	Accepted generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files with objects	Parsed sessions or retryable failure recorded

End-to-End Tests

ID	Description	Steps	Expected Outcome
TC-21	CLICommand Line Interface watch uploads and status reports clean checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced	Run `raw-syncThe process of discovering new/changed session files and updating the database watch`, change a sessionA single conversation or interaction with an AI coding agent, typically one run/launch file, run `raw-syncThe process of discovering new/changed session files and updating the database status`	Generation acknowledged, status shows no pending work
TC-22	HTTP custody round-trip through tokens, negotiation, upload, and commit	Authenticate device, negotiate, upload, commit manifest	Durable receipt with monotonic generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-23	Server unreachable mid-drain	Transient failure class with retry on the next tick
TC-24	Permanent server rejection	Permanent failure class, generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files blocked without retry storm
TC-25	Duplicate byte-identical commit	Existing receipt returned as a no-op
TC-26	Tombstone generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files for a deleted source	Deletion propagates as a custody fact
TC-27	SQLiteEmbedded relational database used as the primary session archive snapshot of a locked provider database	Safe snapshot captured without locking the provider out
TC-28	Non-loopback HTTP server URL	Watch refuses without the insecure allowance

Test Infrastructure

internal/rawsync unit tests exercise custody and device auth without a database.
internal/postgres *_pgtest_test.go files run PostgreSQLRelational database used as a shared sync target and read store-backed custody, upload, device-auth, derivation, schema, and status suites.
internal/rawclient/e2e_test.go drives the HTTP transport against a test server.
cmd/agentsview/raw_sync_test.go covers watch-config validation and status output.
cmd/agentsview/pg_raw_sync_test.go covers pg serve route gating.
internal/server/huma_routes_raw_upload_test.go and huma_routes_raw_sync_test.go cover the HTTP routes.

Test Files

internal/rawcapture/capturer_test.go - Capture planning and unchanged detection.
internal/rawcapture/sqlite_snapshot_test.go - Safe SQLiteEmbedded relational database used as the primary session archive snapshot behavior.
internal/rawcapture/sqlite_snapshot_unix_test.go - Unix snapshot behavior.
internal/rawcapture/sqlite_snapshot_windows_test.go - Windows snapshot behavior.
internal/rawcapture/identity_windows_test.go - Windows file identity.
internal/rawcapture/capacity_linux_test.go - Linux capacity accounting.
internal/rawcheckpoint/store_test.go - Checkpoint persistence and heads.
internal/rawcheckpoint/outbox_test.go - Outbox spooling and reservations.
internal/rawcheckpoint/ack_test.go - Receipt acknowledgement and failure classes.
internal/rawcheckpoint/recovery_test.go - Restart recovery.
internal/rawcheckpoint/status_test.go - Path-free client status.
internal/rawcheckpoint/rows_error_test.go - Row error mapping.
internal/rawsync/manifest_test.go - Manifest canonicalization and limits.
internal/rawsync/device_auth_test.go - Credential, token, scope, and revocation logic.
internal/rawsync/service_test.go - Custody acceptance and fencing.
internal/rawsync/upload_test.go - Upload offset and finalization.
internal/rawsync/object_store_artifact_test.go - Object repository behavior.
internal/rawupload/uploader_test.go - Outbox draining and retry classes.
internal/rawclient/client_test.go - Client construction and error decoding.
internal/rawclient/tokens_test.go - Token exchange.
internal/rawclient/upload_test.go - Chunked resumable upload.
internal/rawclient/commit_test.go - Manifest commit.
internal/rawclient/e2e_test.go - Client transport against a test server.
internal/rawderive/manifest_test.go - Job manifest handling.
internal/rawderive/materializer_test.go - Source reconstruction.
internal/rawderive/parser_test.go - Derived parsing.
internal/rawderive/worker_test.go - Job claiming and retry codes.
internal/rawwatch/auditor_test.go - Bounded audit behavior.
internal/rawwatch/auditor_windows_test.go - Windows audit behavior.
internal/rawwatch/worker_test.go - Serialized capture, audit, and upload.
internal/postgres/raw_ingest_schema_pgtest_test.go - Raw schema migrations.
internal/postgres/raw_ingest_store_pgtest_test.go - Ingest metadata store.
internal/postgres/raw_upload_store_pgtest_test.go - Upload custody store.
internal/postgres/raw_device_auth_store_pgtest_test.go - Device auth store.
internal/postgres/raw_parse_jobs_pgtest_test.go - Parse-job lifecycle.
internal/postgres/raw_sync_status_pgtest_test.go - Tenant status aggregation.
internal/postgres/raw_ingest_custody_pgtest_test.go - Custody acceptance transactions.
internal/postgres/raw_upload_custody_pgtest_test.go - Upload custody transactions.
internal/postgres/raw_client_e2e_pgtest_test.go - Client against live PostgreSQLRelational database used as a shared sync target and read store.
internal/postgres/raw_derive_pipeline_pgtest_test.go - Derivation pipeline.
internal/server/huma_routes_raw_upload_test.go - Upload HTTP routes.
internal/server/huma_routes_raw_sync_test.go - Token, manifest, and status routes.
cmd/agentsview/raw_sync_test.go - Watch validation and status CLICommand Line Interface.
cmd/agentsview/pg_raw_sync_test.go - pg serve route gating.

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall capture original provider files into a durable local outbox without parsing their content	TC-1, TC-2, TC-27
FR-2MustThe system shall record device identity and per-source acknowledged heads (manifest, receipt, generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files) in a local SQLiteEmbedded relational database used as the primary session archive checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced database	TC-3
FR-3MustThe system shall negotiate missing objects with the server before uploading, so already-held bytes are never re-sent	TC-14
FR-4MustThe system shall upload objects resumably with content verification by exact SHA-256 and byte length	TC-10, TC-15
FR-5MustThe system shall commit one complete logical generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files per manifest with expected-parent receipt fencing, monotonic generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files assignment, and a durable receipt	TC-5, TC-6, TC-7, TC-18, TC-25
FR-6MustThe system shall authenticate devices via provisioned credentials exchanged for short-lived scoped tokens, with revocation that blocks issuance and invalidates outstanding tokens	TC-8, TC-9
FR-7MustThe system shall provide a `raw-syncThe process of discovering new/changed session files and updating the database watch` daemon that performs an initial bounded audit, reacts to filesystem changes, repeats the audit every 15 minutes by default, and retries uploads every minute by default	TC-12, TC-16, TC-17
FR-8MustThe system shall provide a `raw-syncThe process of discovering new/changed session files and updating the database status` command that prints path-free JSON describing the local checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced, pending work, retry state, failures, and coverage	TC-21
FR-9ShouldThe system shall claim server parse jobs, reconstruct their source files, parse them, and retry failures through an internal worker library	TC-11, TC-20
FR-10ShouldThe system shall serve the raw-syncThe process of discovering new/changed session files and updating the database HTTP control plane from `pg serve` only when the PostgreSQLRelational database used as a shared sync target and read store role holds every required raw-syncThe process of discovering new/changed session files and updating the database privilege	TC-19
FR-11ShouldThe system shall scope custody by tenant, reject unrecognized or excluded providers before bytes enter custody, and exclude S3Simple Storage Service (Amazon S3-compatible) roots from laptop capture	TC-6
FR-12ShouldThe system shall expose an authenticated tenant-scoped status route reporting source heads, parse-job counts, devices, and open uploads	TC-22
NFR-1MustThe system shall accept the device credential from the environment only, never from CLICommand Line Interface arguments	TC-12
NFR-2MustThe system shall require HTTPS for the raw-syncThe process of discovering new/changed session files and updating the database server URL except for loopback hosts with an explicit insecure flag	TC-28
NFR-3MustThe system shall store only SHA-256 digests of device credentials and tokens in PostgreSQLRelational database used as a shared sync target and read store, never clear values	TC-8
NFR-4MustThe system shall resume interrupted uploads and survive client restarts via durable checkpoints and persisted upload offsets	TC-10, TC-15
NFR-5ShouldThe system shall fail closed on stale parents, reused capture identities with different content, and conflicting object content	TC-7, TC-24, TC-25
NFR-6ShouldThe system shall bound per-provider audit work (default 128 sources) and cap the local outbox (default 1 GiB)	TC-4, TC-17

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Full-Text Search

Overview

The full-text search feature indexes all sessionA single conversation or interaction with an AI coding agent, typically one run/launch messageAn individual turn in a session (user prompt, assistant response, tool result) content using SQLiteEmbedded relational database used as the primary session archive FTS5Full-Text Search version 5 and provides fast text-based search across all sessions. It supports multiple query modes (AND, exact phrase, prefix), filtering by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository, date, and source scope, and returns ranked results with snippet highlights.

Stakeholders

Stakeholder	Interest
End user	Quickly find past sessions by searching for specific terms, code snippets, or error messages

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall index all messageAn individual turn in a session (user prompt, assistant response, tool result) content using SQLiteEmbedded relational database used as the primary session archive FTS5Full-Text Search version 5	Must	The system shall index all messageAn individual turn in a session (user prompt, assistant response, tool result) content using SQLiteEmbedded relational database used as the primary session archive FTS5Full-Text Search version 5
FR-2MustThe system shall support AND-mode search (all terms must match)	Must	The system shall support AND-mode search (all terms must match)
FR-3MustThe system shall support exact phrase matching with double quotes	Must	The system shall support exact phrase matching with double quotes
FR-4MustThe system shall support prefix matching (trailing wildcard)	Must	The system shall support prefix matching (trailing wildcard)
FR-5MustThe system shall return ranked results with snippet highlights	Must	The system shall return ranked results with snippet highlights
FR-6MustThe system shall support filtering by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository, date range, machine, and git branch	Must	The system shall support filtering by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository, date range, machine, and git branch
FR-7MustThe system shall support cursor-based pagination	Must	The system shall support cursor-based pagination
FR-8ShouldThe system shall support regex-based content search as an alternative mode	Should	The system shall support regex-based content search as an alternative mode

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustSearch results should return in under 500ms for typical queries	Must	Performance	Search results should return in under 500ms for typical queries
NFR-2ShouldIndex should handle millions of messages	Should	Scalability	Index should handle millions of messages

Acceptance Criteria

FR-1MustThe system shall index all messageAn individual turn in a session (user prompt, assistant response, tool result) content using SQLiteEmbedded relational database used as the primary session archive FTS5Full-Text Search version 5
- Given messages are synced
- When a search query is submitted
- Then results include matching messages with snippet highlights

Open Questions

None.

Specification: Full-Text Search

Overview

Search uses SQLiteEmbedded relational database used as the primary session archive FTS5Full-Text Search version 5 virtual tables created during DB migration. The indexed content covers messageAn individual turn in a session (user prompt, assistant response, tool result) body text with configurable tokenization. Queries support AND, exact phrase, and prefix modes. Results include per-hit snippets built from the FTS5Full-Text Search version 5 snippet() function.

Data Models

FTS5Full-Text Search version 5 Virtual Table

Column	Type	Description
content	TEXT	Message body text
session_id	TEXT	Parent sessionA single conversation or interaction with an AI coding agent, typically one run/launch
agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)	TEXT	Agent type
projectA named group of sessions, typically corresponding to a code repository	TEXT	Project name

APIApplication Programming Interface Contracts

GET /api/v1/search

Query Parameters

Field	Type	Required	Description
q	string	Yes	Search query
agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)	string	No	Filter by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)
projectA named group of sessions, typically corresponding to a code repository	string	No	Filter by projectA named group of sessions, typically corresponding to a code repository
since	string	No	Start date (RFC3339)
until	string	No	End date (RFC3339)
limit	int	No	Results per page
cursor	string	No	Pagination cursor

Response

Field	Type	Description
results	[]SearchResult	Ranked hits with snippets
next_cursor	string	Cursor for next page

Technical Decisions

Decision	Choice	Rationale
Tokenizer	unicode61	Good Unicode support for multi-language content
Query mode	AND by default	Most intuitive for user search; exact phrase with quotes

Risks and Unknowns

FTS5Full-Text Search version 5 index rebuild on version migration

Test Plan: Full-Text Search

Scope

Tests cover FTS5Full-Text Search version 5 index creation, query modes (AND, exact phrase, prefix), snippet generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files, filtering by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)/projectA named group of sessions, typically corresponding to a code repository/date/machine/branch, cursor-based pagination, and regex search.

Unit Tests

ID	Description	Input	Expected Output
TC-1	AND-mode search returns only messages matching all terms	Multi-term query	Filtered results
TC-2	Exact phrase search matches quoted terms	Quoted phrase query	Results matching exact phrase
TC-3	Prefix search matches trailing wildcard	Prefix query	Results with matching prefix
TC-4	Snippet generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files includes hit context	Search query + messageAn individual turn in a session (user prompt, assistant response, tool result) body	Snippet with highlighted terms
TC-5	Filter by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) returns only that agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)'s sessions	Agent filter param	Filtered results
TC-6	Filter by projectA named group of sessions, typically corresponding to a code repository returns only that projectA named group of sessions, typically corresponding to a code repository's sessions	Project filter param	Filtered results
TC-7	Date range filter scopes results correctly	Since/until params	Results only in date range
TC-8	Cursor pagination returns next page of results	Cursor from first page	Next page results
TC-9	Hybrid search merges FTS5Full-Text Search version 5 and semantic results	RRFReciprocal Rank Fusion mode query	Merged ranked results

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-10	Search across indexed messages	Messages synced to DB	Results returned with snippets

Test Files

internal/db/search_test.go - Core search query tests
internal/db/search_content_test.go - Content search tests
internal/db/search_content_scope_test.go - Scope filtering tests
internal/db/search_content_chunk_test.go - Chunk-level search tests
internal/db/search_content_bench_test.go - Search performance benchmarks
internal/server/search_test.go - HTTP search handler tests

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall index all messageAn individual turn in a session (user prompt, assistant response, tool result) content using SQLiteEmbedded relational database used as the primary session archive FTS5Full-Text Search version 5	TC-10
FR-2MustThe system shall support AND-mode search (all terms must match)	TC-1
FR-3MustThe system shall support exact phrase matching with double quotes	TC-2
FR-4MustThe system shall support prefix matching (trailing wildcard)	TC-3
FR-5MustThe system shall return ranked results with snippet highlights	TC-4
FR-6MustThe system shall support filtering by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository, date range, machine, and git branch	TC-5, TC-6, TC-7
FR-7MustThe system shall support cursor-based pagination	TC-8

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Semantic Search

Overview

The semantic search feature provides meaning-based search across sessionA single conversation or interaction with an AI coding agent, typically one run/launch content using vector embeddings. An opt-in feature, it indexes sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages via an OpenAI-compatible embeddings endpoint, stores vectors in a separate sqlite-vecSQLite extension for vector similarity search database, and supports pure semantic and hybrid (RRFReciprocal Rank Fusion-merged) search modes.

Stakeholders

Stakeholder	Interest
End user	Find sessions by meaning rather than exact text match
Power user	Configure custom embeddingA vector representation of text used for semantic search endpoints (model, dimensions, provider)

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall support building an embeddingA vector representation of text used for semantic search index from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messageAn individual turn in a session (user prompt, assistant response, tool result) content	Must	The system shall support building an embeddingA vector representation of text used for semantic search index from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messageAn individual turn in a session (user prompt, assistant response, tool result) content
FR-2MustThe system shall support multiple embeddingA vector representation of text used for semantic search generations (different models/dimensions)	Must	The system shall support multiple embeddingA vector representation of text used for semantic search generations (different models/dimensions)
FR-3MustThe system shall support activating and retiring generations	Must	The system shall support activating and retiring generations
FR-4MustThe system shall support pure semantic search (query → vector → similarity)	Must	The system shall support pure semantic search (query → vector → similarity)
FR-5MustThe system shall support hybrid search (RRFReciprocal Rank Fusion merge of FTS5Full-Text Search version 5 + semantic results)	Must	The system shall support hybrid search (RRFReciprocal Rank Fusion merge of FTS5Full-Text Search version 5 + semantic results)
FR-6MustThe system shall support configurable embeddingA vector representation of text used for semantic search endpoints, APIApplication Programming Interface keys, and models	Must	The system shall support configurable embeddingA vector representation of text used for semantic search endpoints, APIApplication Programming Interface keys, and models
FR-7ShouldThe system shall support incremental index updates (only new/changed content)	Should	The system shall support incremental index updates (only new/changed content)
FR-8ShouldThe system shall provide a background scheduler for automatic index builds	Should	The system shall provide a background scheduler for automatic index builds

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustEmbedding build should batch requests with configurable concurrency	Must	Performance	Embedding build should batch requests with configurable concurrency
NFR-2ShouldSemantic search is opt-in and does not affect core syncThe process of discovering new/changed session files and updating the database or FTS5Full-Text Search version 5 search	Should	Isolation	Semantic search is opt-in and does not affect core syncThe process of discovering new/changed session files and updating the database or FTS5Full-Text Search version 5 search

Acceptance Criteria

FR-1MustThe system shall support building an embeddingA vector representation of text used for semantic search index from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messageAn individual turn in a session (user prompt, assistant response, tool result) content
- Given messages are synced
- When an embeddings build is triggered
- Then a vector index is created for all messages
FR-4MustThe system shall support pure semantic search (query → vector → similarity)
- Given an active embeddingA vector representation of text used for semantic search generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
- When a semantic search query is submitted
- Then results ranked by cosine similarity are returned

Open Questions

What are the recommended default embeddingA vector representation of text used for semantic search providers and models?

Specification: Semantic Search

Overview

Semantic search uses a separate SQLiteEmbedded relational database used as the primary session archive database (vectors.db) with the sqlite-vecSQLite extension for vector similarity search extension. A messageAn individual turn in a session (user prompt, assistant response, tool result) mirror table tracks content changes for incremental updates. The encoder client sends content to an OpenAI-compatible embeddings APIApplication Programming Interface with configurable endpoint, model, dimensions, batch size, and concurrency.

Architecture

Main SQLiteEmbedded relational database used as the primary session archive DB → Message Mirror (hash-based refresh)
                     ↓
              Embeddings Encoder (HTTP client)
                     ↓
              vectors.db (sqlite-vecSQLite extension for vector similarity search)
                     ↓
          Query → Encode → Similarity Search
                     ↓
              FTS5Full-Text Search version 5 + Semantic → RRFReciprocal Rank Fusion Merge (hybrid mode)

Data Models

vector_messages

Field	Type	Description
id	INTEGER	Primary key
message_id	TEXT	Source messageAn individual turn in a session (user prompt, assistant response, tool result) ID
content_hash	TEXT	Hash of messageAn individual turn in a session (user prompt, assistant response, tool result) content
session_id	TEXT	Parent sessionA single conversation or interaction with an AI coding agent, typically one run/launch
ordinal	INTEGER	Message position in sessionA single conversation or interaction with an AI coding agent, typically one run/launch
refreshed_at	TEXT	Last refresh timestamp

embedding_generations

Field	Type	Description
id	INTEGER	Primary key
model	TEXT	Embedding model name
dimensions	INTEGER	Vector dimensions
status	TEXT	building, active, retired
started_at	TEXT	Build start time
completed_at	TEXT	Build completion time

APIApplication Programming Interface Contracts

POST /api/v1/embeddings/build

Response: SSEServer-Sent Events stream of build progress

GET /api/v1/embeddings/generations

Response: List of generations with status

POST /api/v1/embeddings/generations/{id}/activate

Response: Generation status

Technical Decisions

Decision	Choice	Rationale
Vector DB	Separate SQLiteEmbedded relational database used as the primary session archive + sqlite-vecSQLite extension for vector similarity search	Avoids coupling with main sessionA single conversation or interaction with an AI coding agent, typically one run/launch DB
RRFReciprocal Rank Fusion merge	k=60 constant	Standard RRFReciprocal Rank Fusion parameter for hybrid search
Build strategy	Full scan then incremental	Balances completeness with efficiency

Risks and Unknowns

Embedding APIApplication Programming Interface cost for large datasets
sqlite-vecSQLite extension for vector similarity search SQLiteEmbedded relational database used as the primary session archive extension availability on all platforms

Test Plan: Semantic Search

Scope

Tests cover embeddingA vector representation of text used for semantic search index building, generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files management (activation/retirement), pure semantic search, hybrid RRFReciprocal Rank Fusion search, configurable embeddingA vector representation of text used for semantic search endpoints, incremental index updates, and background scheduler.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Build embeddingA vector representation of text used for semantic search index from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages	Message content	Vector index created
TC-2	Activate/retire embeddingA vector representation of text used for semantic search generations	Generation IDs	Correct generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files state
TC-3	Pure semantic search returns similarity-ranked results	Query text	Results ordered by cosine similarity
TC-4	Hybrid search merges FTS5Full-Text Search version 5 and semantic results	Query text	RRFReciprocal Rank Fusion-merged ranked results
TC-5	Embedding encoder batches requests	Multiple messages	Batched APIApplication Programming Interface calls
TC-6	Index staleness detection	Build version vs current data	Correct staleness verdict

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-7	Full embeddingA vector representation of text used for semantic search build pipeline	Messages synced	Vectors stored and searchable
TC-8	Index repair on corruption	Corrupted vector index	Index rebuilt

Test Files

internal/vector/build_test.go - Embedding index build tests
internal/vector/search_test.go - Semantic/hybrid search tests
internal/vector/index_test.go - Index management tests
internal/vector/encoder_test.go - Embedding encoder tests
internal/vector/manager_test.go - Generation management tests
internal/vector/repair_test.go - Index repair tests
internal/vector/chunk_test.go - Chunking for embeddingA vector representation of text used for semantic search tests
internal/server/huma_routes_embeddings_test.go - Embedding APIApplication Programming Interface tests

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-9	Embedding APIApplication Programming Interface endpoint unreachable	Build fails gracefully with error
TC-10	Zero messages to index	No-op, no index created

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall support building an embeddingA vector representation of text used for semantic search index from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messageAn individual turn in a session (user prompt, assistant response, tool result) content	TC-1, TC-7
FR-2MustThe system shall support multiple embeddingA vector representation of text used for semantic search generations (different models/dimensions)	TC-2
FR-3MustThe system shall support activating and retiring generations	TC-2
FR-4MustThe system shall support pure semantic search (query → vector → similarity)	TC-3
FR-5MustThe system shall support hybrid search (RRFReciprocal Rank Fusion merge of FTS5Full-Text Search version 5 + semantic results)	TC-4
FR-6MustThe system shall support configurable embeddingA vector representation of text used for semantic search endpoints, APIApplication Programming Interface keys, and models	TC-5

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Analytics & Cost Tracking

Overview

The analytics and cost tracking feature provides dashboards and reports on sessionA single conversation or interaction with an AI coding agent, typically one run/launch activity, tool usage, token consumption, and associated costs. It includes activity heatmaps, velocity metrics, per-model cost breakdowns, sessionA single conversation or interaction with an AI coding agent, typically one run/launch health signals, and AI-generated insights.

Stakeholders

Stakeholder	Interest
End user	Understand personal productivity patterns and AI agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) costs
Engineering manager	Team-wide usage visibility via PostgreSQLRelational database used as a shared sync target and read store syncThe process of discovering new/changed session files and updating the database and analytics queries

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall compute and display activity heatmaps over configurable time ranges	Must	The system shall compute and display activity heatmaps over configurable time ranges
FR-2MustThe system shall track token usage per sessionA single conversation or interaction with an AI coding agent, typically one run/launch and per model	Must	The system shall track token usage per sessionA single conversation or interaction with an AI coding agent, typically one run/launch and per model
FR-3MustThe system shall compute cost estimates using a pricing catalog	Must	The system shall compute cost estimates using a pricing catalog
FR-4MustThe system shall provide daily cost summaries with per-model breakdowns	Must	The system shall provide daily cost summaries with per-model breakdowns
FR-5MustThe system shall compute sessionA single conversation or interaction with an AI coding agent, typically one run/launch health signals (outcome, tool health, context pressure)	Must	The system shall compute sessionA single conversation or interaction with an AI coding agent, typically one run/launch health signals (outcome, tool health, context pressure)
FR-6MustThe system shall provide a sessionA single conversation or interaction with an AI coding agent, typically one run/launch stats endpoint with distribution metrics	Must	The system shall provide a sessionA single conversation or interaction with an AI coding agent, typically one run/launch stats endpoint with distribution metrics
FR-7MustThe system shall support timezone-aware date bucketing	Must	The system shall support timezone-aware date bucketing
FR-8ShouldThe system shall provide AI-generated insights from sessionA single conversation or interaction with an AI coding agent, typically one run/launch data	Should	The system shall provide AI-generated insights from sessionA single conversation or interaction with an AI coding agent, typically one run/launch data
FR-9ShouldThe system shall support automated sessionA single conversation or interaction with an AI coding agent, typically one run/launch classification (human vs automated)	Should	The system shall support automated sessionA single conversation or interaction with an AI coding agent, typically one run/launch classification (human vs automated)
FR-10ShouldThe system shall compute velocity metrics (sessions/day, messages/sessionA single conversation or interaction with an AI coding agent, typically one run/launch)	Should	The system shall compute velocity metrics (sessions/day, messages/sessionA single conversation or interaction with an AI coding agent, typically one run/launch)

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustAnalytics queries should complete in under 2 seconds	Must	Performance	Analytics queries should complete in under 2 seconds
NFR-2ShouldCost tracking prices are within 5% of actual provider billing	Should	Accuracy	Cost tracking prices are within 5% of actual provider billing

Acceptance Criteria

FR-1MustThe system shall compute and display activity heatmaps over configurable time ranges
- Given sessionA single conversation or interaction with an AI coding agent, typically one run/launch data exists
- When the analytics page is loaded
- Then activity heatmaps are displayed for the configured time range
FR-4MustThe system shall provide daily cost summaries with per-model breakdowns
- Given sessions have token usage data
- When agentsview usage daily is run
- Then a cost summary with model breakdown is printed

Open Questions

How should prompt caching costs be modeled for accurate pricing?

Specification: Analytics & Cost Tracking

Overview

Analytics queries are implemented as SQL aggregations over the sessions and messages tables. Cost tracking uses a model pricing catalog with LiteLLMOpen-source LLM pricing catalog used for cost estimation integration for dynamic pricing and an offline fallback. Health signals are computed post-syncThe process of discovering new/changed session files and updating the database using heuristic rules on sessionA single conversation or interaction with an AI coding agent, typically one run/launch content.

Architecture

SQLiteEmbedded relational database used as the primary session archive DB → Analytics Queries → RESTRepresentational State Transfer APIApplication Programming Interface → Frontend Charts
                  ↓
           Pricing Catalog (LiteLLMOpen-source LLM pricing catalog used for cost estimation + offline)
                  ↓
           Cost Calculator (cache-aware)
                  ↓
           Usage/Tracking APIApplication Programming Interface

APIApplication Programming Interface Contracts

GET /api/v1/analytics/summary

Response: Summary statistics (sessions, messages, tokens, costs)

GET /api/v1/analytics/activity

Query Parameters: since, until, granularity, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository Response: Activity time series

GET /api/v1/analytics/heatmap

Response: Heatmap data for the web UI

GET /api/v1/usage/summary

Response: Per-model cost breakdown, total spend, token counts

Data Models

Usage Stats

Field	Type	Description
session_id	TEXT	Session identifier
agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)	TEXT	Agent type
model	TEXT	Model name
input_tokens	INTEGER	Input token count
output_tokens	INTEGER	Output token count
cache_creation_tokens	INTEGER	Cache creation tokens
cache_read_tokens	INTEGER	Cache read tokens
cost_usd	REAL	Estimated cost in USD

Technical Decisions

Decision	Choice	Rationale
Pricing source	LiteLLMOpen-source LLM pricing catalog used for cost estimation catalog + offline fallback	Covers most models; works offline
Cost calculation	Cache-aware (creation + read tokens)	Reflects actual billing for providers with prompt caching
Timezone	Configurable per-query	Supports global users and teams
Session classification	ML classifier in DB	Distinguishes automated vs human-driven sessions

Risks and Unknowns

LiteLLMOpen-source LLM pricing catalog used for cost estimation APIApplication Programming Interface dependency for pricing updates
ML classifier accuracy varies by agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) type

Test Plan: Analytics & Cost Tracking

Scope

Tests cover activity heatmaps, token usage tracking, cost estimation, daily cost summaries, sessionA single conversation or interaction with an AI coding agent, typically one run/launch health signals, sessionA single conversation or interaction with an AI coding agent, typically one run/launch stats, timezone-aware bucketing, AI-generated insights, sessionA single conversation or interaction with an AI coding agent, typically one run/launch classification, and velocity metrics.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Activity heatmap computed over time range	Session data + time range	Heatmap data points
TC-2	Token usage tracked per sessionA single conversation or interaction with an AI coding agent, typically one run/launch and model	Parsed usage events	Correct token counts
TC-3	Cost estimated from pricing catalog	Token counts + model	Cost in USD
TC-4	Daily cost summary with per-model breakdown	Multiple sessions with usage	Grouped cost by day and model
TC-5	Session health signalA health or outcome indicator computed from session content (success/failure, tool health, context pressure) computation	Session messages	Signal scores
TC-6	Session stats with distribution metrics	Session data	Statistical distributions
TC-7	Timezone-aware date bucketing	UTC timestamps + timezone	Bucketed by local date
TC-8	Pricing match from LiteLLMOpen-source LLM pricing catalog used for cost estimation catalog	Model name + usage	Matched pricing

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-9	Activity query integration	Sessions with activity data	Correct activity metrics
TC-10	Usage rollup integration	Sessions with token data	Accurate cost rollups

Test Files

internal/activity/activity_test.go - Activity aggregation tests
internal/activity/query_test.go - Activity query tests
internal/activity/sessions_test.go - Session activity tests
internal/activity/usage_test.go - Usage activity tests
internal/db/usage_test.go - Usage database queries
internal/db/activity_test.go - Activity database queries
internal/db/activityreport_test.go - Activity report tests
internal/db/analytics_test.go - Analytics query tests
internal/db/pricing_test.go - Pricing match tests
internal/db/stats_test.go - Stats query tests
internal/db/trends_test.go - Trends query tests
internal/db/usage_perf_test.go - Usage performance tests
internal/pricing/litellm_test.go - LiteLLMOpen-source LLM pricing catalog used for cost estimation pricing tests
internal/server/activity_test.go - HTTP activity handler tests
internal/server/activity_report_test.go - Activity report handler tests
internal/server/analytics_test.go - Analytics handler tests
internal/server/usage_test.go - Usage handler tests
internal/service/usage_test.go - Service layer usage tests

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-11	No token data for sessionA single conversation or interaction with an AI coding agent, typically one run/launch	Cost shows as unavailable
TC-12	Model not in pricing catalog	Unpriced model flagged
TC-13	Empty sessionA single conversation or interaction with an AI coding agent, typically one run/launch data	Zero-filled results

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall compute and display activity heatmaps over configurable time ranges	TC-1, TC-9
FR-2MustThe system shall track token usage per sessionA single conversation or interaction with an AI coding agent, typically one run/launch and per model	TC-2, TC-10
FR-3MustThe system shall compute cost estimates using a pricing catalog	TC-3, TC-8
FR-4MustThe system shall provide daily cost summaries with per-model breakdowns	TC-4
FR-5MustThe system shall compute sessionA single conversation or interaction with an AI coding agent, typically one run/launch health signals (outcome, tool health, context pressure)	TC-5
FR-6MustThe system shall provide a sessionA single conversation or interaction with an AI coding agent, typically one run/launch stats endpoint with distribution metrics	TC-6
FR-7MustThe system shall support timezone-aware date bucketing	TC-7

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: PostgreSQLRelational database used as a shared sync target and read store Sync

Overview

The PostgreSQLRelational database used as a shared sync target and read store syncThe process of discovering new/changed session files and updating the database feature pushes sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from the local SQLiteEmbedded relational database used as the primary session archive archive to a shared PostgreSQLRelational database used as a shared sync target and read store instance, enabling team-wide dashboards and read-only queries. It supports incremental push with fingerprint-based change detection, named targets for multiple PGPostgreSQL instances, and read-only serving of the web UI from PostgreSQLRelational database used as a shared sync target and read store.

Stakeholders

Stakeholder	Interest
Engineering manager	Team-wide visibility into agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) usage
Team member	Access sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from PostgreSQLRelational database used as a shared sync target and read store-connected tools
Operator	Configure multiple PGPostgreSQL targets (work, archive)

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store incrementally	Must	The system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store incrementally
FR-2MustThe system shall support projectA named group of sessions, typically corresponding to a code repository filtering (include/exclude projects)	Must	The system shall support projectA named group of sessions, typically corresponding to a code repository filtering (include/exclude projects)
FR-3MustThe system shall use fingerprint-based change detection for incremental pushes	Must	The system shall use fingerprint-based change detection for incremental pushes
FR-4MustThe system shall support named PostgreSQLRelational database used as a shared sync target and read store targets (multiple destinations)	Must	The system shall support named PostgreSQLRelational database used as a shared sync target and read store targets (multiple destinations)
FR-5MustThe system shall serve the web UI read-only from PostgreSQLRelational database used as a shared sync target and read store	Must	The system shall serve the web UI read-only from PostgreSQLRelational database used as a shared sync target and read store
FR-6MustThe system shall support conflict detection based on owning machine	Must	The system shall support conflict detection based on owning machine
FR-7ShouldThe system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes	Should	The system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes
FR-8ShouldThe system shall support OS service management (systemd/launchd) for auto-push	Should	The system shall support OS service management (systemd/launchd) for auto-push
FR-9ShouldThe system shall support pricing syncThe process of discovering new/changed session files and updating the database from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store	Should	The system shall support pricing syncThe process of discovering new/changed session files and updating the database from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustPush must be idempotent; re-running produces the same state	Must	Consistency	Push must be idempotent; re-running produces the same state

Acceptance Criteria

FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store incrementally
- Given local SQLiteEmbedded relational database used as the primary session archive has sessionA single conversation or interaction with an AI coding agent, typically one run/launch data
- When agentsview pg push is run
- Then sessionA single conversation or interaction with an AI coding agent, typically one run/launch data is replicated to PostgreSQLRelational database used as a shared sync target and read store
FR-7ShouldThe system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes
- Given the watch daemon is running
- When new sessions are synced locally
- Then they are automatically pushed to PostgreSQLRelational database used as a shared sync target and read store

Open Questions

None.

Specification: PostgreSQLRelational database used as a shared sync target and read store Sync

Overview

The PostgreSQLRelational database used as a shared sync target and read store integration has two modes: push syncThe process of discovering new/changed session files and updating the database and read-only serve. Push syncThe process of discovering new/changed session files and updating the database (internal/postgres/push.go) incrementally copies sessions from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store using a fingerprint-based diff. Read-only serve (internal/postgres/store.go) implements db.Store for PostgreSQLRelational database used as a shared sync target and read store-backed queries. Named targets allow multiple PGPostgreSQL destinations.

Architecture

SQLiteEmbedded relational database used as the primary session archive DB → Push Engine (fingerprint diff) → PostgreSQLRelational database used as a shared sync target and read store
                  ↓
           Watch Daemon (fsnotifyGo library for filesystem event notification events)
                  ↓
           OS Service (systemd/launchd)

Data Models

Named PGPostgreSQL Target Config

Field	Type	Description
name	string	Target name (e.g. "work", "archive")
url	string	PostgreSQLRelational database used as a shared sync target and read store DSNData Source Name
machine_name	string	Identifier for this machine
exclude_projects	[]string	Projects to skip
schema	string	PGPostgreSQL schema name

APIApplication Programming Interface Contracts

POST /api/v1/push/pg

Request: {"target": "default"} Response: Push status

Sequences

Incremental Push

1. Query SQLiteEmbedded relational database used as the primary session archive for sessions with fingerprint > last_push_fingerprint
2. Batch insert/update into PostgreSQLRelational database used as a shared sync target and read store
3. Record max fingerprint for next push

Technical Decisions

Decision	Choice	Rationale
Change detection	Monotonic fingerprint column	O(1) incremental detection
Read serve	Implements `db.Store` interface	Same APIApplication Programming Interface handlers work for SQLiteEmbedded relational database used as the primary session archive, PGPostgreSQL, DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive
Conflict resolution	Machine-owner wins	Different machines may have different versions of same sessionA single conversation or interaction with an AI coding agent, typically one run/launch

Risks and Unknowns

Schema drift between SQLiteEmbedded relational database used as the primary session archive and PostgreSQLRelational database used as a shared sync target and read store on version upgrade

Test Plan: PostgreSQLRelational database used as a shared sync target and read store Sync

Scope

Tests cover incremental push from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store, projectA named group of sessions, typically corresponding to a code repository filtering, fingerprint-based change detection, named targets, read-only serve, conflict detection, watch mode, OS service management, and pricing syncThe process of discovering new/changed session files and updating the database.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Push syncs sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store	SQLiteEmbedded relational database used as the primary session archive sessionA single conversation or interaction with an AI coding agent, typically one run/launch data	PostgreSQLRelational database used as a shared sync target and read store has matching rows
TC-2	Fingerprint change detection identifies new/modified	Session fingerprint state	Correct incremental set
TC-3	Project filtering includes/excludes correctly	Include/exclude lists	Filtered push set
TC-4	Named target resolution correct	Config with named targets	Correct target selected
TC-5	Conflict detection by owning machine	Same sessionA single conversation or interaction with an AI coding agent, typically one run/launch from different machines	Conflict flagged

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-6	Full push lifecycle	Real PostgreSQLRelational database used as a shared sync target and read store instance	Data replicated correctly
TC-7	Watch mode pushes on file change	Running watch daemon	Auto-push on new sessionA single conversation or interaction with an AI coding agent, typically one run/launch
TC-8	Read-only serve from PostgreSQLRelational database used as a shared sync target and read store	PostgreSQLRelational database used as a shared sync target and read store with data	Web UI served from PGPostgreSQL

Test Files

internal/postgres/push_test.go - Push lifecycle tests
internal/postgres/push_pgtest_test.go - Push integration tests (PGPostgreSQL)
internal/postgres/push_fingerprint_test.go - Fingerprint tests
internal/postgres/push_window_test.go - Push window tests
internal/postgres/sync_test.go - Sync lifecycle tests
internal/postgres/schema_test.go - Schema management tests
internal/postgres/store_test.go - Store query tests
internal/postgres/sessions_test.go - Session query tests
internal/postgres/messages_test.go - Message query tests
internal/postgres/connect_test.go - Connection tests
internal/postgres/analytics_pgtest_test.go - Analytics PGPostgreSQL tests
internal/postgres/activityreport_pgtest_test.go - Activity report PGPostgreSQL tests
internal/postgres/curation_pgtest_test.go - Curation PGPostgreSQL tests
internal/postgres/pricing_pgtest_test.go - Pricing PGPostgreSQL tests

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-9	PostgreSQLRelational database used as a shared sync target and read store unreachable	Push fails with connect error
TC-10	Schema version mismatch	Migration applied or error reported
TC-11	Duplicate push (idempotency)	Same state, no duplicates

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to PostgreSQLRelational database used as a shared sync target and read store incrementally	TC-1, TC-6
FR-2MustThe system shall support projectA named group of sessions, typically corresponding to a code repository filtering (include/exclude projects)	TC-3
FR-3MustThe system shall use fingerprint-based change detection for incremental pushes	TC-2
FR-4MustThe system shall support named PostgreSQLRelational database used as a shared sync target and read store targets (multiple destinations)	TC-4
FR-5MustThe system shall serve the web UI read-only from PostgreSQLRelational database used as a shared sync target and read store	TC-8
FR-6MustThe system shall support conflict detection based on owning machine	TC-5
FR-7ShouldThe system shall provide a watch mode that auto-pushes on sessionA single conversation or interaction with an AI coding agent, typically one run/launch changes	TC-7

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive Mirror

Overview

The DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror pushes sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from the local SQLiteEmbedded relational database used as the primary session archive archive to a DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive database file, enabling portable analytics and read-only local serving. It also supports the QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients remote protocol for network access to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive, allowing remote querying of the sessionA single conversation or interaction with an AI coding agent, typically one run/launch mirror.

Stakeholders

Stakeholder	Interest
End user	Portable analytics file for data analysis
Power user	Remote access to sessionA single conversation or interaction with an AI coding agent, typically one run/launch data via QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients protocol
Analyst	SQL-based querying of sessionA single conversation or interaction with an AI coding agent, typically one run/launch data using DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Must	The system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive
FR-2MustThe system shall support incremental push with fingerprint-based change detection	Must	The system shall support incremental push with fingerprint-based change detection
FR-3MustThe system shall serve the web UI read-only from DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Must	The system shall serve the web UI read-only from DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive
FR-4MustThe system shall expose the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror over the QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients remote protocol	Must	The system shall expose the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror over the QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients remote protocol
FR-5MustThe system shall support dual DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive drivers (CGOC Go interoperability and pure Go)	Must	The system shall support dual DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive drivers (CGOC Go interoperability and pure Go)
FR-6ShouldThe system shall support projectA named group of sessions, typically corresponding to a code repository filtering	Should	The system shall support projectA named group of sessions, typically corresponding to a code repository filtering

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustQuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients server binds to loopback by default and requires a token	Must	Security	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients server binds to loopback by default and requires a token

Acceptance Criteria

FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive
- Given local SQLiteEmbedded relational database used as the primary session archive has sessionA single conversation or interaction with an AI coding agent, typically one run/launch data
- When agentsview duckdb push is run
- Then sessionA single conversation or interaction with an AI coding agent, typically one run/launch data is replicated to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive
FR-4MustThe system shall expose the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror over the QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients remote protocol
- Given the QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients server is running
- When a remote client connects with a valid token
- Then the client can query the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror

Open Questions

None.

Specification: DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive Mirror

Overview

The DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive integration mirrors SQLiteEmbedded relational database used as the primary session archive data to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive for portable analytics. It supports CGOC Go interoperability-based and pure Go (modernc) DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive drivers. The QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients protocol exposes the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive file over the network with token-based authentication. Read-only serve implements db.Store for DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive-backed queries.

Architecture

SQLiteEmbedded relational database used as the primary session archive DB → Push Engine (fingerprint diff) → DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive File
                                                  ↓
                                         QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients Server (remote protocol)
                                                  ↓
                                         Remote DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive Clients

Data Models

DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive Config

Field	Type	Description
path	string	Path to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive file
quack_bind	string	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients server bind address
quack_token	string	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients authentication token

Sequences

Push

1. Query SQLiteEmbedded relational database used as the primary session archive for sessions with fingerprint > last_push_fingerprint
2. Bulk insert into DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive using prepared statements
3. Record max fingerprint

Technical Decisions

Decision	Choice	Rationale
Driver	CGOC Go interoperability + modernc (pure Go) fallback	Platform compatibility
Protocol	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients	DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive-native remote protocol
Authentication	Bearer token	Simple, secure enough for local network

Risks and Unknowns

DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive driver compatibility across platforms
QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients protocol maturity and feature support

Test Plan: DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive Mirror

Scope

Tests cover push from SQLiteEmbedded relational database used as the primary session archive to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive, incremental push with fingerprinting, full rebuild, read-only serve, QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients remote protocol, dual driver support (CGOC Go interoperability and pure Go), and projectA named group of sessions, typically corresponding to a code repository filtering.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Push syncs sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	SQLiteEmbedded relational database used as the primary session archive sessionA single conversation or interaction with an AI coding agent, typically one run/launch data	DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive has matching rows
TC-2	Incremental push detects changed sessions	Modified sessionA single conversation or interaction with an AI coding agent, typically one run/launch fingerprints	Only changed data pushed
TC-3	Full rebuild creates complete DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror	All SQLiteEmbedded relational database used as the primary session archive data	Complete DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror
TC-4	Read-only serve returns query results	DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror	Query results returned

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-5	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients protocol remote query	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients server running	Remote query returns results
TC-6	Mirror watch detects file changes	Watch daemon running	Auto-push on change
TC-7	Store contract parity	SQLiteEmbedded relational database used as the primary session archive + DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive with same data	Identical query results

Test Files

internal/duckdb/push_bounded_test.go - Bounded push tests
internal/duckdb/sync_test.go - Sync lifecycle tests
internal/duckdb/sync_fastpath_test.go - Fast path syncThe process of discovering new/changed session files and updating the database tests
internal/duckdb/rebuild_test.go - Full rebuild tests
internal/duckdb/probe_test.go - Mirror probe tests
internal/duckdb/smoke_test.go - Smoke tests
internal/duckdb/store_test.go - Store query tests
internal/duckdb/store_contract_test.go - Store contract tests
internal/duckdb/connect_test.go - Connection tests
internal/duckdb/quack_smoke_duckdbtest_test.go - QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients protocol tests
internal/duckdb/quack_sql_test.go - QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients SQL tests
internal/duckdb/quack_url_form_duckdbtest_test.go - QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients URL tests
internal/duckdb/mirror_watch_test.go - Mirror watch tests

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-8	DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive file locked	Push waits or reports error
TC-9	Incompatible DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive driver version	Error reported
TC-10	QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients connection without token	Connection rejected

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall push sessionA single conversation or interaction with an AI coding agent, typically one run/launch data from SQLiteEmbedded relational database used as the primary session archive to DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	TC-1, TC-3
FR-2MustThe system shall support incremental push with fingerprint-based change detection	TC-2
FR-3MustThe system shall serve the web UI read-only from DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	TC-4
FR-4MustThe system shall expose the DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror over the QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients remote protocol	TC-5
FR-5MustThe system shall support dual DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive drivers (CGOC Go interoperability and pure Go)	TC-6

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Admin & Operations

Overview

The admin and operations features cover secret scanning across sessionA single conversation or interaction with an AI coding agent, typically one run/launch content, remote syncSyncing sessions from other machines via SSH or HTTP from other machines, export/import capabilities, AI-generated insights from sessionA single conversation or interaction with an AI coding agent, typically one run/launch data, and self-update functionality. These features support day-to-day administration and data portability.

Stakeholders

Stakeholder	Interest
End user	Export sessions, import from other tools, scan for leaked secrets
Operator	Remote syncThe process of discovering new/changed session files and updating the database from multiple machines, monitor for security issues
Security-conscious user	Detect accidentally committed APIApplication Programming Interface keys and tokens in sessionA single conversation or interaction with an AI coding agent, typically one run/launch content

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall scan sessionA single conversation or interaction with an AI coding agent, typically one run/launch content for secrets (APIApplication Programming Interface keys, tokens, passwords) using rule-based detection	Must	The system shall scan sessionA single conversation or interaction with an AI coding agent, typically one run/launch content for secrets (APIApplication Programming Interface keys, tokens, passwords) using rule-based detection
FR-2MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch export as HTML	Must	The system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch export as HTML
FR-3MustThe system shall support publishing sessions to GitHub Gists	Must	The system shall support publishing sessions to GitHub Gists
FR-4MustThe system shall support importing from Claude.ai and ChatGPT exports	Must	The system shall support importing from Claude.ai and ChatGPT exports
FR-5MustThe system shall support self-update via GitHub release check	Must	The system shall support self-update via GitHub release check
FR-6MustThe system shall support remote syncSyncing sessions from other machines via SSH or HTTP from other machines via SSHSecure Shell	Must	The system shall support remote syncSyncing sessions from other machines via SSH or HTTP from other machines via SSHSecure Shell
FR-7ShouldThe system shall support AI-generated insights (daily activity summaries, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) analysis)	Should	The system shall support AI-generated insights (daily activity summaries, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) analysis)
FR-8ShouldThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch health grades (A-F)	Should	The system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch health grades (A-F)
FR-9ShouldThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch starring and pinning	Should	The system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch starring and pinning

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustSecrets scan results are stored locally and not sent externally	Must	Security	Secrets scan results are stored locally and not sent externally

Acceptance Criteria

FR-1MustThe system shall scan sessionA single conversation or interaction with an AI coding agent, typically one run/launch content for secrets (APIApplication Programming Interface keys, tokens, passwords) using rule-based detection
- Given sessionA single conversation or interaction with an AI coding agent, typically one run/launch content contains an APIApplication Programming Interface key pattern
- When a secret scan is run
- Then the finding is recorded and flagged in the UI
FR-3MustThe system shall support publishing sessions to GitHub Gists
- Given a sessionA single conversation or interaction with an AI coding agent, typically one run/launch
- When "Publish to Gist" is selected
- Then the sessionA single conversation or interaction with an AI coding agent, typically one run/launch is published as a GitHub Gist
FR-6MustThe system shall support remote syncSyncing sessions from other machines via SSH or HTTP from other machines via SSHSecure Shell
- Given a remote host is configured
- When agentsview syncThe process of discovering new/changed session files and updating the database --host <host> is run
- Then sessions from the remote host are synced

Open Questions

What secret patterns should be included in the default ruleset?

Specification: Admin & Operations

Overview

Admin features are implemented across several internal packages: internal/secrets/ for secret scanning, internal/export/ for sessionA single conversation or interaction with an AI coding agent, typically one run/launch export, internal/importer/ for importing from other tools, internal/insightAn AI-generated summary or analysis of session data/ for AI-generated insights, internal/update/ for self-updates, internal/signals/ for health signals, and internal/remotesync/ for remote syncSyncing sessions from other machines via SSH or HTTP.

Architecture

Session Content
  ├→ Secret Scanner (rule-based patterns)
  ├→ Exporter (HTML, Gist)
  ├→ Insight Generator (AI agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.))
  └→ Health Signal Computer (heuristic rules)

Data Models

Secret Finding

Field	Type	Description
id	TEXT	Finding identifier
session_id	TEXT	Source sessionA single conversation or interaction with an AI coding agent, typically one run/launch
type	TEXT	Secret type (api_key, token, password)
match	TEXT	Redacted matched content
line	INTEGER	Line number
severity	TEXT	Severity level

Insight

Field	Type	Description
id	TEXT	Insight identifier
type	TEXT	daily, agent_analysis, canned
title	TEXT	Insight title
content	TEXT	Generated insightAn AI-generated summary or analysis of session data body
model	TEXT	Model used for generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files
created_at	TEXT	Generation timestamp

APIApplication Programming Interface Contracts

GET /api/v1/secrets

Response: List of secret findings with sessionA single conversation or interaction with an AI coding agent, typically one run/launch context

POST /api/v1/secrets/scan

Response: SSEServer-Sent Events stream of scan progress

POST /api/v1/insights/generate

Response: SSEServer-Sent Events stream of generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files progress

GET /api/v1/sessions/{id}/export

Response: HTML export of the sessionA single conversation or interaction with an AI coding agent, typically one run/launch

Sequences

Secret Scanning

1. Walk all sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages
2. Apply regex patterns for each secret type
3. Redact matched content
4. Store findings in secrets table
5. Notify UI via SSEServer-Sent Events

Technical Decisions

Decision	Choice	Rationale
Insight generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files	Uses configured agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)	Leverages existing LLM infrastructure
Secret detection	Rule-based regex	Fast, no ML dependency
Export format	HTML with embedded styling	Self-contained, portable
Remote syncThe process of discovering new/changed session files and updating the database	SSHSecure Shell transport	Ubiquitous, no additional infrastructure

Risks and Unknowns

Insight generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files cost and latency
False positives in secret scanning

Test Plan: Admin & Operations

Scope

Tests cover secret scanning, sessionA single conversation or interaction with an AI coding agent, typically one run/launch export (HTML, GitHub Gist), Claude.ai/ChatGPT import, self-update, remote syncSyncing sessions from other machines via SSH or HTTP via SSHSecure Shell, AI-generated insights, sessionA single conversation or interaction with an AI coding agent, typically one run/launch health grades, and starring/pinning.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Secret scanning detects APIApplication Programming Interface key patterns	Session content with secrets	Findings recorded with redacted matches
TC-2	Session export produces valid HTML	Session data	HTML output
TC-3	Import from Claude.ai/ChatGPT	Export archive	Sessions imported into SQLiteEmbedded relational database used as the primary session archive
TC-4	Self-update check	Current version + remote	Update available/not available
TC-5	Remote syncThe process of discovering new/changed session files and updating the database via SSHSecure Shell	SSHSecure Shell host config	Sessions synced from remote
TC-6	Secret ruleset version handling	Ruleset version	Correct rule application

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-7	Full remote syncSyncing sessions from other machines via SSH or HTTP lifecycle	SSHSecure Shell configured	Sessions transferred and indexed
TC-8	Canonical JSON export/import	Session data	Round-trip fidelity
TC-9	Insight generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files from sessionA single conversation or interaction with an AI coding agent, typically one run/launch data	Sessions with messages	Structured insights produced

Test Files

internal/secrets/secrets_test.go - Secret scanning tests
internal/secrets/rules_test.go - Ruleset tests
internal/secrets/bench_test.go - Scanning performance benchmarks
internal/export/canonical_json_test.go - Canonical JSON export/import
internal/export/pricing_test.go - Pricing export tests
internal/export/project_identity_test.go - Project identity export
internal/importer/importer_test.go - Import tests
internal/importer/assets_test.go - Import asset tests
internal/importer/zip_test.go - Zip import tests
internal/update/update_test.go - Self-update tests
internal/remotesync/archive_test.go - Remote syncThe process of discovering new/changed session files and updating the database archive tests
internal/remotesync/http_test.go - Remote syncThe process of discovering new/changed session files and updating the database HTTP tests
internal/remotesync/manifest_test.go - Manifest tests
internal/remotesync/mirror_test.go - Mirror tests
internal/remotesync/resolve_test.go - Host resolution tests
internal/remotesync/cleanup_registry_test.go - Cleanup registry tests
internal/remotesync/failure_test.go - Failure handling tests
internal/remotesync/import_test.go - Import tests
internal/remotesync/migration_test.go - Migration tests
internal/ssh/ssh_test.go - SSHSecure Shell connection tests
internal/ssh/classify_test.go - SSHSecure Shell classification tests
internal/ssh/extract_test.go - SSHSecure Shell path extraction tests
internal/ssh/resolve_test.go - SSHSecure Shell resolution tests
internal/ssh/transfer_test.go - SSHSecure Shell transfer tests
internal/insightAn AI-generated summary or analysis of session data/generate_test.go - Insight generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files tests
internal/insightAn AI-generated summary or analysis of session data/prompt_test.go - Insight prompt tests
internal/insightAn AI-generated summary or analysis of session data/summary_test.go - Insight summary tests
internal/db/secret_findings_test.go - Secret findings DB tests

Edge Cases and Failure Scenarios

ID	Scenario	Expected Behavior
TC-10	SSHSecure Shell host unreachable	Sync fails with connect error
TC-11	No new version available	Update reports up-to-date

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall scan sessionA single conversation or interaction with an AI coding agent, typically one run/launch content for secrets (APIApplication Programming Interface keys, tokens, passwords) using rule-based detection	TC-1, TC-6
FR-2MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch export as HTML	TC-2
FR-4MustThe system shall support importing from Claude.ai and ChatGPT exports	TC-3, TC-8
FR-5MustThe system shall support self-update via GitHub release check	TC-4
FR-6MustThe system shall support remote syncSyncing sessions from other machines via SSH or HTTP from other machines via SSHSecure Shell	TC-5, TC-7
FR-7ShouldThe system shall support AI-generated insights (daily activity summaries, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) analysis)	TC-9

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: MCPModel Context Protocol Server

Overview

The MCPModel Context Protocol (Model Context Protocol) server exposes agentsview's sessionA single conversation or interaction with an AI coding agent, typically one run/launch data as read-only tools for AI coding assistants. It supports stdio and StreamableHTTP transports, providing tools for searching sessions, listing sessions, viewing sessionA single conversation or interaction with an AI coding agent, typically one run/launch details and messages, content search, and usage summaries.

Stakeholders

Stakeholder	Interest
AI agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) user	Query sessionA single conversation or interaction with an AI coding agent, typically one run/launch data directly from within an AI coding assistant
Developer	Integrate agentsview data into MCPModel Context Protocol-compatible tools

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall provide an MCPModel Context Protocol server with stdio transport	Must	The system shall provide an MCPModel Context Protocol server with stdio transport
FR-2MustThe system shall provide an MCPModel Context Protocol server with StreamableHTTP transport	Must	The system shall provide an MCPModel Context Protocol server with StreamableHTTP transport
FR-3MustThe system shall expose a `search_sessions` tool for FTS5Full-Text Search version 5 search	Must	The system shall expose a `search_sessions` tool for FTS5Full-Text Search version 5 search
FR-4MustThe system shall expose a `list_sessions` tool for sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing	Must	The system shall expose a `list_sessions` tool for sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing
FR-5MustThe system shall expose a `get_session_overview` tool for sessionA single conversation or interaction with an AI coding agent, typically one run/launch details	Must	The system shall expose a `get_session_overview` tool for sessionA single conversation or interaction with an AI coding agent, typically one run/launch details
FR-6MustThe system shall expose a `get_messages` tool for messageAn individual turn in a session (user prompt, assistant response, tool result) retrieval	Must	The system shall expose a `get_messages` tool for messageAn individual turn in a session (user prompt, assistant response, tool result) retrieval
FR-7MustThe system shall expose a `search_content` tool for content search	Must	The system shall expose a `search_content` tool for content search
FR-8MustThe system shall expose a `get_usage_summary` tool for usage data	Must	The system shall expose a `get_usage_summary` tool for usage data

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustMCPModel Context Protocol server operates on existing auth; no additional credentials required	Must	Security	MCPModel Context Protocol server operates on existing auth; no additional credentials required

Acceptance Criteria

FR-1MustThe system shall provide an MCPModel Context Protocol server with stdio transport
- Given agentsview is running
- When agentsview mcp is run
- Then an MCPModel Context Protocol server starts on stdio, providing the defined tools

Open Questions

None.

Specification: MCPModel Context Protocol Server

Overview

The MCPModel Context Protocol server (internal/mcp/) implements the Model Context Protocol using the Go MCPModel Context Protocol SDK. It registers six read-only tools that wrap the existing sessionA single conversation or interaction with an AI coding agent, typically one run/launch service interface. The server supports two transport modes: stdio for direct subprocess invocation and StreamableHTTP for RESTRepresentational State Transfer-based MCPModel Context Protocol clients.

Architecture

MCPModel Context Protocol Client (AI Assistant) ↔ MCPModel Context Protocol Server (agentsview)
                                 ↓
                          Internal/Service Backend
                                 ↓
                          SQLiteEmbedded relational database used as the primary session archive / PGPostgreSQL / DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive

APIApplication Programming Interface Contracts

Tools

Tool	Description	Parameters
search_sessions	Full-text search across sessions	query, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository, limit
list_sessions	List sessions with filters	agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), projectA named group of sessions, typically corresponding to a code repository, limit, offset
get_session_overview	Get sessionA single conversation or interaction with an AI coding agent, typically one run/launch summary	session_id
get_messages	Get messages for a sessionA single conversation or interaction with an AI coding agent, typically one run/launch	session_id, limit, offset
search_content	Search within messageAn individual turn in a session (user prompt, assistant response, tool result) content	query, session_id, mode
get_usage_summary	Get usage/cost summary	since, until, agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)

Sequences

MCPModel Context Protocol Tool Invocation

Client → JSON-RPC Request → MCPModel Context Protocol Server → Service Backend → Response

Technical Decisions

Decision	Choice	Rationale
SDK	Go MCPModel Context Protocol SDK (modelcontextprotocol/go-sdk)	Official SDK, spec-compliant
Transports	stdio + StreamableHTTP	Covers local AI tool integration and remote clients
Architecture	Thin wrapper over service layer	Reuses existing query logic, no data duplication

Risks and Unknowns

MCPModel Context Protocol protocol version compatibility as the spec evolves

Test Plan: MCPModel Context Protocol Server

Scope

Tests cover MCPModel Context Protocol server startup with stdio and StreamableHTTP transports, tool definitions for search_sessions, list_sessions, get_session_overview, get_messages, search_content, get_usage_summary, and tool invocation.

Unit Tests

ID	Description	Input	Expected Output
TC-1	MCPModel Context Protocol server starts with stdio transport	Server config	Server listening on stdio
TC-2	MCPModel Context Protocol server starts with StreamableHTTP transport	Server config	HTTP endpoint available
TC-3	Tool definitions are correctly shaped	Tool definitions	Valid MCPModel Context Protocol tool shapes
TC-4	search_sessions tool	Search query	Ranked sessionA single conversation or interaction with an AI coding agent, typically one run/launch results
TC-5	list_sessions tool	Filter params	Session list
TC-6	get_session_overview tool	Session ID	Session details
TC-7	get_messages tool	Session ID	Message list

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-8	Full MCPModel Context Protocol tool invocation cycle	Server running	Tools execute and return

Test Files

internal/mcp/server_test.go - Server lifecycle tests
internal/mcp/shape_test.go - Tool shape definition tests
internal/mcp/tools_test.go - Tool invocation tests

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall provide an MCPModel Context Protocol server with stdio transport	TC-1
FR-2MustThe system shall provide an MCPModel Context Protocol server with StreamableHTTP transport	TC-2
FR-3MustThe system shall expose a `search_sessions` tool for FTS5Full-Text Search version 5 search	TC-3, TC-4
FR-4MustThe system shall expose a `list_sessions` tool for sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing	TC-3, TC-5
FR-5MustThe system shall expose a `get_session_overview` tool for sessionA single conversation or interaction with an AI coding agent, typically one run/launch details	TC-3, TC-6
FR-6MustThe system shall expose a `get_messages` tool for messageAn individual turn in a session (user prompt, assistant response, tool result) retrieval	TC-3, TC-7
FR-7MustThe system shall expose a `search_content` tool for content search	TC-3, TC-4
FR-8MustThe system shall expose a `get_usage_summary` tool for usage data	TC-3

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: RESTRepresentational State Transfer APIApplication Programming Interface & Web Frontend

Overview

The RESTRepresentational State Transfer APIApplication Programming Interface and web frontend provide the primary user interface for agentsview. The APIApplication Programming Interface is built with the HumaOpenAPI 3.1 REST framework for Go framework (OpenAPI 3.1) and exposes endpoints for sessions, messages, search, analytics, usage, and administration. The frontend is a Svelte 5Frontend framework using runes for reactivity SPASingle Page Application embedded in the Go binary, featuring sessionA single conversation or interaction with an AI coding agent, typically one run/launch browsing, analytics dashboard, usage tracking, and settings.

Stakeholders

Stakeholder	Interest
End user	Browse, search, and interact with sessionA single conversation or interaction with an AI coding agent, typically one run/launch data through a web UI
APIApplication Programming Interface consumer	Integrate with agentsview via RESTRepresentational State Transfer APIApplication Programming Interface
Developer	Build on top of agentsview's OpenAPI schema

Functional Requirements

ID	Priority	Requirement
FR-1MustThe system shall provide a RESTRepresentational State Transfer APIApplication Programming Interface with OpenAPI 3.1 specification	Must	The system shall provide a RESTRepresentational State Transfer APIApplication Programming Interface with OpenAPI 3.1 specification
FR-2MustThe system shall serve a Svelte 5Frontend framework using runes for reactivity SPASingle Page Application embedded in the Go binary	Must	The system shall serve a Svelte 5Frontend framework using runes for reactivity SPASingle Page Application embedded in the Go binary
FR-3MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing with rich filtering and cursor pagination	Must	The system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing with rich filtering and cursor pagination
FR-4MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch detail view with full messageAn individual turn in a session (user prompt, assistant response, tool result) history	Must	The system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch detail view with full messageAn individual turn in a session (user prompt, assistant response, tool result) history
FR-5MustThe system shall provide an analytics dashboard with charts and metrics	Must	The system shall provide an analytics dashboard with charts and metrics
FR-6MustThe system shall provide a usage/cost tracking page	Must	The system shall provide a usage/cost tracking page
FR-7MustThe system shall provide an activity/concurrency report page	Must	The system shall provide an activity/concurrency report page
FR-8MustThe system shall provide a full-text search page	Must	The system shall provide a full-text search page
FR-9MustThe system shall provide SSEServer-Sent Events for live updates	Must	The system shall provide SSEServer-Sent Events for live updates
FR-10MustThe system shall support keyboard navigation (j/k, Cmd+K search, ? shortcuts)	Must	The system shall support keyboard navigation (j/k, Cmd+K search, ? shortcuts)
FR-11MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch starring and trash/restore	Must	The system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch starring and trash/restore
FR-12MustThe system shall support messageAn individual turn in a session (user prompt, assistant response, tool result) pinning	Must	The system shall support messageAn individual turn in a session (user prompt, assistant response, tool result) pinning
FR-13ShouldThe system shall provide a recent edits feed showing files changed by agents	Should	The system shall provide a recent edits feed showing files changed by agents
FR-14ShouldThe system shall support settings management via the web UI	Should	The system shall support settings management via the web UI

Non-Functional Requirements

ID	Priority	Category	Requirement
NFR-1MustAPIApplication Programming Interface rejects requests with unrecognized Host headers (DNS rebinding protection)	Must	Security	APIApplication Programming Interface rejects requests with unrecognized Host headers (DNS rebinding protection)
NFR-2MustServer binds to 127.0.0.1 by default	Must	Security	Server binds to 127.0.0.1 by default
NFR-3ShouldFrontend bundle is embedded for single-binary deployment	Should	Performance	Frontend bundle is embedded for single-binary deployment

Acceptance Criteria

FR-2MustThe system shall serve a Svelte 5Frontend framework using runes for reactivity SPASingle Page Application embedded in the Go binary
- Given the server is running
- When a browser navigates to http://127.0.0.1:8080
- Then the Svelte SPASingle Page Application is served and interactive
FR-10MustThe system shall support keyboard navigation (j/k, Cmd+K search, ? shortcuts)
- Given the sessionA single conversation or interaction with an AI coding agent, typically one run/launch list is displayed
- When j/k keys are pressed
- Then the selection moves up/down in the list

Open Questions

Should there be a mobile-responsive layout or is desktop-only sufficient?

Specification: RESTRepresentational State Transfer APIApplication Programming Interface & Web Frontend

Overview

The RESTRepresentational State Transfer APIApplication Programming Interface is registered in internal/server/huma_route_groups.go using the HumaOpenAPI 3.1 REST framework for Go v2 framework, which automatically generates an OpenAPI 3.1 schema. The frontend is a Svelte 5Frontend framework using runes for reactivity SPASingle Page Application with runes-based reactivity, built with Vite+ and TypeScript. The SPASingle Page Application is embedded into the Go binary during build for single-binary deployment.

Architecture

Browser → HTTP Server (HumaOpenAPI 3.1 REST framework for Go + Chi) → Service Backend → SQLiteEmbedded relational database used as the primary session archive/PGPostgreSQL/DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive
             ↓
        Embedded SPASingle Page Application (frontend/dist/)
             ↓
        SSEServer-Sent Events Broadcaster (live updates)

Frontend Component Tree

App.svelte
├── ThreeColumnLayout
│   ├── AppHeader (search, nav)
│   ├── SessionList (sidebar)
│   │   └── SessionItem
│   ├── MessageList (content)
│   │   ├── MessageContent
│   │   ├── ToolBlock / CallGroup / ParallelGroup
│   │   ├── ThinkingBlock / CodeBlock / MermaidBlock
│   │   └── ActivityLane
│   └── SessionVitals (right panel)
├── AnalyticsPage
├── UsagePage
├── ActivityPage
├── TrendsPage
├── InsightsPage
├── PinnedPage
├── TrashPage
├── RecentEditsPage
└── SettingsPage

APIApplication Programming Interface Contracts

Core Routes (OpenAPI 3.1)

Method	Path	Description
GET	/api/v1/sessions	List sessions
GET	/api/v1/sessions/{id}	Get sessionA single conversation or interaction with an AI coding agent, typically one run/launch detail
GET	/api/v1/sessions/{id}/messages	List messages
GET	/api/v1/search	Full-text search
GET	/api/v1/analytics/summary	Analytics summary
GET	/api/v1/usage/summary	Usage summary
GET	/events	SSEServer-Sent Events events

Sequences

SPASingle Page Application Load

1. Browser requests /
2. Server serves index.html with embedded SPASingle Page Application
3. SPASingle Page Application loads and calls GET /api/v1/sessions for initial data
4. SPASingle Page Application opens SSEServer-Sent Events connection to /events for live updates

Technical Decisions

Decision	Choice	Rationale
APIApplication Programming Interface framework	HumaOpenAPI 3.1 REST framework for Go v2	OpenAPI 3.1 native, code-first
Frontend framework	Svelte 5Frontend framework using runes for reactivity (runes)	Lightweight, fast, reactive
Embedding	Build-time copy of frontend/dist	Single binary deployment
SSEServer-Sent Events	/events endpoint with Broadcaster	Real-time updates without polling
Routing	Client-side store-based router	SPASingle Page Application navigation without page reloads
i18n	Paraglidei18n framework used in the Svelte frontend for message catalogs JS + inlang	Type-safe messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs

Risks and Unknowns

SPASingle Page Application bundle size growth over time
Browser compatibility with Svelte 5Frontend framework using runes for reactivity runes

Test Plan: RESTRepresentational State Transfer APIApplication Programming Interface & Web Frontend

Scope

Tests cover RESTRepresentational State Transfer APIApplication Programming Interface endpoints, Svelte SPASingle Page Application rendering, sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing/filtering/pagination, sessionA single conversation or interaction with an AI coding agent, typically one run/launch detail view, analytics dashboard, usage tracking, activity reports, full-text search UI, SSEServer-Sent Events live updates, keyboard navigation, starring/trash, messageAn individual turn in a session (user prompt, assistant response, tool result) pinning, recent edits feed, and settings management.

Unit Tests

ID	Description	Input	Expected Output
TC-1	Session list endpoint with cursor pagination	Filter params + cursor	Paginated sessionA single conversation or interaction with an AI coding agent, typically one run/launch list
TC-2	Session detail returns full messageAn individual turn in a session (user prompt, assistant response, tool result) history	Session ID	Complete messageAn individual turn in a session (user prompt, assistant response, tool result) tree
TC-3	SSEServer-Sent Events stream sends live updates	Sync event	Event received by client
TC-4	Frontend sessionA single conversation or interaction with an AI coding agent, typically one run/launch list renders correctly	Session data array	Rendered list items
TC-5	Frontend messageAn individual turn in a session (user prompt, assistant response, tool result) content renders correctly	Message data	Rendered messages
TC-6	Frontend analytics dashboard renders	Analytics data	Charts and metrics displayed
TC-7	Frontend usage page renders	Usage data	Cost breakdown displayed
TC-8	Keyboard navigation works	j/k keypresses	Selection moves

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-9	Frontend-backend full integration	Server running	SPASingle Page Application loads and queries APIApplication Programming Interface
TC-10	E2E sessionA single conversation or interaction with an AI coding agent, typically one run/launch browsing	Test data	Full browse flow works
TC-11	E2E search flow	Indexed sessions	Search results displayed

Test Files

internal/server/sessions_test.go - Session APIApplication Programming Interface handler tests
internal/server/session_mgmt_test.go - Session management tests
internal/server/session_usage_test.go - Session usage APIApplication Programming Interface tests
internal/server/session_stats_test.go - Session stats APIApplication Programming Interface tests
internal/server/search_test.go - Search APIApplication Programming Interface tests
internal/server/analytics_test.go - Analytics APIApplication Programming Interface tests
internal/server/activity_test.go - Activity APIApplication Programming Interface tests
internal/server/usage_test.go - Usage APIApplication Programming Interface tests
internal/server/server_test.go - Server lifecycle tests
internal/server/auth_test.go - Auth middleware tests
internal/server/middleware_test.go - Middleware tests
internal/server/export_test.go - Export handler tests
internal/server/starred_test.go - Starred sessionA single conversation or interaction with an AI coding agent, typically one run/launch tests
internal/server/pins_test.go - Pinned messageAn individual turn in a session (user prompt, assistant response, tool result) tests
internal/server/spa_test.go - SPASingle Page Application serving tests
internal/server/broadcaster_test.go - SSEServer-Sent Events broadcaster tests
internal/server/huma_routes_sessions_test.go - Session route tests
frontend/src/lib/api/client.test.ts - APIApplication Programming Interface client tests
frontend/src/lib/api/runtime.test.ts - Runtime tests
frontend/src/lib/stores/sessions.test.ts - Session store tests
frontend/src/lib/stores/search.test.ts - Search store tests
frontend/src/lib/stores/analytics.test.ts - Analytics store tests
frontend/src/lib/stores/usage.test.ts - Usage store tests
frontend/src/lib/stores/activity.test.ts - Activity store tests
frontend/src/lib/components/sidebar/SessionList.test.ts - Session list component
frontend/src/lib/components/content/MessageContent.test.ts - Message content component
frontend/src/lib/components/analytics/AnalyticsPage.test.ts - Analytics page component
frontend/src/lib/components/usage/UsagePage.test.ts - Usage page component
frontend/e2e/sessionA single conversation or interaction with an AI coding agent, typically one run/launch-list.spec.ts - Session list e2e
frontend/e2e/usage.spec.ts - Usage page e2e
frontend/e2e/navigation.spec.ts - Navigation e2e

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall provide a RESTRepresentational State Transfer APIApplication Programming Interface with OpenAPI 3.1 specification	TC-1
FR-2MustThe system shall serve a Svelte 5Frontend framework using runes for reactivity SPASingle Page Application embedded in the Go binary	TC-9
FR-3MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch listing with rich filtering and cursor pagination	TC-1
FR-4MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch detail view with full messageAn individual turn in a session (user prompt, assistant response, tool result) history	TC-2
FR-5MustThe system shall provide an analytics dashboard with charts and metrics	TC-6
FR-6MustThe system shall provide a usage/cost tracking page	TC-7
FR-8MustThe system shall provide a full-text search page	TC-11
FR-9MustThe system shall provide SSEServer-Sent Events for live updates	TC-3
FR-10MustThe system shall support keyboard navigation (j/k, Cmd+K search, ? shortcuts)	TC-8
FR-11MustThe system shall support sessionA single conversation or interaction with an AI coding agent, typically one run/launch starring and trash/restore	TC-1
FR-12MustThe system shall support messageAn individual turn in a session (user prompt, assistant response, tool result) pinning	TC-2

Vocabulary

Domain Terms

Technical Terms

Term	Definition
CGOC Go interoperability	Go's mechanism for calling C code, required for the sqlite3 driver
ClickHouseColumnar analytics database supported as a remote mirror and read store	Columnar analytics database supported as a remote mirror and read store
cobraCLI framework for Go	CLICommand Line Interface framework for Go
CockroachDBPostgreSQL-compatible distributed database supported as a shared-database target	PostgreSQLRelational database used as a shared sync target and read store-compatible distributed database supported as a shared-database target
CWDCurrent Working Directory, used for sync path filtering	Current Working Directory, used for syncThe process of discovering new/changed session files and updating the database path filtering
DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive	Embedded analytics database used as a local single-file mirror of the SQLiteEmbedded relational database used as the primary session archive archive
fsnotifyGo library for filesystem event notification	Go library for filesystem event notification
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive virtual table module for full-text indexing and search
golangci-lintGo linter aggregator	Go linter aggregator
HumaOpenAPI 3.1 REST framework for Go	OpenAPI 3.1 RESTRepresentational State Transfer framework for Go
kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend	Shared UI component library (@kenn-io/kit-uiShared UI component library (@kenn-io/kit-ui) used in the frontend) used in the frontend
LiteLLMOpen-source LLM pricing catalog used for cost estimation	Open-source LLM pricing catalog used for cost estimation
MCPModel Context Protocol	Model Context Protocol, a protocol for AI tools to expose capabilities
NilAwayGo nil pointer analysis tool	Go nil pointer analysis tool
Paraglidei18n framework used in the Svelte frontend for message catalogs	i18n framework used in the Svelte frontend for messageAn individual turn in a session (user prompt, assistant response, tool result) catalogs
pgxPostgreSQL driver for Go	PostgreSQLRelational database used as a shared sync target and read store driver for Go
PostgreSQLRelational database used as a shared sync target and read store	Relational database used as a shared syncThe process of discovering new/changed session files and updating the database target and read store
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion, a method for merging FTS5Full-Text Search version 5 and semantic search results
SQLiteEmbedded relational database used as the primary session archive	Embedded relational database used as the primary sessionA single conversation or interaction with an AI coding agent, typically one run/launch archive
sqlite-vecSQLite extension for vector similarity search	SQLiteEmbedded relational database used as the primary session archive extension for vector similarity search
SSEServer-Sent Events	Server-Sent Events, used for real-time UI updates
Svelte 5Frontend framework using runes for reactivity	Frontend framework using runes for reactivity
TauriDesktop application framework wrapping web UIs	Desktop application framework wrapping web UIs
testifyGo testing library with assertions and mocking	Go testing library with assertions and mocking
TOMLTom's Obvious Minimal Language, used for configuration files	Tom's Obvious Minimal Language, used for configuration files

Acronyms and Abbreviations

Abbreviation	Expansion
ADRArchitecture Decision Record	Architecture Decision Record
APIApplication Programming Interface	Application Programming Interface
CGOC Go interoperability	C Go interoperability
CI/CDContinuous Integration / Continuous Deployment	Continuous Integration / Continuous Deployment
CLICommand Line Interface	Command Line Interface
CORSCross-Origin Resource Sharing	Cross-Origin Resource Sharing
CSPContent Security Policy	Content Security Policy
CRUDCreate, Read, Update, Delete	Create, Read, Update, Delete
DDLData Definition Language	Data Definition Language
DMGApple Disk Image	Apple Disk Image
DSNData Source Name	Data Source Name
FTSFull-Text Search	Full-Text Search
FTS5Full-Text Search version 5	Full-Text Search version 5
IDEIntegrated Development Environment	Integrated Development Environment
LOTRLLM Organized Tree of Retrievals (from internal/insight)	LLM Organized Tree of Retrievals (from internal/insightAn AI-generated summary or analysis of session data)
MCPModel Context Protocol	Model Context Protocol
OTelOpenTelemetry	OpenTelemetry
PGPostgreSQL	PostgreSQLRelational database used as a shared sync target and read store
RESTRepresentational State Transfer	Representational State Transfer
RRFReciprocal Rank Fusion	Reciprocal Rank Fusion
S3Simple Storage Service (Amazon S3-compatible)	Simple Storage Service (Amazon S3Simple Storage Service (Amazon S3-compatible)-compatible)
SHMShared Memory	Shared Memory
SPASingle Page Application	Single Page Application
SSEServer-Sent Events	Server-Sent Events
SSHSecure Shell	Secure Shell
TUITerminal User Interface	Terminal User Interface
WALWrite-Ahead Logging	Write-Ahead Logging

Term	Definition
agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)	An AI coding tool that produces sessionA single conversation or interaction with an AI coding agent, typically one run/launch files (Claude, Codex, Cursor, etc.)
artifactA normalized, versioned session payload exchanged between machines via artifact folder sync	A normalized, versioned sessionA single conversation or interaction with an AI coding agent, typically one run/launch payload exchanged between machines via artifactA normalized, versioned session payload exchanged between machines via artifact folder sync folder syncThe process of discovering new/changed session files and updating the database
checkpointA durable progress marker recording how far a sync, parse, export, or upload job has advanced	A durable progress marker recording how far a syncThe process of discovering new/changed session files and updating the database, parse, export, or upload job has advanced
compactionAn agent-side summarization of conversation context to reclaim window space, tracked as a session health signal	An agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-side summarization of conversation context to reclaim window space, tracked as a sessionA single conversation or interaction with an AI coding agent, typically one run/launch health signalA health or outcome indicator computed from session content (success/failure, tool health, context pressure)
embeddingA vector representation of text used for semantic search	A vector representation of text used for semantic search
FTS5Full-Text Search version 5	SQLiteEmbedded relational database used as the primary session archive Full-Text Search version 5, used for messageAn individual turn in a session (user prompt, assistant response, tool result) content search
generationA versioned batch of derived data, either one embedding index built with a specific model and dimensions or one accepted batch of raw-synced source files	A versioned batch of derived data, either one embeddingA vector representation of text used for semantic search index built with a specific model and dimensions or one accepted batch of raw-synced source files
harnessThe runtime that executes an agent and persists its session files, such as DeepSeek Harness	The runtime that executes an agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) and persists its sessionA single conversation or interaction with an AI coding agent, typically one run/launch files, such as DeepSeek Harness
insightAn AI-generated summary or analysis of session data	An AI-generated summary or analysis of sessionA single conversation or interaction with an AI coding agent, typically one run/launch data
messageAn individual turn in a session (user prompt, assistant response, tool result)	An individual turn in a sessionA single conversation or interaction with an AI coding agent, typically one run/launch (user prompt, assistant response, tool result)
parse diffThe difference between two parser runs, used to detect incremental changes	The difference between two parserCode that reads an agent-specific session file format and extracts structured data runs, used to detect incremental changes
parserCode that reads an agent-specific session file format and extracts structured data	Code that reads an agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.)-specific sessionA single conversation or interaction with an AI coding agent, typically one run/launch file format and extracts structured data
pollerThe interval-driven background scheduler that runs periodic jobs such as sync and maintenance	The interval-driven background scheduler that runs periodic jobs such as syncThe process of discovering new/changed session files and updating the database and maintenance
projectA named group of sessions, typically corresponding to a code repository	A named group of sessions, typically corresponding to a code repository
project identityThe git remote + worktree mapping used to disambiguate projects	The git remote + worktreeA git working tree (main or linked checkout) used with mapping rules to attribute sessions to projects mapping used to disambiguate projects
pull quoteA notable excerpt extracted from session messages, used in reports	A notable excerpt extracted from sessionA single conversation or interaction with an AI coding agent, typically one run/launch messages, used in reports
QuackDuckDB extension and remote protocol for serving a DuckDB mirror over the network to trusted clients	DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive extension and remote protocol for serving a DuckDBEmbedded analytics database used as a local single-file mirror of the SQLite archive mirror over the network to trusted clients
raw captureLocal preservation of original provider session files into a durable upload outbox without parsing their content	Local preservation of original provider sessionA single conversation or interaction with an AI coding agent, typically one run/launch files into a durable upload outbox without parsing their content
raw syncUpload of original session files to an operator-managed server for later hosted processing	Upload of original sessionA single conversation or interaction with an AI coding agent, typically one run/launch files to an operator-managed server for later hosted processing
recall entryA distilled, reusable fact extracted from session history with evidence links	A distilled, reusable fact extracted from sessionA single conversation or interaction with an AI coding agent, typically one run/launch history with evidence links
remote syncSyncing sessions from other machines via SSH or HTTP	Syncing sessions from other machines via SSHSecure Shell or HTTP
secret findingDetected credentials or secrets in session content, stored with redacted matches	Detected credentials or secrets in sessionA single conversation or interaction with an AI coding agent, typically one run/launch content, stored with redacted matches
sessionA single conversation or interaction with an AI coding agent, typically one run/launch	A single conversation or interaction with an AI coding agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.), typically one run/launch
session watchLive polling of one session's database state and source-file mtime, shared by the SSE handler and the session watch command	Live polling of one sessionA single conversation or interaction with an AI coding agent, typically one run/launch's database state and source-file mtime, shared by the SSEServer-Sent Events handler and the session watchLive polling of one session's database state and source-file mtime, shared by the SSE handler and the session watch command command
signalA health or outcome indicator computed from session content (success/failure, tool health, context pressure)	A health or outcome indicator computed from sessionA single conversation or interaction with an AI coding agent, typically one run/launch content (success/failure, tool health, context pressure)
syncThe process of discovering new/changed session files and updating the database	The process of discovering new/changed sessionA single conversation or interaction with an AI coding agent, typically one run/launch files and updating the database
tool callAn invocation of a tool/function by the AI agent during a session	An invocation of a tool/function by the AI agentAn AI coding tool that produces session files (Claude, Codex, Cursor, etc.) during a sessionA single conversation or interaction with an AI coding agent, typically one run/launch
usage eventA record of token consumption during a session or portion of a session	A record of token consumption during a sessionA single conversation or interaction with an AI coding agent, typically one run/launch or portion of a sessionA single conversation or interaction with an AI coding agent, typically one run/launch
worktreeA git working tree (main or linked checkout) used with mapping rules to attribute sessions to projects	A git working tree (main or linked checkout) used with mapping rules to attribute sessions to projects

SDLC Status Dashboard

Features

Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable

Requirements: Session Sync & Management

Overview

Stakeholders

Functional Requirements

Non-Functional Requirements

Acceptance Criteria

Open Questions

Specification: Session Sync & Management

Overview

Architecture

Data Models

ParsedSession

SkipCacheEntry

APIApplication Programming Interface Contracts

POST /api/v1/syncThe process of discovering new/changed session files and updating the database

POST /api/v1/resync

GET /api/v1/syncThe process of discovering new/changed session files and updating the database/status

Sequences

File Change Detection

Periodic Scan

Technical Decisions

Risks and Unknowns

Test Plan: Session Sync & Management

Scope

Unit Tests

Integration Tests

Test Files

Edge Cases and Failure Scenarios

Coverage Matrix

requirements

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable

Requirements: Recall System

Overview

Stakeholders

Functional Requirements

Non-Functional Requirements

Acceptance Criteria

Open Questions

Specification: Recall System

Overview

Architecture

Data Models

recall_entries

recall_evidence

APIApplication Programming Interface Contracts

GET /api/v1/recall/search

Technical Decisions

Test Plan: Recall System

Scope

Unit Tests

Test Files

Coverage Matrix

requirements

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable

Requirements: Desktop App

Overview

Stakeholders

Functional Requirements

Non-Functional Requirements

Acceptance Criteria

Open Questions

Specification: Desktop App

Overview

Architecture

Technical Decisions

Build Configuration

Test Plan: Desktop App

Scope

Unit Tests

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable

`agentsview clickhouse push [target]`

`agentsview clickhouse status [target]`

`agentsview clickhouse serve`

`agentsview clickhouse service`

Pipeline Progress ?
⚪ not started not yet begun
✏️ draft initial version
🔍 in review under review
🚧 in progress actively worked on
⛔ blocked waiting on dependency
✅ done completed
⏭️ skipped not applicable