Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
dicklesworthstone avatar

Cass

dicklesworthstone/coding_agent_session_search

  • 2.6k installs
  • 1k repo stars
  • Updated August 5, 2026
  • dicklesworthstone/coding_agent_session_search

cass is an agent skill that Coding Agent Session Search - unified CLI/TUI to index and search local coding agent history from Claude Code, Codex, Ge.

About

Unified high performance CLI TUI to index and search your local coding agent history Aggregates sessions from 11 agents Codex Claude Code Gemini CLI Cline OpenCode Amp Cursor ChatGPT Aider Pi Agent and Factory Droid CRITICAL Robot Mode Required for AI Agents NEVER run bare cass it launches an interactive TUI that blocks your session CORRECT JSON output for agents cass search query robot cass search query json alias The cass skill documents workflows prerequisites and usage patterns grounded in its repository SKILL md Agents should follow the documented steps respect safety and permission notes and cite only capabilities described in the source It triggers on phrases matching the skill description and integrates with the agent toolchain for the tasks outlined in the documentation

  • description: "Coding Agent Session Search - unified CLI/TUI to index and search local coding agent history from Claude C
  • Unified, high-performance CLI/TUI to index and search your local coding agent history. Aggregates sessions from **11 age
  • **NEVER run bare `cass`** - it launches an interactive TUI that blocks your session!
  • See SKILL.md for cass operational details.
  • See SKILL.md for cass operational details.

Cass by the numbers

  • 2,613 all-time installs (skills.sh)
  • +118 installs in the week ending Aug 4, 2026 (Skillselion tracking)
  • Ranked #320 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
  • Security screen: HIGH risk (skills.sh audit)
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
At a glance

cass capabilities & compatibility

Capabilities
description: "coding agent session search unif · unified, high performance cli/tui to index and s · **never run bare `cass`** it launches an inter · see skill.md for cass operational details.
Use cases
orchestration
From the docs

What cass says it does

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
SKILL.md
Unified, high-performance CLI/TUI to index and search your local coding agent history. Aggregates sessions from **11 agents**: Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Ai
SKILL.md
**NEVER run bare `cass`** - it launches an interactive TUI that blocks your session!
SKILL.md
npx skills add https://github.com/dicklesworthstone/coding_agent_session_search --skill cass

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs2.6k
repo stars★ 1k
Security audit0 / 3 scanners passed
Last updatedAugust 5, 2026
Repositorydicklesworthstone/coding_agent_session_search ↗

What does cass help with and when should an agent load it?

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

Who is it for?

Developers using cass as documented in the skill repository.

Skip if: Skip when the task falls outside the cass documented scope.

When should I use this skill?

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

What you get

Agent actions aligned with the cass SKILL.md workflow and documented deliverables.

  • Aligned agent session context tied to current repo tasks

Files

SKILL.mdMarkdownGitHub ↗

CASS - Coding Agent Session Search

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

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

Pre-Flight Check

# Health check (exit 0=healthy, 1=unhealthy, <50ms)
cass health

# If unhealthy, rebuild index
cass index --full

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 management (critical for LLMs!)
cass search "error" --robot --fields minimal              # path, line, agent only
cass search "error" --robot --fields summary              # adds title, score
cass search "error" --robot --max-content-length 500      # truncate fields
cass search "error" --robot --max-tokens 2000             # soft budget (~4 chars/token)
cass search "error" --robot --limit 5                     # cap results

# Pagination (cursor-based)
cass search "TODO" --robot --robot-meta --limit 20
# Use _meta.next_cursor from response:
cass search "TODO" --robot --robot-meta --limit 20 --cursor "eyJ..."

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

# Query analysis/debugging
cass search "auth*" --robot --explain    # parsed query, cost estimates
cass search "auth error" --robot --dry-run  # validate without executing

# Aggregations (server-side counts)
cass search "error" --robot --aggregate agent,workspace,date

# Request correlation
cass search "bug" --robot --request-id "req-12345"

# Source filtering (for multi-machine setups)
cass search "auth" --robot --source laptop
cass search "error" --robot --source remote

# Traceability (for debugging agent pipelines)
cass search "error" --robot --trace-file /tmp/cass-trace.json

