cass

cass セッション検索

目次

• 金鉱の原則
• 正確なプロンプト — 発見ワークフロー
• バージョン固定に関する注意事項
• 2 段階のブートストラップ（「必ず最初に」を置き換える）
• インデックス停止時の復旧判断フローチャート
• クイックリファレンス
• 用途別の使い分け
• 重要なルール
• エージェントハーネスの除外
• 検索モード
• マシンをまたいだ検索（複数ワークステーションのコーパス）
• アンチパターン（避けるべきこと）
• 過去のセッションを本来のハーネスで再開する
• ヒューリスティクス
• jq の基本
• 隠れた機能：以前のスキルで見落とされていた機能
• トークンとコストの分析（追加のユースケース）
• 復旧用チートシート（権限不要の手段）
• リファレンス一覧
• クイック検索（リファレンス用 Grep レシピ）
• スクリプト
• 検証

核心となる洞察： 繰り返し使っているプロンプトこそ、最良のプロンプトです。10 回以上入力したものがあれば、それは効果があります。履歴を掘り起こしましょう。

金鉱の原則

会話履歴には、次のものが含まれています。

• 洗練されたプロンプト — よりうまくいった言い換えはすべて記録されています
• 機能する定型手順 — 10 回以上繰り返されたプロンプトは、あなたの方法論そのものです
• スコープに関する判断 — 「X をしないと決めたのはいつか？」
• 復旧時の行動 — コンテキストを失った後に何を検索したかが、何が重要だったかを示します

洞察： 新しいアプローチを考案するより、過去を掘り起こすほうが効果的です。

---

正確なプロンプト — 発見ワークフロー

1. Bootstrap: Check health, refresh only if stale (capped, in the background), get project overview
   cass status --json
   # if .index.stale == true:  ( timeout 600 cass index --json >/tmp/cass-index.$$.log 2>&1 </dev/null & )
   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

このワークフローが機能する理由

• まずは集計 — 詳細に踏み込む前に、全体像を把握します
• --fields minimal — 出力を 5 倍小さくし、コンテキストウィンドウを節約します
• line_number <= 3 — ユーザープロンプトはセッションの冒頭にあります
• コンテキストのクラスタリング — 作業はまとまって進みます。1 件の有用な結果から、関連するセッションが次々に見つかります

---

バージョン固定に関する注意事項

cass は急速に進化しています。このスキルは HEAD の動作（/dp/coding_agent_session_search にある最新のソース）について説明しています。リリース済みの v0.3.6 バイナリには、それ以降に追加されたいくつかの機能がありません。

• cass sources agents {list,exclude,include} — 2026-04-20 に追加（コミット 82d8d70e）
• 全件再構築時の末尾における writer-race への耐性 — 2026-04-22 に修正（コミット e06342f2、bead zz8ni）
• フェデレーションインストール向けの語彙生成マニフェスト（コミット 2b7b86a1、683ccd03、cf76fe15）
• 再構築プロデューサーの停止状況のテレメトリー（コミット 73a86604）

フラグやサブコマンドが「認識されない」と表示されたり、ドキュメントの説明と異なる動作をしたりする場合は、cass --version を実行し、該当コミットを git log -- src/lib.rs で確認してください。該当する各セクションには、依存するコミットやバージョンが記載されています。

インストール済みのバイナリが実際にサポートしている機能を確認します。

cass capabilities --json | jq '{version: .crate_version, features, connectors}'
cass introspect --json   | jq '.commands[].name'

---

2 段階のブートストラップ（「常に最初に実行」を置き換え）

重要なのは 3 つの状態です。決して混同しないでください。

状態	意味	対応
cass health の終了コードが 0	50 ミリ秒未満の事前チェックに合格しました	すぐに検索します
cass health の終了コードが 1 で、index.stale=true	インデックスは使用可能ですが古い状態です	すぐに検索し、実時間の上限を設けてバックグラウンドで更新します：( timeout 600 cass index --json &>/tmp/cass-bg.log </dev/null & )（裸の & は絶対に使わないでください。cass index がハングする可能性があります）
cass status が database.exists=false または documents=0 を返す	本当に破損している／未初期化状態です	cass doctor --fix --json を実行してから、cass index --full --json を実行します

