Agent Session Search

Agent Session Search

Unified CLI/TUI to index and search local coding agent history. Aggregates sessions from 13+ agents into a single searchable index with sub-60ms latency. Purpose-built for AI agent consumption with robot mode and forgiving syntax. Not a library -- CASS is an external Rust CLI that must be installed separately.

Do not use for real-time session monitoring. Do not use when the agent has no local session history stored on disk.

Install via curl one-liner, Homebrew, or Scoop (see Configuration reference). Requires Rust nightly toolchain for building from source.

CRITICAL: NEVER run bare `cass` -- it launches an interactive TUI that blocks your session. Always use `--robot` or `--json` flags.

Essential Commands

Supported Agents

Search Modes

Semantic mode requires MiniLM model files. When unavailable, CASS falls back to a hash-based embedder for approximate similarity.

Forgiving Syntax

CASS auto-corrects common agent mistakes and emits teaching notes to stderr:

Common Mistakes

Delegation

Use this skill for indexing, searching, and analyzing coding agent session history via CASS CLI. Delegates to the external cass binary for all operations. Run cass robot-docs guide for the authoritative command reference directly from the installed version.

For multi-machine session search, see Remote Sources. For TUI usage by human operators, see TUI Reference.

References

• Command Reference -- indexing, search, session viewing, export, and diagnostics
• Robot Mode -- self-documenting API, forgiving syntax, output formats, token budget
• Query Language -- boolean operators, wildcards, match types, time formats, auto-fuzzy fallback
• Search and Ranking -- search modes, ranking, scoring formula
• Remote Sources -- multi-machine search via SSH/rsync, setup wizard, path mappings
• TUI Reference -- keyboard shortcuts, themes, saved views, density modes, bookmarks
• Error Handling -- structured errors, exit codes, troubleshooting
• Internals -- response shapes, deduplication, performance, watch mode, semantic search
• Configuration -- environment variables, shell completions, installation, integrations

Command Reference

Indexing

# Full rebuild of DB and search index
cass index --full

# Incremental update (since last scan)
cass index

# Watch mode: auto-reindex on file changes
cass index --watch

# Force rebuild even if schema unchanged
cass index --full --force-rebuild

Search

# Basic search (JSON output required for agents!)
cass search "query" --robot

# With filters
cass search "error" --robot --agent claude --days 7
cass search "bug" --robot --workspace /path/to/project
cass search "panic" --robot --today

# Time filters
cass search "auth" --robot --since 2024-01-01 --until 2024-01-31
cass search "test" --robot --yesterday
cass search "fix" --robot --week

# Wildcards
cass search "auth*" --robot          # prefix: authentication, authorize
cass search "*tion" --robot          # suffix: authentication, exception
cass search "*config*" --robot       # substring: misconfigured

# Search modes
cass search "authentication" --mode lexical --robot
cass search "how to handle user login" --mode semantic --robot
cass search "auth error handling" --mode hybrid --robot

# Token budget management (critical for LLMs!)
cass search "error" --robot --fields minimal              # path, line, agent only
cass search "error" --robot --limit 5                     # cap results

# Match highlighting
cass search "authentication error" --robot --highlight

Session Viewing and Export

# Expand context around a line (from search result)
cass expand /path/to/session.jsonl -n 42 -C 5 --json
# Shows 5 messages before and after line 42

# View source at line
cass view /path/to/session.jsonl -n 42 --json

# Export conversation as self-contained HTML
cass export-html /path/to/session.jsonl
cass export-html /path/to/session.jsonl --encrypt --password "secret"
cass export-html /path/to/session.jsonl --output-dir ./exports --open

Status and Diagnostics

# Quick health check
cass health
cass health --json

# Self-documenting API for agents
cass robot-docs guide      # quick-start walkthrough
cass robot-docs commands   # all commands and flags
cass robot-docs schemas    # response JSON schemas
cass robot-docs exit-codes # error handling
cass robot-docs examples   # copy-paste invocations
cass robot-docs contracts  # API versioning
cass robot-docs sources    # remote sources guide

Use Cases

# "I solved this before..."
cass search "TypeError: Cannot read property" --robot --days 30

# Cross-agent learning (what has ANY agent said about X?)
cass search "authentication" --robot --workspace /path/to/project

# Agent-to-agent handoff
cass search "database migration" --robot --fields minimal

# Daily review
cass search "--today" --robot

Configuration

Environment Variables

Shell Completions

cass completions bash > ~/.local/share/bash-completion/completions/cass
cass completions zsh > "${fpath[1]}/_cass"
cass completions fish > ~/.config/fish/completions/cass.fish
cass completions powershell >> $PROFILE

Installation

# One-liner install (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh \
  | bash -s -- --easy-mode --verify

# Windows (Scoop)
scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/cass

# macOS/Linux (Homebrew)
brew install dicklesworthstone/tap/cass

Remote install fallback chain (for multi-machine setup):