Session Analysis

# Export conversation to markdown/HTML/JSON
cass export /path/to/session.jsonl --format markdown -o conversation.md
cass export /path/to/session.jsonl --format html -o conversation.html
cass export /path/to/session.jsonl --format json --include-tools

# 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

# Activity timeline
cass timeline --today --json --group-by hour
cass timeline --days 7 --json --agent claude
cass timeline --since 7d --json

# Find related sessions for a file
cass context /path/to/source.ts --json

Status & Diagnostics

# Quick health (<50ms)
cass health
cass health --json

# Full status snapshot
cass status --json
cass state --json  # alias

# Statistics
cass stats --json
cass stats --by-source  # for multi-machine

# Full diagnostics
cass diag --verbose

---

Aggregation & Analytics

Aggregate search results server-side to get counts and distributions without transferring full result data:

# Count results by agent
cass search "error" --robot --aggregate agent
# → { "aggregations": { "agent": { "buckets": [{"key": "claude_code", "count": 45}, ...] } } }

# Multi-field aggregation
cass search "bug" --robot --aggregate agent,workspace,date

# Combine with filters
cass search "TODO" --agent claude --robot --aggregate workspace
Aggregation FieldDescription
agentGroup by agent type (claude_code, codex, cursor, etc.)
workspaceGroup by workspace/project path
dateGroup by date (YYYY-MM-DD)
match_typeGroup by match quality (exact, prefix, fuzzy)

Top 10 buckets returned per field, with other_count for remaining items.

---

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 Deep Dive

Self-Documenting API

CASS teaches agents how to use itself:

# Quick capability check
cass capabilities --json
# Returns: features, connectors, limits

# Full API schema
cass introspect --json
# Returns: all commands, arguments, response shapes

# 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 auto-corrects common mistakes:

What you typeWhat CASS understands
cass serach "error"cass search "error" (typo corrected)
cass -robot -limit=5cass --robot --limit=5 (single-dash fixed)
cass --Robot --LIMIT 5cass --robot --limit 5 (case normalized)
cass find "auth"cass search "auth" (alias resolved)
cass --limt 5cass --limit 5 (Levenshtein <=2)

Command Aliases:

  • find, query, q, lookup, grep → search
  • ls, list, info, summary → stats
  • st, state → status
  • reindex, idx, rebuild → index
  • show, get, read → view
  • docs, help-robot, robotdocs → robot-docs

Output Formats

# Pretty-printed JSON (default)
cass search "error" --robot

# Streaming JSONL (header + one hit per line)
cass search "error" --robot-format jsonl

# Compact single-line JSON
cass search "error" --robot-format compact

# With performance metadata
cass search "error" --robot --robot-meta

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

Token Budget Management

LLMs have context limits. Control output size:

FlagEffect
--fields minimalOnly source_path, line_number, agent
--fields summaryAdds title, score
--fields score,title,snippetCustom field selection
--max-content-length 500Truncate long fields (UTF-8 safe)
--max-tokens 2000Soft budget (~4 chars/token)
--limit 5Cap number of results

Truncated fields include *_truncated: true indicator.

---

Structured Error Handling

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

CodeMeaningAction
0SuccessParse stdout
1Health check failedRun cass index --full
2Usage errorFix syntax (hint provided)
3Index/DB missingRun cass index --full
4Network errorCheck connectivity
5Data corruptionRun cass index --full --force-rebuild
6Incompatible versionUpdate cass
7Lock/busyRetry later
8Partial resultIncrease --timeout
9Unknown errorCheck retryable flag

---

Search Modes

Three search modes, selectable with --mode flag:

ModeAlgorithmBest For
lexical (default)BM25 full-textExact term matching, code searches
semanticVector similarityConceptual queries, "find similar"
hybridReciprocal Rank FusionBalanced precision and recall
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 = Σ 1 / (60 + rank_i)

---

Pipeline Mode (Chained Search)

Chain searches by piping session paths:

# Find sessions mentioning "auth", then search within those for "token"
cass search "authentication" --robot-format sessions | \
  cass search "refresh token" --sessions-from - --robot

# Build a filtered corpus from today's work
cass search --today --robot-format sessions > today_sessions.txt
cass search "bug fix" --sessions-from today_sessions.txt --robot

