coding-agent-session-search

Coding Agent Session Search

cass is the CLI from Dicklesworthstone/coding_agent_session_search. Longrein installs the latest official release but does not fork or reimplement it. Use cass --version to identify the active upstream build.

Agent Rules

• Never run bare cass; it opens the interactive TUI and can block an agent session.
• Always use --json, --robot, or --robot-format json for machine-readable output.
• Start unknown setups with cass triage --json and follow its next_command when it reports not_initialized, stale, or rebuilding state.
• Keep outputs bounded with --limit, --fields, --max-content-length, or --max-tokens.
• Treat stdout as data and stderr as diagnostics. Parse JSON instead of scraping human text.
• Check health, freshness, privacy, and warnings before pasting evidence into another prompt or answer.

Core Workflow

1. Check readiness:

cass triage --json

If next_command is present, inspect its stated safety and run it exactly when it is in scope. A first build or refresh commonly uses:

cass index --json --no-progress-events

2. Search broadly, then narrow:

cass search "authentication redirect timeout" --robot --robot-meta --limit 10 --fields summary --max-tokens 4000

Use --fields minimal for wide scans. Use --fields summary when titles and scores help triage. Add --workspace "$(pwd)", --agent, or date filters when the user provides that scope.

3. Drill into promising hits:

cass view /path/to/session.jsonl -n 42 --json
cass expand /path/to/session.jsonl -n 42 -C 5 --json

Use source_path and line_number from search hits. Prefer expand when surrounding dialogue changes the meaning.

4. Package bounded evidence for another agent or later step:

cass pack "checkout timeout root cause" --robot --max-tokens 8000 --limit 30

5. Cite paths, lines, or session identifiers from the machine output. Separate confirmed session evidence from inference, and re-check claims against the current repository or runtime before treating them as current truth.

Machine Contract

• Discover current schemas with cass capabilities --json, cass introspect --json, and cass robot-docs schemas instead of guessing fields.
• Search results normally expose hits[]; request only the fields needed for the current decision.
• With --robot-meta, use _meta.next_cursor for bounded pagination.
• Hybrid search may legitimately fall back to lexical while semantic assets are absent or rebuilding.
• Branch on error.kind in structured error envelopes, not on human message text.
• Do not download semantic models, delete indexes, or run broad repair commands without task-specific authority.