cass

CASS - コーディングエージェントのセッション検索

ローカルのコーディングエージェントの履歴をインデックス化して検索する、統合された高性能な CLI/TUI です。Codex、Claude Code、Gemini CLI、Cline、OpenCode、Amp、Cursor、ChatGPT、Aider、Pi-Agent、Factory (Droid)、OpenHands、Antigravity、Grok Build を含む 23 種類のエージェントのセッションを集約します。

重要：AI エージェントにはロボットモードが必須です

cass をそのまま実行しないでください。セッションをブロックする対話型 TUI が起動します。

# WRONG - blocks terminal
cass

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

機械可読な出力には、必ず --robot または --json フラグを使用してください。

---

AI エージェント向けクイックリファレンス

範囲を絞った履歴の取得

プロジェクトの履歴について簡単に確認する場合は、まず対象を絞ったクエリを 1 つ実行してください。 以下のフラグの組み合わせは cass 0.8.0 で検証済みです。インストールされているバージョンごとに一度、cass --version と cass search --help を確認してください。--no-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 の単位はミリ秒です。--max-tokens はおおよその出力上限であり、CPU やメモリの制限ではありません。さらに、呼び出し側で実時間の期限を設定してください（たとえば、コマンドの前に GNU timeout 10s を指定します）。このラッパーからの終了コード 124 は未完了の試行を示します。中断された標準出力は有効な JSON ではない可能性があります。JSON 検索の出力では、終了コード 0 の場合も budget.timed_out を確認してください。タイムアウトによって検索結果が空でも、履歴が存在しないことの証明にはなりません。

view -C 3 は前後の行数を制限するもので、バイト数やトークン数は制限しません。1 件の JSONL レコードが大きい場合もあります。抜粋をプロンプトに追加する前に、出力サイズを確認してください。

ハイブリッドモードが引き続き製品のデフォルトです。明示的に語彙モードを指定すると、このワークフローで意味的な推論を避けられます。--no-maintenance はインデックスの修復、追いつき処理、デーモンの自動起動を防ぎます。maintenance-required が返された場合は、その障害要因を報告して、この履歴取得の試行を中止してください。要約の依頼を、インデックス作成、修復、モデルのインストール、ワイルドカードによる一括集約、またはステータス確認の繰り返しに切り替えないでください。準備状況の診断には準備状況確認コマンドを使用し、別の変更を伴うタスクを開始する前に、提案された操作を確認してください。クエリが完了した後で、日付や用語の範囲を意図的に広げてください。概念的な検索が必要で、そのコストが許容できる場合に限り、セマンティックモードまたはハイブリッドモードを選択してください。要約では、出典と行番号の引用を保持してください。

必須コマンド

# 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

---

CASS を使う理由

エージェント間の知識共有

コーディングエージェントの知識は、さまざまな場所に分散しています。

• ~/.claude/projects にある Claude Code のセッション
• ~/.codex/sessions にある Codex のセッション
• SQLite データベースにある Cursor の状態
• Markdown ファイルにある Aider の履歴

CASS はこれらすべてを統合し、1 つの検索可能なインデックスにまとめます。問題に行き詰まったときは、過去のすべてのエージェントセッションを検索して、関連する解決策を見つけられます。

ユースケース

# "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

---

コマンドリファレンス

インデックス作成

# 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

検索

# 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

セッション分析

# 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

ステータスと診断

# Readiness diagnosis, when needed; not a prerequisite for every query
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

---

集約と分析

検索結果をサーバー側で集約すると、結果データ全体を転送せずに件数や分布を取得できます。

集約によって出力の量は減りますが、スキャン処理が減るとは限りません。履歴について簡単に確認する場合、最初に集約を使うのではなく、上記の範囲を絞った取得手順を使用してください。

# 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

集約フィールド	説明
agent	エージェントの種類ごとにグループ化（claude_code、codex、cursor など）
workspace	ワークスペース／プロジェクトのパスごとにグループ化
date	日付ごとにグループ化（YYYY-MM-DD）
match_type	一致品質ごとにグループ化（exact、prefix、fuzzy）

各フィールドについて上位 10 件のバケットが返され、残りの項目は other_count に含まれます。

---

リモートソース（複数マシンの検索）

SSH/rsync 経由で、複数のマシンにあるセッションを検索します。

セットアップウィザード（推奨）

cass sources setup

ウィザードでは、次の処理が行われます。