Use cases:

  • Drill-down: Broad search → narrow within results
  • Cross-reference: Find sessions with term A, then find term B within them
  • Corpus building: Save session lists for repeated searches

---

Query Language

Basic Queries

QueryMatches
errorMessages containing "error" (case-insensitive)
python errorBoth "python" AND "error"
"authentication failed"Exact phrase

Boolean Operators

OperatorExampleMeaning
ANDpython AND errorBoth terms required (default)
ORerror OR warningEither term matches
NOTerror NOT testFirst term, excluding second
-error -testShorthand for NOT
# 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

PatternTypePerformance
auth*PrefixFast (edge n-grams)
*tionSuffixSlower (regex)
*config*SubstringSlowest (regex)

Match Types

Results include match_type:

TypeMeaningScore Boost
exactVerbatim matchHighest
prefixVia prefix expansionHigh
suffixVia suffix patternMedium
substringVia substring patternLower
fuzzyAuto-fallback (sparse results)Lowest

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:

FormatExamples
Relative-7d, -24h, -30m, -1w
Keywordsnow, today, yesterday
ISO 86012024-11-25, 2024-11-25T14:30:00Z
US Dates11/25/2024, 11-25-2024
Unix Timestamp1732579200 (seconds or milliseconds)

---

Ranking Modes

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

ModeFormulaBest For
Recent Heavyrelevance*0.3 + recency*0.7"What was I working on?"
Balancedrelevance*0.5 + recency*0.5General search
Relevancerelevance*0.8 + recency*0.2"Best explanation of X"
Match QualityPenalizes fuzzy matchesPrecise technical searches
Date NewestPure chronologicalRecent activity
Date OldestReverse chronological"When did I first..."

Score Components

  • Text Relevance (BM25): Term frequency, inverse document frequency, length normalization
  • Recency: Exponential decay (today ~1.0, last week ~0.7, last month ~0.3)
  • Match Exactness: Exact phrase=1.0, Prefix=0.9, Suffix=0.8, Substring=0.6, Fuzzy=0.4

Blended Scoring Formula

Final_Score = BM25_Score × Match_Quality + α × Recency_Factor
Modeα ValueEffect
Recent Heavy1.0Recency dominates
Balanced0.4Moderate recency boost
Relevance Heavy0.1BM25 dominates
Match Quality0.0Pure text matching

---

Supported Agents (11 Connectors)

AgentLocationFormat
Claude Code~/.claude/projectsJSONL
Codex~/.codex/sessionsJSONL (Rollout)
Gemini CLI~/.gemini/tmpJSON
ClineVS Code global storageTask directories
OpenCode.opencode directoriesSQLite
Amp~/.local/share/amp + VS CodeMixed
Cursor~/Library/Application Support/CursorSQLite (state.vscdb)
ChatGPT~/Library/Application Support/com.openai.chatJSON (v1 unencrypted)
Aider~/.aider.chat.history.md + per-projectMarkdown
Pi-Agent~/.pi/agent/sessionsJSONL with thinking
Factory (Droid)~/.factory/sessionsJSONL by workspace

Note: ChatGPT v2/v3 are AES-256-GCM encrypted (keychain access required). Legacy v1 unencrypted conversations are indexed automatically.

---

TUI Features (for Humans)

Launch with cass (no flags):

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 & 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 & 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

TabContentSwitch With
MessagesFull conversation with markdown[ / ]
SnippetsKeyword-extracted summaries[ / ]
RawUnformatted JSON/text[ / ]

Context Window Sizing

SizeCharactersUse Case
Small~200Quick scanning
Medium~400Default balanced view
Large~800Longer passages
XLarge~1600Full context, code review

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

---

Theme Presets

Cycle through 6 built-in themes with F2:

ThemeDescriptionBest For
DarkTokyo Night-inspired deep bluesLow-light environments
LightHigh-contrast light backgroundBright environments
CatppuccinWarm pastels, reduced eye strainAll-day coding
DraculaPurple-accented dark themePopular developer theme
NordArctic-inspired cool tonesCalm, focused work
High ContrastMaximum readabilityAccessibility needs

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