落とし穴： 古いインデックスを破損状態として扱うと、増分更新（1～3 秒）や、古くても正確なクエリで済んだはずなのに、不要なフル再構築（8～25 秒）が発生します。

# Robust two-step bootstrap that never blocks the user.
# IMPORTANT: every cass index call gets a wall-clock cap. cass index has been
# observed to hang indefinitely under contention — without `timeout`, the
# bootstrap itself becomes the symptom.
cass status --json | jq '{healthy, fresh: .index.fresh, stale: .index.stale, db: .database.exists, sem: .semantic.available}'

# Refresh policy: stale → bg refresh (capped); never block search
if [ "$(cass status --json | jq -r '.index.stale')" = "true" ]; then
  ( timeout 600 cass index --json >"/tmp/cass-index.$$.log" 2>&1 </dev/null & ) 2>/dev/null
fi
# Search even with stale index — results are still useful
cass search "KEYWORD" --workspace /path --json --fields minimal --limit 10

このロジックの本番品質版（すべての呼び出しへの上限設定、破損状態へのエスカレーション、フックの終了コードのセマンティクス）には、scripts/recover.sh を使用してください。タイムアウトと PID ごとのログを使って、完全な判断ツリーを実装しています。

古い状態で cass health が終了コード 1 を返すのは、cron／CI 向けの意図的な事前チェック信号です。対話型のエージェントループでは、cass status --json を優先して、状態を判断してください。

---

インデックス作成の停滞と復旧の判断ツリー

実際に発生した不具合です（すべて収集したセッションで確認済み）。上から順に確認してください。最初に一致した項目を適用します。

症状	考えられる原因	自動修正（ユーザーへの確認不要）
cass index --json が phase: indexing, current: 0, total: N を2分以上ストリーミングし続ける	v0.3.6 の未解決の issue #196：以前に --force-rebuild を実行した後、増分インデックス作成が停止する	実行を終了し、cass index --full --force-rebuild --json を実行します（通常25秒）
cass status に index.rebuilding=true と古い pid（1時間以上前）が表示される	クラッシュしたインデクサーがロックを残した	cass doctor --fix --json を実行します（古い .index.lock が自動的に削除されます）
cass search のヒット数が0なのに、ファイルに明らかに検索語が含まれている	検索語がツールの stdout/stderr にあり、インデックス作成時にスキップされた	rg -n "TERM" /path/to/session.jsonl にフォールバックします
cass search --workspace /X は0件を返すが、--workspace なしの同じクエリでは検索できる	ワークスペース文字列の不一致	cass search "KEYWORD" --aggregate workspace --limit 1 --json で正規パスを確認してから、再実行します
vtable constructor failed: fts_messages（古い不具合で、0.3.0以降では修正済み）	アップグレード後にDBとFTSのスキーマがずれた	cass doctor --fix --json を実行すると、SQLite から Tantivy 側が再構築されます
--limit 0 panic	以前の cass バージョンでは limit=0 でパニックが発生した	集計には必ず --limit 1（または --limit 5）を指定します
cass のプロジェクトディレクトリに巨大な core.NNNNN ファイルがある	過去にインデクサーがクラッシュし、コアダンプが記録された	そのまま残しても安全です。検索には影響しません。削除するのは、ユーザーから明示的な許可があった場合に限ります。
Windows で cass models install が WSAENOTCONN エラーで失敗する（クローズ済みの #193）	huggingface からのダウンロード中にネットワークが一時的に切断された	1回再試行します。解消しない場合は --mirror <URL> で別の HF ミラーを指定するか、モデルがローカルにキャッシュされている場合は --from-file <DIR> を使います。その後、cass models verify を実行します。
cass index に「Index rebuild is already in progress」と表示されるが、何も見えない	別のエージェントが同時に再構築を開始した	無理に中断しないでください。`cass status --json
cass index --full --force-rebuild --json が200秒以上実行された後、"index failed: updating last_indexed_at after index run ... database is busy" と表示して終了する	persist_final_index_run_metadata での同時再構築の競合。HEAD（commit e06342f2、bead zz8ni）で修正済み。v0.3.6以前に影響します。	インデックスデータが正常か確認します：`cass search "X" --limit 1 --json
再構築が成功したように見えるのに、cass status がいつまでも unhealthy と表示する	上記と同じです。タイムスタンプマーカーが書き込まれていません	同じ方法で修正します。検索でヒットすることを確認し、cass index --json を1回実行すると、マーカーが書き込まれます。適切な修正を利用するには、v0.3.6 より新しいバージョンにアップグレードします

