/coding_agent_session_search

name: cass
description: "Coding Agent Session Search - unified CLI/TUI to index and search local coding agent history from Claude Code, Codex, Gemini, Cursor, Aider, ChatGPT, Pi-Agent, Factory, and more. Purpose-built for AI agent consumption with robot mode."

CASS - Coding Agent Session Search

Unified, high-performance CLI/TUI to index and search your local coding agent history. Aggregates sessions from **23 agents**, including Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Pi-Agent, Factory (Droid), OpenHands, Antigravity, and Grok Build.

CRITICAL: Robot Mode Required for AI Agents

**NEVER run bare `cass`** - it launches an interactive TUI that blocks your session!

# WRONG - blocks terminal
cass

# CORRECT - JSON output for agents
cass search "query" --robot
cass search "query" --json  # alias

**Always use `--robot` or `--json` flags for machine-readable output.**

---

Quick Reference for AI Agents

Bounded History Retrieval

For a quick project-history question, start with one scoped query. The flag set below is verified on cass 0.8.0; check `cass --version` and `cass search --help` once per installed version. If `--no-maintenance` is unsupported, stop and report the version mismatch; silently removing it permits maintenance.

# Specific terms, one workspace, recent history, small cited result set
cass search "performance regression" --workspace /path/to/project --days 7 \
  --mode lexical --no-maintenance --robot --robot-meta --fields minimal \
  --limit 5 --max-tokens 2000 --timeout 2000

# Expand only a useful hit, using its exact source_path and line_number
cass view /path/to/session.jsonl -n 42 -C 3 --json --timeout 2000

`--timeout` is in milliseconds; `--max-tokens` is an approximate output budget, not a CPU or memory limit. Apply a caller-side wall-clock deadline as well (for example, GNU `timeout 10s` before the command). Exit 124 from that wrapper is an incomplete attempt; its interrupted stdout may not be valid JSON. In JSON search output, inspect `budget.timed_out` even after exit 0: empty timed-out hits do not prove that no history exists.

`view -C 3` limits surrounding lines, not bytes or tokens; a single JSONL record can be large. Check its output size before adding excerpts to a prompt.

Hybrid remains the product default. Explicit lexical mode keeps this workflow out of semantic inference; `--no-maintenance` prevents index repair, catch-up, and daemon auto-spawn. If it returns `maintenance-required`, report that blocker and stop this retrieval attempt. Do not turn a summary request into an index, repair, model-install, wildcard-aggregate, or repeated health/status workflow. Use readiness commands when diagnosing readiness; review their proposed actions before starting a separate mutating task. Broaden dates or terms deliberately after a completed query; choose semantic/hybrid only when conceptual retrieval is needed and its cost is acceptable. Preserve source/line citations in summaries.

Essential Commands

# Find the current session for this workspace
cass sessions --current --json

# List recent sessions for a specific project
cass sessions --workspace "$(pwd)" --json --limit 5

# Common agent flow: find current session, then export it
cass export-html "$(cass sessions --current --json | jq -r '.sessions[0].path')" --json

# Search with JSON output
cass search "authentication error" --robot --limit 5

# Search with metadata (elapsed_ms, cache stats, freshness)
cass search "error" --robot --robot-meta

# Minimal payload (path, line, agent only)
cass search "bug" --robot --fields minimal

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

# Expand context around a line
cass expand /path/to/session.jsonl -n 42 -C 5 --json

# Capabilities discovery
cass capabilities --json

# Full API schema
cass introspect --json

# LLM-optimized documentation
cass robot-docs guide
cass robot-docs commands
cass robot-docs schemas
cass robot-docs examples
cass robot-docs exit-codes

---

Why Use CASS

Cross-Agent Knowledge Transfer

Your coding agents create scattered knowledge:

• Claude Code sessions in `~/.claude/projects`
• Codex sessions in `~/.codex/sessions`
• Cursor state in SQLite databases
• Aider history in markdown files

CASS **unifies all of this** into a single searchable index. When you're stuck on a problem, search across ALL your past agent sessions to find relevant solutions.

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 summary

# Daily review
cass timeline --today --json

---

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

# Safe retries with idempotency key (24h TTL)
cass index --full --idempotency-key "build-$(date +%Y%m%d)"

# JSON output with stats
cass index --full --json

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

# Token budget manageme