1. ~/.ssh/config から SSH ホストを検出します
2. 各ホストでエージェントのデータと cass のインストール状況を調べます
3. 必要に応じて、リモート環境に cass をインストールします
4. リモート環境のセッションをインデックス化します
5. sources.toml を設定します
6. データをローカルに同期します

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

手動セットアップ

# Add a remote machine
cass sources add [email protected] --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

設定は、~/.config/cass/sources.toml（Linux）または ~/Library/Application Support/cass/sources.toml（macOS）に保存されます。

---

ロボットモードの詳細

自己説明型 API

CASS は、エージェントに自身の使い方を教えます。

# 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

柔軟な構文（エージェントに使いやすい設計）

CASS はよくある間違いを自動修正します。

入力内容	CASS が認識する内容
cass serach "error"	cass search "error"（誤字を修正）
cass -robot -limit=5	cass --robot --limit=5（単一ハイフンを修正）
cass --Robot --LIMIT 5	cass --robot --limit 5（大文字・小文字を統一）
cass find "auth"	cass search "auth"（エイリアスを解決）
cass --limt 5	cass --limit 5（レーベンシュタイン距離 <=2）

コマンドエイリアス：

• 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

出力形式

# 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

設計原則： stdout は JSON のみ、診断情報は stderr に出力します。

トークン予算の管理

LLM にはコンテキスト上限があります。出力サイズを制御できます。

フラグ	効果
--fields minimal	source_path、line_number、agent のみ
--fields summary	title、score を追加
--fields score,title,snippet	フィールドをカスタム選択
--max-content-length 500	長いフィールドを切り詰めます（UTF-8 安全）
--max-tokens 2000	ソフト上限（約 4 文字／トークン）
--limit 5	結果数の上限

切り詰められたフィールドには *_truncated: true インジケーターが含まれます。

---

構造化エラー処理

エラーは、実行可能なヒントを含む JSON 形式です。

{
  "error": {
    "code": 3,
    "kind": "index_missing",
    "message": "Search index not found",
    "hint": "Run 'cass index --full' to build the index",
    "retryable": false
  }
}

終了コード

コード	意味	対応
0	成功	stdout を解析します
1	ヘルスチェック失敗	報告された状態を確認します。自動再構築は行われません
2	使用方法のエラー	構文を修正します（ヒントが提示されます）
3	インデックス／DB が見つからない	不足しているアセットを報告します。インデックス作成は別個の変更タスクです
4	ネットワークエラー	接続を確認します
5	データ／メンテナンスの失敗	エラーの種類を確認し、アーカイブを保持して問題点を報告します
6	互換性のないバージョン	cass を更新します
7	ロック中／使用中	後で再試行します
8	部分的な結果	網羅性が不完全であることを報告し、黙って再試行しないでください
9	不明なエラー	retryable フラグを確認します

コードはコマンドごとに異なります。cass robot-docs exit-codes と JSON エラーの種類を参照してください。検索予算の超過時は、budget.timed_out=true を伴う終了コード 0 が返されることがあります。 セッションパスの出力では、タイムアウト時に終了コード 10 が使われます。

---

検索モード

--mode フラグで選択できる検索モードは 3 種類です。

モード	アルゴリズム	適した用途
lexical	BM25 全文検索	正確な用語の一致、上限付き履歴レシピ
semantic	ベクトル類似度	概念的なクエリ、「類似項目を検索」
hybrid（デフォルト）	Reciprocal Rank Fusion	セマンティック検索の準備が整うと意味的な絞り込みを行う、語彙的な検索

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 は RRF を使用して、語彙検索とセマンティック検索を組み合わせます。

RRF_score = Σ 1 / (60 + rank_i)

---

パイプラインモード（検索の連鎖）

セッションパスをパイプで渡して検索を連鎖させます。

# 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

ユースケース：

• 絞り込み：広範な検索 → 結果内で範囲を絞り込む
• 相互参照：用語 A を含むセッションを検索し、その中から用語 B を検索する
• コーパスの構築：繰り返し検索するためにセッションリストを保存する

---

クエリ言語

基本的なクエリ

クエリ	一致条件
error	"error" を含むメッセージ（大文字・小文字を区別しない）
python error	"python" と "error" の両方
"authentication failed"	完全一致するフレーズ

ブール演算子