Role-Aware Message Styling

RoleVisual Treatment
UserBlue-tinted background, bold
AssistantGreen-tinted background
SystemGray/muted background
ToolOrange-tinted background

---

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:

ModeLinesBest For
Compact3Maximum results visible
Cozy5Balanced view (default)
Spacious8Detailed preview

---

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)

---

Optional Semantic Search

Local-only semantic search using MiniLM (no cloud):

Required files (place in data directory):

  • model.onnx
  • tokenizer.json
  • config.json
  • special_tokens_map.json
  • tokenizer_config.json

Vector index stored as vector_index/index-minilm-384.cvvi.

CASS does NOT auto-download models; you must manually install them.

Hash Embedder Fallback: When MiniLM not installed, CASS uses a hash-based embedder for approximate semantic similarity.

---

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

TUI automatically starts watch mode in background.

---

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

OperationLatency
Prefix search (cached)2-8ms
Prefix search (cold)40-60ms
Substring search80-200ms
Full reindex5-30s
Incremental reindex50-500ms
Health check<50ms

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

---

Response Shapes

Search Response:

{
  "query": "error",
  "limit": 10,
  "count": 5,
  "total_matches": 42,
  "hits": [
    {
      "source_path": "/path/to/session.jsonl",
      "line_number": 123,
      "agent": "claude_code",
      "workspace": "/projects/myapp",
      "title": "Authentication debugging",
      "snippet": "The error occurs when...",
      "score": 0.85,
      "match_type": "exact",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "_meta": {
    "elapsed_ms": 12,
    "cache_hit": true,
    "wildcard_fallback": false,
    "next_cursor": "eyJ...",
    "index_freshness": { "stale": false, "age_seconds": 120 }
  }
}

Aggregation Response:

{
  "aggregations": {
    "agent": {
      "buckets": [
        {"key": "claude_code", "count": 120},
        {"key": "codex", "count": 85}
      ],
      "other_count": 15
    }
  }
}

---

Environment Variables

VariablePurpose
CASS_DATA_DIROverride data directory
CHATGPT_ENCRYPTION_KEYBase64 key for encrypted ChatGPT
PI_CODING_AGENT_DIROverride Pi-Agent sessions path
CASS_CACHE_SHARD_CAPPer-shard cache entries (default 256)
CASS_CACHE_TOTAL_CAPTotal cached hits (default 2048)
CASS_DEBUG_CACHE_METRICSEnable cache debug logging
CODING_AGENT_SEARCH_NO_UPDATE_PROMPTSkip update checks

---

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

---

API Contract & Versioning

cass api-version --json
# → { "version": "0.4.0", "contract_version": "1", "breaking_changes": [] }

cass introspect --json
# → Full schema: all commands, arguments, response types

Guaranteed Stable:

  • Exit codes and their meanings
  • JSON response structure for --robot output
  • Flag names and behaviors
  • _meta block format

---

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

---

Troubleshooting

IssueSolution
"missing index"cass index --full
Stale warningRerun index or enable watch
Empty resultsCheck cass stats --json, verify connectors detected
JSON parsing errorsUse --robot-format compact
Watch not triggeringCheck watch_state.json, verify file event support
Reset TUI statecass tui --reset-state or Ctrl+Shift+Del

---

Installation

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

# Windows
irm https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.ps1 | iex

---

Integration with Flywheel

ToolIntegration
CMCASS provides episodic memory, CM extracts procedural memory
NTMRobot mode flags for searching past sessions
Agent MailSearch threads across agent history
BVCross-reference beads with past solutions

Related skills

mattpocockSetup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196kopen.feishu.cnLark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402kjuliusbrusseeCavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7klarksuiteLark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16kxixu-meRunning Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72runcomfy-comCodex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10

Forks & variants (1)

Cass has 1 known copy in the catalog totaling 81 installs. They canonicalize to this original listing.

How it compares

Pick cass for agent session alignment and recall; use standalone issue trackers when the primary need is human sprint planning rather than agent continuity.

FAQ

What is cass?

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. P

When should I use cass?

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. P

Is cass safe to install?

Review the Security Audits panel on this page before installing in production.

AI & Agent Buildingagents
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.