1. cargo-binstall (~30s) 2. Pre-built binary (~10s) 3. cargo install (~5min) 4. Full bootstrap with rustup (~10min)

Integration with CASS Memory (cm)

CASS provides episodic memory (raw sessions). CM extracts procedural memory (rules and playbooks):

# 1. CASS indexes raw sessions
cass index --full

# 2. Search for relevant past experience
cass search "authentication timeout" --robot --limit 10

# 3. CM reflects on sessions to extract rules
cm reflect

Integration with Flywheel

Error Handling

Structured Error Responses

Errors are JSON with actionable hints:

{
  "error": {
    "code": 3,
    "kind": "index_missing",
    "message": "Search index not found",
    "hint": "Run 'cass index --full' to build the index",
    "retryable": false
  }
}

Exit Codes

stdout contains JSON data only. stderr contains diagnostics and teaching notes.

Run cass robot-docs exit-codes for the full exit code reference from your installed version.

Recovery Pattern

# Always start with a health check
cass health --json || cass index --full

# If search returns errors, rebuild the index
cass index --full --force-rebuild

Troubleshooting

Internals

Architecture

CASS uses a dual storage strategy:

• SQLite (WAL mode): Source of truth with ACID compliance and FTS5 for fallback search
• Tantivy: Speed layer with schema v4, edge n-grams for fast prefix matching

Deduplication Strategy

CASS uses multi-layer deduplication:

1. Message Hash: SHA-256 of (role + content + timestamp) -- identical messages stored once 2. Conversation Fingerprint: Hash of first N message hashes -- detects duplicate files 3. Search-Time Dedup: Results deduplicated by content similarity

Noise Filtering:

• Empty messages and pure whitespace
• System prompts (unless searching for them)
• Repeated tool acknowledgments

Performance Characteristics

Memory: 70-140MB typical (50K messages) Disk: ~600 bytes/message (including n-gram overhead)

Watch Mode

Real-time index updates:

cass index --watch

• Debounce: 2 seconds (wait for burst to settle)
• Max wait: 5 seconds (force flush during continuous activity)
• Incremental: Only re-scans modified files

The TUI automatically starts watch mode in background.

Semantic Search

Local-only semantic search using MiniLM via FastEmbed (384-dimensional vectors, no cloud dependency):

• Primary model: MiniLM (~23MB, auto-downloaded on first use via FastEmbed)
• Fallback: Hash-based embedder (FNV-1a deterministic hashing) for approximate similarity when MiniLM unavailable

Vector index stored in CVVI format (Custom Vector Versioned Index) with:

• F32/F16 precision support
• Content deduplication via SHA-256
• Memory-mapped loading for efficiency

Query Language

Basic Queries

Boolean Operators

# Complex boolean query
cass search "authentication AND (error OR failure) NOT test" --robot

# Exclude test files
cass search "bug fix -test -spec" --robot

# Either error type
cass search "TypeError OR ValueError" --robot

Wildcard Patterns

Match Types

Results include match_type:

Auto-Fuzzy Fallback

When exact query returns <3 results, CASS automatically retries with wildcards:

• auth → *auth*
• Results flagged with wildcard_fallback: true

Flexible Time Input

CASS accepts a wide variety of time/date formats:

Remote Sources (Multi-Machine Search)

Search across sessions from multiple machines via SSH/rsync.

Setup Wizard (Recommended)

cass sources setup

The wizard:

1. Discovers SSH hosts from ~/.ssh/config 2. Probes each for agent data and cass installation 3. Optionally installs cass on remotes 4. Indexes sessions on remotes 5. Configures sources.toml 6. Syncs data locally

cass sources setup --hosts css,csd,yto  # Specific hosts only
cass sources setup --dry-run             # Preview without changes
cass sources setup --resume              # Resume interrupted setup

Manual Setup

# Add a remote machine
cass sources add user@laptop.local --preset macos-defaults
cass sources add dev@workstation --path ~/.claude/projects --path ~/.codex/sessions

# List sources
cass sources list --json

# Sync sessions
cass sources sync
cass sources sync --source laptop --verbose

# Check connectivity
cass sources doctor
cass sources doctor --source laptop --json

# Path mappings (rewrite remote paths to local)
cass sources mappings list laptop
cass sources mappings add laptop --from /home/user/projects --to /Users/me/projects
cass sources mappings test laptop /home/user/projects/myapp/src/main.rs

# Remove source
cass sources remove laptop --purge -y

Configuration stored in ~/.config/cass/sources.toml (Linux) or ~/Library/Application Support/cass/sources.toml (macOS).

Robot Mode

Self-Documenting API

CASS teaches agents how to use itself:

# Topic-based docs (LLM-optimized)
cass robot-docs commands   # all commands and flags
cass robot-docs schemas    # response JSON schemas
cass robot-docs examples   # copy-paste invocations
cass robot-docs exit-codes # error handling
cass robot-docs guide      # quick-start walkthrough
cass robot-docs contracts  # API versioning
cass robot-docs sources    # remote sources guide