cass を使わず、手動の find／grep にフォールバックしてごまかすのは絶対に避けてください。 上記の自動修正を使えば、実際に発生したすべての問題をユーザーの介入なしで解決できます。ユーザーに「インデックスを再構築してください」と頼むのは最悪の結果です。エージェントが待機しているのです。

---

クイックリファレンス

# Health first; refresh only when stale, always with a wall-clock cap (see Two-Step Bootstrap)
cass status --json
[ "$(cass status --json | jq -r '.index.stale')" = "true" ] && ( timeout 600 cass index --json >/tmp/cass-index.$$.log 2>&1 </dev/null & )

# Project overview: who did what, when?
cass search "*" --workspace /path --aggregate agent,date --limit 1 --json

# Find keyword, minimal output
cass search "KEYWORD" --workspace /path --json --fields minimal --limit 50

# Follow a hit
cass view /path.jsonl -n LINE -C 20        # Line-oriented
cass expand /path.jsonl --line LINE --context 3  # Message-oriented

# Find related sessions
cass context /path.jsonl --json

# Export for parsing
cass export /path.jsonl --format json --include-tools -o /tmp/out.json

# Inspect or change persistent agent-harness exclusions
cass sources agents list --json
cass sources agents exclude openclaw
cass sources agents exclude openclaw --keep-indexed-data
cass sources agents include openclaw

---

状況に応じた使い分け

目的	使用するもの	理由
プロジェクトの概要	--aggregate agent,date --limit 1	件数のみで、内容は含みません
プロンプトを検索する	--fields minimal + jq select(.line_number <= 3)	ユーザーのプロンプトは1～3行目です
定型作業の検出	一致数を数えます：10件を超えれば定型作業	繰り返されているものは機能しています
会話全体	cass expand --context 3	メッセージの境界が保持されます
生の JSON を解析する	cass export --include-tools -o file.json	エクスポート結果をパイプに通さないでください
コンテンツが見つからない	rg "string" /path.jsonl	cass はツールの出力をスキップします
ノイズの多いハーネスがインデックスを埋め尽くす	cass sources agents exclude <agent>	今後のインデックス作成を継続的に無効にします

---

重要なルール

ルール	理由	結果
--limit 1 が最低値	--limit 0 はパニックを引き起こします	集約には 1 を使用します
--fields minimal	トークン効率	出力が 5 分の 1 に縮小します
ファイルにエクスポート	パイプ処理で broken pipe パニックが発生します	必ず -o /tmp/out.json を指定します
ワークスペースのパスを正確に指定	大文字と小文字を区別して照合します	--aggregate workspace を使って確認します
--include-tools	デフォルトではツール呼び出しが非表示です	完全なエクスポートに必須です

---

エージェントハーネスの除外

あるエージェントハーネスが無意味な出力やループを生み出している、またはディスクを使いすぎているとユーザーから言われた場合、除外できないと伝えるのではなく、cass で直接対処します。

# See current state
cass sources agents list --json

# Persistently stop indexing this harness in future scans/syncs/watch mode
cass sources agents exclude openclaw

# Keep already indexed data but block future indexing
cass sources agents exclude openclaw --keep-indexed-data

# Re-enable later
cass sources agents include openclaw

exclude が実際に行うこと

• 設定を sources.toml に書き込み、以後の実行でも保持します
• ソースファイルがディスク上に残っていても、以後のインデックス作成を防ぎます
• デフォルトでは、そのハーネスのアーカイブ済みローカルデータを削除し、字句検索を再構築します。これにより、除外によって容量も解放されます

使用する状況