演算子	例	意味
AND	python AND error	両方の用語が必要です（デフォルト）
OR	error OR warning	いずれかの用語が一致
NOT	error NOT test	2 番目の用語を除外して、最初の用語に一致
-	error -test	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

ワイルドカードパターン

パターン	種類	パフォーマンス
auth*	前方一致	高速（エッジ n グラム）
*tion	後方一致	低速（正規表現）
*config*	部分一致	最も低速（正規表現）

一致タイプ

結果には match_type が含まれます。

種類	意味	スコアブースト
exact	完全一致	最高
prefix	前方展開による一致	高
suffix	後方パターンによる一致	中
substring	部分文字列パターンによる一致	低
fuzzy	自動フォールバック（結果が少ない場合）	最低

ファジーフォールバックの自動実行

完全一致検索の結果が3件未満の場合、CASS はワイルドカードを使って自動的に再試行します。

• auth → *auth*
• 結果には wildcard_fallback: true のフラグが付けられます

柔軟な時間入力

CASS はさまざまな時間・日付形式に対応しています。

形式	例
相対指定	-7d、-24h、-30m、-1w
キーワード	now、today、yesterday
ISO 8601	2024-11-25、2024-11-25T14:30:00Z
米国式日付	11/25/2024、11-25-2024
Unix タイムスタンプ	1732579200（秒またはミリ秒）

---

ランキングモード

TUI では F12 で切り替えるか、--ranking フラグを使用します。

モード	計算式	最適な用途
新しさ重視	relevance*0.3 + recency*0.7	「何に取り組んでいましたか？」
バランス型	relevance*0.5 + recency*0.5	一般的な検索
関連性重視	relevance*0.8 + recency*0.2	「X の最適な説明」
一致品質	ファジー一致にペナルティを付与	正確な技術検索
日付：新しい順	純粋な時系列順	最近のアクティビティ
日付：古い順	逆時系列順	「最初はいつでしたか……」

スコアの構成要素

• テキスト関連性（BM25）：用語頻度、逆文書頻度、長さの正規化
• 新しさ：指数減衰（今日：約1.0、先週：約0.7、先月：約0.3）
• 一致の正確さ：完全一致=1.0、前方一致=0.9、後方一致=0.8、部分一致=0.6、ファジー一致=0.4

ブレンドスコアの計算式

Final_Score = BM25_Score × Match_Quality + α × Recency_Factor

モード	α 値	効果
新しさ重視	1.0	新しさが優先されます
バランス型	0.4	新しさが適度に加味されます
関連性重視	0.1	BM25 が優先されます
一致品質	0.0	純粋なテキスト一致

---

対応エージェント（23 コネクター）

エージェント	場所	形式
Claude Code	~/.claude/projects	JSONL
Codex	~/.codex/sessions	JSONL（Rollout）
Gemini CLI	~/.gemini/tmp	JSON
Cline	VS Code のグローバルストレージ	タスクディレクトリ
OpenCode	.opencode ディレクトリ	SQLite
Amp	~/.local/share/amp + VS Code	混在
Cursor	~/Library/Application Support/Cursor	SQLite（state.vscdb）
ChatGPT	~/Library/Application Support/com.openai.chat	JSON（v1 暗号化なし）
Aider	~/.aider.chat.history.md + プロジェクトごと	Markdown
Pi-Agent	~/.pi/agent/sessions	思考を含む JSONL
Factory (Droid)	~/.factory/sessions	ワークスペースごとの JSONL
GitHub Copilot Chat	VS Code のグローバルストレージ	JSON / SQLite
GitHub Copilot CLI	~/.copilot/session-state	JSONL
OpenClaw	~/.openclaw	JSONL
ClawdBot	~/.clawdbot	JSONL
Vibe	~/.vibe/logs/session	JSONL
Crush	~/.crush/crush.db	SQLite
Hermes	~/.hermes	JSONL
Kimi Code	~/.kimi/sessions	JSONL
Qwen Code	~/.qwen/tmp	JSON / JSONL
OpenHands	~/.openhands/conversations	JSON イベントストリーム
Antigravity	~/.gemini/antigravity-cli	JSONL / SQLite
Grok Build	$GROK_HOME/sessions（デフォルト：~/.grok/sessions）	ACP 更新 JSONL

注： ChatGPT v2/v3 は AES-256-GCM で暗号化されています（キーチェーンへのアクセスが必要です）。暗号化されていない旧式の v1 会話は自動的にインデックスされます。

---