Forgiving Syntax (Agent-Friendly)

CASS aggressively normalizes input to maximize acceptance when intent is clear. When corrections are applied, CASS emits a teaching note to stderr so agents learn the canonical syntax.

Output Conventions

Design principle: stdout = JSON only; diagnostics go to stderr.

# JSON output for agent consumption
cass search "error" --robot

# Health check with JSON
cass health --json

# View/expand with JSON
cass view /path -n 42 --json
cass expand /path -n 42 -C 5 --json

Exit code 0 means success (parse stdout). Non-zero means an error occurred.

Token Budget Management

LLMs have context limits. Control output size:

Start with --fields minimal --limit 5 and widen as needed.

Agent Workflow

Recommended sequence for AI agents:

# 1. Check if CASS is available and healthy
cass health --json || cass index --full

# 2. Search for relevant past experience
cass search "authentication error" --robot --fields minimal --limit 5

# 3. Get more context on a promising result
cass expand /path/to/session.jsonl -n 42 -C 5 --json

# 4. View full source if needed
cass view /path/to/session.jsonl -n 42 --json

Always check health first. If CASS is not installed, skip gracefully.

Search and Ranking

Search Modes

Three search modes, selectable with --mode flag:

cass search "authentication" --mode lexical --robot
cass search "how to handle user login" --mode semantic --robot
cass search "auth error handling" --mode hybrid --robot

Hybrid combines lexical and semantic using RRF:

RRF_score = Sigma 1 / (60 + rank_i)

Semantic mode requires MiniLM model files (~23MB). When MiniLM is not available, CASS falls back to a hash-based embedder (FNV-1a deterministic hashing) for approximate similarity.

Ranking Modes

Cycle with F12 in TUI or use --ranking flag:

Score Components

• Text Relevance (BM25): Term frequency, inverse document frequency, length normalization
• Recency: Exponential decay based on age
• Match Exactness: Exact > Prefix > Suffix > Substring > Fuzzy

Match Types

Results include a match_type field indicating how the query matched:

TUI Reference

Launch with cass (no flags). Do not use from AI agents — use `--robot` mode instead.

Keyboard Shortcuts

Navigation

• Up/Down: Move selection
• Left/Right: Switch panes
• Tab/Shift+Tab: Cycle focus
• Enter: Open in $EDITOR
• Space: Full-screen detail view
• Home/End: Jump to first/last result
• PageUp/PageDown: Scroll by page

Filtering

• F3: Agent filter
• F4: Workspace filter
• F5/F6: Time filters (from/to)
• Shift+F3: Scope to current result's agent
• Shift+F4: Clear workspace filter
• Shift+F5: Cycle presets (24h/7d/30d/all)
• Ctrl+Del: Clear all filters

Modes

• F2: Toggle theme (6 presets)
• F7: Context window size (S/M/L/XL)
• F9: Match mode (prefix/standard)
• F12: Ranking mode
• Ctrl+B: Toggle border style

Selection and Actions

• m: Toggle selection
• Ctrl+A: Select all
• A: Bulk actions menu
• Ctrl+Enter: Add to queue
• Ctrl+O: Open all queued
• y: Copy path/content
• Ctrl+Y: Copy all selected
• /: Find in detail pane
• n/N: Next/prev match

Views and Palette

• Ctrl+P: Command palette
• 1-9: Load saved view
• Shift+1-9: Save view to slot

Source Filtering (multi-machine)

• F11: Cycle source filter (all/local/remote)
• Shift+F11: Source selection menu

Global

• Ctrl+C: Quit
• F1 or ?: Toggle help
• Ctrl+Shift+R: Force re-index
• Ctrl+Shift+Del: Reset all TUI state

Detail Pane Tabs

Context Window Sizing

Peek Mode (Ctrl+Space): Temporarily expand to XL without changing default.

Theme Presets

Cycle through 6 built-in themes with F2:

All themes validated against WCAG contrast requirements (4.5:1 minimum for text).

Role-Aware Message Styling

Saved Views

Save filter configurations to 9 slots for instant recall.

What Gets Saved:

• Active filters (agent, workspace, time range)
• Current ranking mode
• The search query

Keyboard:

• Shift+1 through Shift+9: Save current view
• 1 through 9: Load view from slot

Via Command Palette: Ctrl+P → "Save/Load view"

Views persist in tui_state.json across sessions.

Density Modes

Control lines per search result. Cycle with Shift+D:

Bookmark System

Save important results with notes and tags. In TUI: Press b to bookmark, add notes and tags.

Bookmark Structure:

• title: Short description
• source_path, line_number, agent, workspace
• note: Your annotations
• tags: Comma-separated labels
• snippet: Extracted content

Storage: ~/.local/share/coding-agent-search/bookmarks.db (SQLite)