• ハーネスがループする出力や価値の低い出力を大量に生成している
• 「今後、このソースを無視する」よう cass に記憶させたい
• ソースファイルを手動で削除せず、元に戻せるエージェントに適した方法でアーカイブの肥大化を抑えたい

---

検索モード

モード	使用する状況	例
lexical（デフォルト）	正確な文字列、ファイル名	"AGENTS.md"、"--workspace"
semantic	概念的な内容、表現が不明な場合	"scope reduction discussions"
hybrid	幅広く調べる場合	"architecture decisions"

デフォルトでは lexical を使用してください。 正確な表現がわからない場合にのみ、semantic を使用してください。

Semantic / Hybrid を有効にする（初回のみ）

cass models status --json    # state: not_installed | installed | partial
cass models install          # downloads ~90MB MiniLM bundle from HuggingFace
cass index --semantic --build-hnsw --json   # builds vector + HNSW
cass search "QUERY" --mode hybrid --json    # then queries fall back to lexical if semantic missing

モデルが not_installed の場合、--mode hybrid と --mode semantic はエラーを出さずに lexical にフォールバックします。パニックも、機能が低下した状態になることもありません。詳しくは SEMANTIC_AND_HYBRID.md を参照してください。

---

マシン間検索（複数ワークステーションのコーパス）

ユーザーが css、csd、ts1、ts2 などでエージェントを実行している場合、各マシンの cass コーパスは互いに独立しています。マシンをまたいで検索する方法は 3 つあります。

# Option A: One-shot remote query (no setup, slow per call)
ssh css 'cass search "KEYWORD" --json --fields minimal --limit 20' | jq '.hits'

# Option B: Configured sources (preferred — caches the remote sessions locally)
cass sources setup                                      # interactive wizard, auto-discovers from ~/.ssh/config
cass sources add ssh://user@css --name css --preset linux-defaults
cass sources sync --source css --json                   # rsyncs new sessions, then re-indexes
cass search "KEYWORD" --json                            # results now span all configured sources
cass sources list --json                                # see what's wired up

# Option C: Parallel fan-out (when speed matters more than dedup)
for h in css csd ts1 ts2; do
  ssh "$h" 'cass search "KEYWORD" --json --fields minimal --limit 10' > "/tmp/cass-$h.json" &
done
wait
jq -s '[.[] | .hits[]] | unique_by(.source_path + (.line_number|tostring))' /tmp/cass-*.json

cass sources doctor で接続状況を診断できます。設定済みソースの検索結果には、ヒットのメタデータに origin_host が含まれます。ユーザーに結果を報告する際は、この情報を保持してください。詳しくは、REMOTE_SOURCES.md を参照してください。

---

アンチパターン（やってはいけないこと）

アンチパターン	問題点	代わりに行うこと
ユーザーに「インデックスを再構築しますか？」と尋ねる	エージェントが待機しています。再構築は安全で、何度実行しても結果は変わりません	cass doctor --fix --json をそのまま実行します（ソースデータは保持されます）
status が異常と示すたびに cass index --full を実行する	30 分古いインデックスに対して 25 秒かけて再構築するのは無駄です	index.stale と database.exists を個別に確認し、増分処理を優先します
「何があるか確認する」ために cass をそのまま実行する	エージェントのセッションで、操作をブロックする TUI が起動します	常に --json または --robot を指定します。単独では実行しません
cass export を head／jq にパイプする	大きなセッションでは broken-pipe panic が発生します	先に cass export ... -o /tmp/x.json を実行し、その後ファイルを操作します
サブエージェントのファイルを親セッションと同じものとして扱う	サブエージェントは、2 行目に独自のプロンプトを持つ別個の会話ログです	select(.source_path | contains("subagent")) で絞り込みます
「制限なし」の意味で --limit 0 を使う	以前の cass では panic が発生します。現在の cass は RAM の上限で制限しますが、通常は意図した動作ではありません	適切な制限（--limit 50）を使うか、--cursor でページネーションします
--workspace /X で検索し、結果が 0 件でも信用する	ワークスペースの文字列では大文字・小文字と末尾のスラッシュが区別されます	結果が 0 件でもヒットするはずだった場合は、--aggregate workspace --limit 1 を指定して再実行し、正式なキーを確認します
大量の検索で --fields minimal を省略する	デフォルトの full は、1 件あたり約 3 KB × 100 件で、コンテキストを 300 KB 消費します	大量に検索するときは常に --fields minimal を指定し、残す数件だけ summary／full に切り替えます
プロンプトを抽出するために、セッションファイルを cat で読む	会話全体がコンテキストに読み込まれます	cass view PATH -n LINE -C 5（ウィンドウ）または cass expand PATH --line LINE --context 3（メッセージ認識型）を使います
cass search のたびに再インデックスする	無駄です。インデックスはプロセス間で共有されます	インデックスは共有されています。cass status が stale を示す場合、または recommended_action が推奨する場合にのみ更新します