TUI の機能（人間向け）

cass を引数なしで起動します。

キーボードショートカット

ナビゲーション：

• Up/Down：選択項目を移動
• Left/Right：ペインを切り替え
• Tab/Shift+Tab：フォーカスを順に切り替え
• Enter：$EDITOR で開く
• Space：全画面の詳細ビュー
• Home/End：最初／最後の結果に移動
• PageUp/PageDown：ページ単位でスクロール

フィルタリング：

• F3：エージェントフィルター
• F4：ワークスペースフィルター
• F5/F6：時間フィルター（開始／終了）
• Shift+F3：現在の結果のエージェントに絞り込む
• Shift+F4：ワークスペースフィルターをクリア
• Shift+F5：プリセットを切り替え（24h/7d/30d/all）
• Ctrl+Del：すべてのフィルターをクリア

モード：

• F2：テーマを切り替え（6種類のプリセット）
• F7：コンテキストウィンドウのサイズ（S/M/L/XL）
• F9：一致モード（prefix/standard）
• F12：ランキングモード
• Ctrl+B：枠線のスタイルを切り替え

選択とアクション：

• m：選択を切り替え
• Ctrl+A：すべて選択
• A：一括操作メニュー
• Ctrl+Enter：キューに追加
• Ctrl+O：キュー内の項目をすべて開く
• y：パス／内容をコピー
• Ctrl+Y：選択した項目をすべてコピー
• /：詳細ペイン内を検索
• n/N：次／前の一致箇所

ビューとパレット：

• Ctrl+P：コマンドパレット
• 1-9：保存済みビューを読み込む
• Shift+1-9：ビューをスロットに保存

ソースフィルタリング（複数マシン）：

• F11：ソースフィルターを切り替え（all/local/remote）
• Shift+F11：ソース選択メニュー

全般：

• Ctrl+C：終了
• F1 または ?：ヘルプを切り替え
• Ctrl+Shift+R：強制的に再インデックス
• Ctrl+Shift+Del：TUI の状態をすべてリセット

詳細ペインのタブ

タブ	内容	切り替え方法
Messages	Markdown 形式の会話全体	[ / ]
Snippets	キーワードから抽出した要約	[ / ]
Raw	未整形の JSON／テキスト	[ / ]

コンテキストウィンドウのサイズ設定

サイズ	文字数	用途
Small	~200	すばやく確認
Medium	~400	バランスの取れたデフォルト表示
Large	~800	長めの文章
XLarge	~1600	コンテキスト全体、コードレビュー

Peek モード（Ctrl+Space）：デフォルトを変更せず、一時的に XL まで拡大します。

---

テーマプリセット

F2 で組み込みの6種類のテーマを切り替えます：

テーマ	説明	最適な用途
Dark	Tokyo Night をイメージした深い青	暗い環境
Light	コントラストの高い明るい背景	明るい環境
Catppuccin	目の疲れを抑える温かみのあるパステルカラー	一日中のコーディング
Dracula	紫をアクセントにしたダークテーマ	人気の開発者向けテーマ
Nord	北極をイメージしたクールな色調	落ち着いて集中できる作業
High Contrast	最大限の読みやすさ	アクセシビリティのニーズ

すべてのテーマは、WCAG のコントラスト要件（テキストは最低 4.5:1）に照らして検証済みです。

役割に応じたメッセージスタイル

役割	表示スタイル
User	青みがかった背景、太字
Assistant	緑みがかった背景
System	グレー／控えめな背景
Tool	オレンジみがかった背景

---

保存済みビュー

フィルター設定を9つのスロットに保存し、すぐに呼び出せます。

保存される項目：

• 有効なフィルター（エージェント、ワークスペース、時間範囲）
• 現在のランキングモード
• 検索クエリ

キーボード操作：

• Shift+1 から Shift+9：現在のビューを保存
• 1 から 9：スロットからビューを読み込む

コマンドパレットから： Ctrl+P → 「ビューを保存／読み込む」

ビューはセッションをまたいで tui_state.json に保存されます。

---

密度モード

検索結果ごとの行数を設定します。Shift+D で切り替えます：

モード	行数	最適な用途
Compact	3	表示できる結果数を最大化
Cozy	5	バランスの取れた表示（デフォルト）
Spacious	8	詳細なプレビュー

---

ブックマークシステム

メモやタグを付けて、重要な結果を保存します：

