cass

Help the user install, search, explore, and export their Claude Code sessions using the `cass` CLI and the optional `cass-memory` (`cm`) reflection pipeline. Two tools — independent, loosely coupled:

Tool	Role	Required
cass	Infrastructure: index, search, export sessions	Yes
cm (cass-memory)	Intelligence: reflect on sessions, build playbook rules	Optional

Check if installed:

cass --version   # expect: cass 0.x.x
cm --version     # expect: cass-memory 0.x.x (optional)

# Install cass (session indexer)
brew install dicklesworthstone/tap/cass
cass index --full   # ~2 min first run

# Install cm / cass-memory (reflection pipeline) — optional
brew install dicklesworthstone/tap/cm
# or one-liner: curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh" | bash -s -- --easy-mode --verify

# Configure LLM provider for cm (one of):
export ANTHROPIC_API_KEY=sk-ant-...
cm init && cm doctor   # verify cass + LLM OK

<quick_start>

1. Check index freshness: cass status --json
2. If stale (recommended_action = "index"), run: cass index
3. Execute the user's request (search / export / context / timeline) </quick_start>

Step 1: Pre-flight Check

Always run this first:

cass status --json

Key fields to check:

• recommended_action: "ok" = index is fresh; "index" = needs reindexing
• db_stats.total_sessions: how many sessions are indexed
• freshness.stale: true if index is stale

If stale, run:

cass index

Skip re-indexing if the user is searching a session they already know the path to (direct export).

---

Step 2: Execute the Request

Search sessions

# Basic search
cass search "topic keyword" --json --fields summary

# Limit to current workspace
cass search "keyword" --json --fields summary --workspace $(pwd)

# Filter by time
cass search "keyword" --json --fields summary --days 7

# Filter by agent (claude_code, cursor, codex, aider, etc.)
cass search "keyword" --json --fields summary --agent claude_code

# Chained search (narrow down results)
cass search "first topic" --robot-format sessions | cass search "second topic" --sessions-from -

Output fields in --fields summary: source_path, line_number, agent, title, score.

Export a session

# Export to stdout (review inline)
cass export ~/.claude/projects/<workspace-encoded>/<session-id>.jsonl

# Export to file
cass export <path-to-session.jsonl> -o /tmp/session.md

# Include tool call details
cass export <path> --include-tools

Session files live at: ~/.claude/projects/<workspace-encoded>/ — encode workspace path by replacing / with -.

Find related sessions for a file

cass context <path-to-session.jsonl> --json --limit 5

Returns sessions that worked in the same workspace or touched the same files.

View activity timeline

# Last 7 days
cass timeline --days 7

# Specific range
cass timeline --since 2025-01-01 --until 2025-01-31

Expand context around a search result

When cass search returns a line_number, use expand to see surrounding messages:

cass expand <path-to-session.jsonl> --line <line_number>

Reflect on sessions with cass-memory (cm)

# Preview what would be processed (dry run)
cm reflect --days 7 --max-sessions 3 --dry-run

# Run reflection: exports sessions → LLM diary → playbook rules
cm reflect --days 7 --max-sessions 5

# View current playbook rules
cm playbook

# Get context snippets for current workspace
cm context --workspace $(pwd)

# Check what cm knows about a topic
cm search "rate limiting"

# Health check (verifies cass + LLM connection)
cm doctor

# Daily cron: index + reflect on yesterday's sessions
# 0 8 * * * cass index && cm reflect --days 1

---

Step 3: Present Results

For search results: Show session title + path. If the user wants details, export the most relevant session.

For exports: Render the markdown inline or summarize key decisions/actions from the session.

For context results: List related sessions with their titles and workspaces.

---

Tips

• Use --fields summary to keep token usage low for search results.
• Use --workspace $(pwd) to scope to the current project.
• cass search --robot-format sessions outputs paths only — useful for piping into export or chained searches.
• For semantic search (finds conceptually related content): cass search "topic" --mode semantic
• Session paths follow this pattern: ~/.claude/projects/<workspace-encoded>/<uuid>.jsonl

<success_criteria> Session search/exploration is complete when:

• Index freshness verified (and refreshed if needed)
• User's sessions found or confirmed absent
• Relevant session content surfaced (exported/expanded as needed)

cass-memory reflection is complete when:

• cm doctor shows cass: OK and LLM: OK
• cm reflect ran without errors
• cm playbook shows updated rules </success_criteria>