---

過去のセッションをネイティブなハーネスで再開する

cass resume は、セッションパスをネイティブ CLI が会話を続けるために使う正確なコマンドに変換します。対象は Claude Code、Codex、Gemini、OpenCode、pi_agent です。

# Find a relevant past session
cass search "KEYWORD" --json --fields minimal --limit 5 \
  | jq -r '.hits[0].source_path' > /tmp/sess.path

# Print the resume command without executing
cass resume "$(cat /tmp/sess.path)" --shell

# Or replace the current process with the resumed agent
cass resume "$(cat /tmp/sess.path)" --exec

注意点： サブエージェントのファイル（subagents/agent-*.jsonl）は、設計上、再開できません。親によってオーケストレーションされています。--agent claude を渡すよう案内する session_id_not_found が表示されます。まず cass context <path> --json で親セッションを解決してください。RESUME.md を参照してください。

---

ヒューリスティクス

シグナル	意味	アクション
line_number が 1～3	ユーザープロンプト	select(.line_number <= 3) で絞り込みます
/subagents/ の 2 行目	THE extraction prompt	コピー＆ペーストですぐに使えます
total_matches > 10	定型パターン	文書化して再利用します
結果が 0 件 ＋ コンテンツが存在	ワークスペースパスの不一致	--aggregate workspace を使います

---

jq の基本

# User prompts only
| jq '[.hits[] | select(.line_number <= 3)]'

# Source paths for follow-up
| jq '.hits[].source_path' -r

# Aggregation buckets
| jq '.aggregations.agent.buckets'

# Count matches
| jq '.total_matches'

# Find repeated prompts (ritual detection)
| jq '[.hits[] | select(.line_number <= 3) | .title[0:80]] | group_by(.) | map({prompt: .[0], count: length}) | sort_by(-.count) | .[0:20]'

---

隠れた実力：以前のスキルが見逃していた機能