TUI で b を押してブックマークし、メモとタグを追加します。

ブックマークの構造：

• title：短い説明
• source_path、line_number、agent、workspace
• note：注釈
• tags：カンマ区切りのラベル
• snippet：抽出された内容

保存先：~/.local/share/coding-agent-search/bookmarks.db（SQLite）

---

オプションのセマンティック検索

MiniLM を使用したローカル限定のセマンティック検索（クラウド不使用）：

必須ファイル（data ディレクトリに配置してください）：

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

ベクトルインデックスは vector_index/index-minilm-384.cvvi に保存されます。

CASS はモデルを自動ダウンロードしません。手動でインストールする必要があります。

ハッシュ埋め込みのフォールバック： MiniLM がインストールされていない場合、CASS はハッシュベースの埋め込み器を使用して、おおよそのセマンティック類似度を算出します。

---

ウォッチモード

リアルタイムのインデックス更新：

cass index --watch

• デバウンス： 2 秒（変更が落ち着くまで待機）
• 最大待ち時間： 5 秒（変更が続いている間も強制的に反映）
• 増分更新： 変更されたファイルのみを再スキャン

TUI はバックグラウンドでウォッチモードを自動的に開始します。

---

重複排除の方針

CASS は多層の重複排除を行います：

1. メッセージハッシュ： (role + content + timestamp) の SHA-256。重複するメッセージは一度だけ保存されます
2. 会話フィンガープリント： 先頭 N 件のメッセージハッシュのハッシュ値。重複ファイルを検出します
3. 検索時の重複排除： コンテンツの類似性に基づいて結果を重複排除します

ノイズのフィルタリング：

• 空のメッセージと空白のみのメッセージ
• システムプロンプト（検索対象にする場合を除く）
• 繰り返されるツールの確認応答

---

パフォーマンス特性

レイテンシとメモリ使用量は、アーカイブのサイズ、インデックスの準備状況、モデルの状態、プロセスがコールド状態かどうかによって異なります。過去の小規模コーパスでの計測時間は、大規模なアーカイブでの完了期限を保証するものではありません。コマンド全体の実行時間を計測し、各検索試行に上限時間を設定して、成功した結果とタイムアウトまたはメンテナンスによる拒否を区別してください。

---

レスポンス形式

検索レスポンス：

{
  "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 }
  }
}

集計レスポンス：

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

---

環境変数

変数	用途
CASS_DATA_DIR	データディレクトリを上書きします
CHATGPT_ENCRYPTION_KEY	暗号化された ChatGPT 用の Base64 キー
PI_CODING_AGENT_DIR	Pi-Agent セッションのパスを上書きします
CASS_CACHE_SHARD_CAP	シャードごとのキャッシュエントリ数（デフォルト 256）
CASS_CACHE_TOTAL_CAP	キャッシュするヒットの合計数（デフォルト 2048）
CASS_DEBUG_CACHE_METRICS	キャッシュのデバッグログを有効にします
CODING_AGENT_SEARCH_NO_UPDATE_PROMPT	アップデートの確認をスキップします

---

シェル補完

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 契約とバージョニング

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

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

安定性が保証される項目：

• 終了コードとその意味
• --robot 出力の JSON レスポンス構造
• フラグの名前と動作
• _meta ブロックの形式

---

CASS Memory（cm）との連携

CASS はエピソード記憶（生のセッション）を提供します。CM は手続き記憶（ルールやプレイブック）を抽出します：

# 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

---

トラブルシューティング

問題	解決策
"missing index" / maintenance-required	問題となっている要因を報告し、検索と、承認を得たインデックス作成・修復を分けてください
古いという警告	経過時間とカバー範囲を報告し、更新するかどうかは別途判断してください
結果が空	budget.timed_out を確認してください。その後、試行が完了していた場合はクエリの範囲を見直してください
JSON の解析エラー	--robot-format compact を使用してください
ウォッチが動作しない	watch_state.json を確認し、ファイルイベントがサポートされていることを確かめてください
TUI の状態をリセットする	cass tui --reset-state または Ctrl+Shift+Del

---

インストール

# 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

---

Flywheel との連携

ツール	連携内容
CM	CASS はエピソード記憶を提供し、CM は手続き記憶を抽出します
NTM	過去のセッションを検索するためのロボットモードのフラグ
Agent Mail	エージェントの履歴からスレッドを検索します
BV	beads と過去の解決策を相互参照します