cass

name: cass description: Mine past agent sessions for working prompts, decisions, and patterns. Use when "what did I ask?", "find that prompt", session archaeology, or agent history. practices:

• pragmatic-programmer skill_api_version: 1 user-invocable: false hexagonal_role: supporting metadata: tier: execution external_dependencies:
  • "cass binary (>=0.3.6 recommended; some commands require HEAD \u2014 see Version Pinning)"
  • jq (required for parsing --json output)
  • GNU coreutils 'timeout' (recommended; cass index can hang under contention)
  • ssh + rsync (optional; only for cross-machine cass sources workflows)
  • fastembed model bundle ~90MB (optional; only for --mode semantic / hybrid; install via cass models install)

cass Session Search

Core Insight: Your repeated prompts are your best prompts. If you typed it 10+ times, it works. Mine your history.

cass is an upstream (Dicklesworthstone) tool and is self-describing — do not re-learn its surface from this skill. Discover it live:

cass capabilities --json      # features/connectors/limits of the installed binary
cass introspect --json        # full schema of every command + response
cass robot-docs guide|commands|examples|schemas|contracts   # machine-targeted docs

This skill carries only the AgentOps operating doctrine: when to reach for cass, the discovery workflow, the recovery posture, and the anti-patterns we have actually hit.

When to Use

• "What did I ask last time?" / "find that prompt that worked" — session archaeology
• Prior-art check before inventing a new approach, plan, or prompt
• Scope archaeology: "when did we decide NOT to do X?"
• Post-context-loss recovery: what was searched for after a crash = what mattered

The Goldmine Principle

Your conversation history contains:

• Refined prompts — Every rephrase that worked better was captured
• Working rituals — Prompts repeated 10+ times ARE your methodology
• Scope decisions — "When did we decide NOT to do X?"
• Recovery moments — What you searched for after context loss = what mattered

The insight: Mining your past beats inventing new approaches. In the AgentOps loop the goal is prior-art first: mine as a research-phase move before writing a fresh plan or prompt, and feed what you find back into the corpus instead of re-deriving it.

THE EXACT PROMPT — Discovery Workflow

1. Bootstrap: Check health, refresh index, get project overview
   cass status --json && cass index --json
   cass search "*" --workspace /data/projects/PROJECT --aggregate agent,date --limit 1 --json

2. Find prompts: Search for keywords, filter to user prompts (lines 1-3)
   cass search "KEYWORD" --workspace /data/projects/PROJECT --json --fields minimal --limit 50 \
     | jq '[.hits[] | select(.line_number <= 3)]'

3. Follow hits: View the actual content
   cass view /path/from/source_path.jsonl -n LINE -C 20

4. Expand context: See the full conversation flow
   cass expand /path/from/source_path.jsonl --line LINE --context 3

5. Discover related: Find the whole work cluster
   cass context /path/from/source_path.jsonl --json

Why it works: aggregations first (know the terrain), --fields minimal (5x smaller output), line_number <= 3 (user prompts live at the top), context clustering (one good hit → many related sessions). >10 matches for a prompt = a ritual; document and reuse it.

Operating Doctrine: Stale ≠ Broken

Three index states matter — never conflate them:

The trap: treating stale as broken triggers an unneeded 8–25s full rebuild when a 1–3s incremental (or a stale-but-correct query) would do. scripts/recover.sh implements the full decision tree with timeouts. Detailed symptom→fix tables (issue #196 hang, stale locks, database is busy race, etc.): RECOVERY.md, OBSERVABILITY.md, PITFALLS.md.

Version Pinning

cass evolves quickly; the released binary may lack HEAD features. When a flag returns "unrecognized", do not guess — probe: cass capabilities --json and cass introspect --json | jq '.commands[].name', and check cass --version.

Anti-Patterns (Don't Do These)

Long-form versions with mined evidence: ANTI_PATTERNS.md.

Safety Boundaries

Pre-authorized (rebuilds derived index data only, never destroys source sessions): cass doctor --fix --json, cass index --full --force-rebuild --json, cass sources doctor/sync, cass models install/verify.

Do NOT without explicit permission: delete core.NNNNN coredumps, delete .beads/, git reset --hard, or hand-edit ~/.config/cass/sources.toml — the CLI commands above already do everything safely. Never run bare cass (blocking TUI) inside an agent loop.

Reference Index

When the right reference isn't obvious from titles, grep -ni "SYMPTOM" references/*.md — cheaper than loading whole files into context.

Scripts

Scripts live under scripts/. They execute, never load — zero context tokens. None mutate state without explicit confirmation.

Validation

# Quick health check
cass status --json | jq '.index.fresh'

# Should return: true

If false, run: cass index --json