コマンド	得られるもの	使用するタイミング
cass health	50 ミリ秒未満で終了コードのみを返す事前チェック	Cron ／フックのゲート処理
cass index --watch --json	ファイルシステムウォッチャーがインデックスを最新状態に維持します。1 サイクルだけ実行する場合は --watch-once /path	長時間稼働するオーケストレーターホスト
cass index --idempotency-key K --json	同一キーのレスポンスを 24 時間キャッシュします	再試行される CI 実行
cass index --semantic --build-hnsw	O(log n) の近似ベクトル検索	cass models install の後
cass doctor --fix --json	DB からインデックスを自動再構築し、破損した DB を .corrupt.<ts> にバックアップします	status.healthy=false のときはいつでも
cass resume PATH --shell	異なるハーネス間で使える再開コマンドを出力します	過去の Codex／Claude／Gemini セッションの続行
cass sources setup	ssh-config に対応した、複数マシン用の対話型ウィザード	マシン群を初めて接続するとき
cass sources sync --source NAME --json	rsync でリモートセッションを同期し、その後インデックスを再構築します	マシン群の定期的な更新
cass sources doctor --json	接続性とパスを検査します	マシン間の結果に依存する前
cass sources mappings ...	ソースのパスをローカルの同等パスに書き換えます	ワークスペースの移動後
cass sources agents {list,exclude,include}	ハーネスの除外設定を永続化します（~/.config/cass/sources.toml に disabled_agents を書き込みます）	openclaw ／ノイズの多いコネクターによってインデックスがあふれるとき
cass models install / status / verify / remove	MiniLM バンドル（約 90 MB）を管理します	セマンティック検索を有効にするとき
cass analytics tokens | tools | models	インデックス化されたセッションから、日別／ツール別／モデル別の使用状況統計を取得します	コストレポート、リグレッションチェック
cass analytics rebuild --json	coverage_pct が低い場合に、ロールアップテーブルを過去分まで補完します	大量の import または sources sync の後
cass analytics validate --json	生データ行とロールアップ間のずれを検出します	数値を報告する前の健全性チェック
cass import chatgpt PATH	ChatGPT ウェブからエクスポートした conversations.json をコーパスに取り込みます	ChatGPT.com から移行するとき
cass export-html PATH --password ...	暗号化された、単体で動作する HTML 会話ビューアーを作成します	1 つのセッションをチームメイトと共有するとき
cass pages encrypt ARCHIVE --with-recovery	静的ホスティング向けの、暗号化された検索可能なアーカイブを作成します	編集済みコーパスを公開するとき
cass introspect --json	すべてのコマンドとレスポンスのスキーマを完全に出力します	プログラムから機能を調べるとき
cass capabilities --json	自己設定に必要な機能／コネクター／制限を出力します	バージョンに応じたフォールバック
cass robot-docs guide | commands | examples | schemas | contracts	マシン向けの組み込みドキュメント	スキルだけでは不十分な場合のエージェントループ内
cass --robot-format jsonl | compact | toon | sessions	ストリーミング対応／トークン最適化／シェルパイプで利用可能な出力	大量の検索結果、連鎖検索
cass --trace-file FILE	低速実行のデバッグ用に、スパンのタイミングを JSONL 形式で出力します	パフォーマンス問題のトリアージ

ここに記載されたフラグが「認識されない」というエラーになる場合、インストール済みの cass バイナリはソースより古いバージョンです。cass --version と上流の git log -- src/lib.rs を確認してください。不足しているコマンドの多くは v0.3.x で追加されました。

---

トークンとコストの分析（追加のユースケース）

# Daily token usage across your whole agent fleet
cass analytics tokens --days 30 --group-by day --json | jq '.data.buckets[].api_tokens'

# Per-agent tool-use intensity (rows are keyed by agent slug, not tool name)
cass analytics tools --days 30 --json | jq '.data.rows[0:10]'

# Top models by API tokens
cass analytics models --json | jq '.data.by_api_tokens.rows[0:10]'

# After import / sync, refresh rollups
cass analytics rebuild --json
cass analytics validate --json   # confirm no drift between raw and rollup

cass analytics status --json では coverage_pct が表示されます。約 90% 未満の場合、過去分を補完するために analytics rebuild を実行してください。ANALYTICS.md を参照してください。

---

復旧チートシート（許可不要の操作）

コーパスを検索可能な状態に保つため、これらの操作は事前に許可されています。いずれもソースのセッションデータを破棄せず、派生したインデックスデータのみを再構築します。

cass doctor --json --verbose         # Diagnose without changing anything
cass doctor --fix --json             # Apply safe rebuilds; backs up bad DB to .corrupt.<ts>
cass doctor --fix --force-rebuild --json   # Same, but rebuild even when healthy
cass index --full --force-rebuild --json   # Workaround for OPEN issue #196 (incremental hang)
cass sources doctor --json           # Probe remote sources
cass sources sync --source NAME --json     # Re-fetch and re-index a single source
cass models install                  # Restore missing semantic model
cass models verify                   # Validate model file checksums

明示的な許可なしに行ってはいけないこと：core.NNNNN ファイルの削除、.beads/ の削除、git reset --hard、ユーザーの .config/cass/sources.toml 内の手動編集。上記の CLI コマンドを使えば、すべて安全に実行できます。

暗号化された Pages アーカイブの完全な災害復旧手順：RECOVERY.md。

---

リファレンス一覧

内容	リファレンス
コマンドの完全なリファレンス	COMMANDS.md
ワークフローのレシピ	RECIPES.md
jq パターン	PATTERNS.md
注意点と対処法	PITFALLS.md
セッションファイル形式	SESSION_FORMATS.md
リモートソース、複数マシン	REMOTE_SOURCES.md
セマンティック検索／ハイブリッド検索／モデル	SEMANTIC_AND_HYBRID.md
トークン／ツール／モデルの分析	ANALYTICS.md
ハーネスをまたいだセッションの再開	RESUME.md
Doctor と自律的な復旧	RECOVERY.md
採掘したゴールドスタンダードのプロンプト	PROMPTS.md
アンチパターン（詳細版）	ANTI_PATTERNS.md
ヘルスとステータスとインデックスの違い	OBSERVABILITY.md
Pages の暗号化アーカイブと HTML エクスポート	PAGES_AND_EXPORT.md
ハーネスの除外（disabled_agents）	HARNESS_EXCLUSION.md
スキーマのイントロスペクション契約	INTROSPECTION.md

---

クイック検索（リファレンス向け grep レシピ）

適切なリファレンスがタイトルからすぐに分からない場合は、リファレンスディレクトリを直接 grep してください。ファイル全体をコンテキストに読み込むより低コストです。

REFS=.claude/skills/cass/references

# Find any anti-pattern by symptom keyword
grep -ni "limit 0\|broken pipe\|workspace path\|stale" "$REFS"/ANTI_PATTERNS.md "$REFS"/PITFALLS.md

# Find the recipe / jq for a task
grep -niE "ritual|user prompt|aggregate|subagent|cluster|timeline" "$REFS"/RECIPES.md "$REFS"/PATTERNS.md

# Find a recovery recipe (issue numbers, error strings, fix names)
grep -niE "doctor|--force-rebuild|issue #196|last_indexed_at|database is busy|core\." "$REFS"/RECOVERY.md "$REFS"/OBSERVABILITY.md

# Find a flag, command, or response field
grep -niE "robot-format|--mode|--cursor|_meta|fallback_mode|hits_clamped" "$REFS"/COMMANDS.md "$REFS"/INTROSPECTION.md

# Find a real "what did I ask" prompt template you've used before
grep -ni "use cass\|find that\|session history\|what worked" "$REFS"/PROMPTS.md

# Find harness/connector slugs and exclusion behavior
grep -niE "openclaw|disabled_agents|sources agents" "$REFS"/HARNESS_EXCLUSION.md "$REFS"/REMOTE_SOURCES.md

# Find resume / cross-harness behavior
grep -niE "resume|--shell|--exec|subagent.*not resumable" "$REFS"/RESUME.md

これらのコマンドはリファレンスディレクトリ全体を 50ms 未満で grep し、ファイル名と行を表示します。その後、Read ツールで該当箇所を開けます。リファレンス全体を読むよりはるかに低コストです。

---

スクリプト

スクリプトは scripts/ にあります。コンテキストトークンを一切消費せず、実行されるだけで読み込まれません。明示的な確認なしに状態を変更するスクリプトはありません。

スクリプト	用途
./scripts/quick_analysis.sh /path	コマンド 1 つでプロジェクトの概要を確認（status → エージェント／日付の集計 → 上位のプロンプト）
./scripts/prompt_miner.py --workspace /path	繰り返されるプロンプトを検出（儀式的な反復の検出）
./scripts/validate.sh	cass のインストールとスキル構造を検証
./scripts/recover.sh	自律的な復旧の判断ツリー（READY → STALE_BUT_USABLE → BROKEN）。デフォルトで安全です。cass search の前に PreToolUse フックとして使用します。ハングする issue #196 を回避するため、すべての cass index 呼び出しを timeout でラップします
./scripts/multi_machine_search.sh "QUERY" [host…]	マシン群に対する並列検索（デフォルトは css/csd/ts1/ts2）。結果を統合し、source_path:line で重複を除去して、スコア順に並べ替えます。ホストごとに timeout の上限があります。シェル特殊文字を含むクエリにも安全です

---

検証

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

# Should return: true

false の場合は、.index.stale と .database.exists を確認してください（Two-Step Bootstrap を参照）。古いインデックスでも検索は可能です。まず検索し、上限付きで更新してください：timeout 600 cass index --json（上限なしで実行しないでください）。cass doctor --fix --json が必要なのは、database.exists=false または documents=0 の場合のみです。