🔎

Claude Codeでセッションを探すためにccsearchを作った

に公開
Claude Code
Coding agent
ccsearch
tech

結構Claude Codeを使っているのですが使えば使うほど過去のセッションを探すのが大変になってきた。

「あの実装、どのセッションでやったっけ？」と経験をしぬほどやってきています。

セッションの情報はは~/.claude/projects/以下にJSONL形式で保存されているけれど、プロジェクトごとに分かれているし、ファイル名に情報がないので中身が分からない。

そこで作ったのがccsearch

ccsearchとは

ccsearchはClaude CLIのセッション履歴を検索・管理するツールだ。npmで簡単にインストールできる。

npm install -g ccsearch

インストールしたくない場合はnpxでも使える。
※大抵はnpxで使うんだろうなという想定をしています。

npx ccsearch@latest

実行すると、ブラウザでWebUIが開く。ここから過去のセッションを検索したり、エクスポートしたりできる。

主な機能

1. 全文検索

おそらくほとんどの人はこの機能しか使わない。すべてのプロジェクトを横断して、セッション内容を検索できる。

また、Claudeが実行したツールの結果（ファイルの内容など）も検索対象に含まれる。これが意外と便利で、「あのコードどこで見たっけ」というときに見つかることが多い。

2. エクスポート/インポート

チームメンバーとセッションを共有したいことがよくある。「このセッション見て」と言えるのは便利だ。

エクスポートはプロジェクト単位でも、最新のn件でもできる。インポートした内容はローカルのセッションと混ざらないよう、別モードで閲覧できるようにしている。

3. セッションを引き継ぐためにClaude Codeのコマンドを発行

上記のCLIをコピーボタンを押すとclaude -r "f7b12123-ed4c-4803-9141-17ded76a54a3" ""のようなコマンドがクリップボードにコピーされる。
ターミナル上に貼り付ければセッションに戻ることができます。

CLIモードでの使い方

ccsearchはWebUIだけでなく、CLIからも使える。ターミナルで完結したい人や、スクリプトに組み込みたい人向けの機能だ。

基本的な使い方

何もオプションを指定しないと、WebUIが起動する。

# WebUIを起動（デフォルトポート: 3210）
npx ccsearch@latest

exportコマンド

セッションをJSON形式でエクスポートできる。チームでの共有やバックアップに便利だ。

# すべてのセッションをエクスポート デフォルトは ccsearch-export.jsonというファイル名で出力される
npx ccsearch@latest export

# 出力ファイルを指定
npx ccsearch@latest export -o my-sessions.json

# 最新10件のセッションのみエクスポート
npx ccsearch@latest export -l 10

# 特定のプロジェクトのセッションのみエクスポート
npx ccsearch@latest export -p github.com/suthio/ccsearch

# インタラクティブモード（セッションを選んでエクスポート）
npx ccsearch@latest export -i

インタラクティブモード（-iオプション）は特に便利で、セッション一覧が表示されて、エクスポートしたいものを番号で選べる。「1,3,5」のようにカンマ区切りで複数選択もできる。

エクスポートされるJSONには以下の情報が含まれる。

  • セッションの内容（メッセージ履歴）
  • メタデータ（作成日時、更新日時）
  • プロジェクト情報（GitHubリポジトリの場合は簡略化されたパス）
  • エクスポート情報（日時、プラットフォーム、バージョン）

searchコマンド

CLIから直接セッションを検索できる。

# 基本的な検索
npx ccsearch@latest search "API"

# プロジェクトを指定して検索
npx ccsearch@latest search "バグ修正" -p /Users/me/myproject

# 複数の単語で検索（スペース区切り）
npx ccsearch@latest search "Claude Code エラー"

検索対象は以下の通り。

  • セッションタイトル
  • メッセージ内容
  • プロジェクトパス

オプション一覧

グローバルオプション：

  • --version: バージョン表示
  • --help: ヘルプ表示
  • --port <number>: WebUIのポート番号指定

exportコマンドのオプション：

  • -o, --output <file>: 出力ファイル名（デフォルト: ccsearch-export.json）
  • -p, --project <project>: プロジェクトでフィルタ
  • -l, --last <n>: 最新n件のみエクスポート
  • -i, --interactive: インタラクティブモード

searchコマンドのオプション：

  • -p, --project <project>: プロジェクトでフィルタ

活用例

僕がよく使うパターンをいくつか紹介する。

# 今週の作業内容をエクスポート（最新30件くらい） 最近なにをやったかまとめてもらうのに便利
ccsearch export -l 30 -o weekly-report.json

# 特定のプロジェクトで「エラー」を含むセッションを探す
ccsearch search "エラー" -p github.com/suthio/myapp

CLIモードは自動化に向いている。例えば、cronで定期的にバックアップを取ったり、特定のキーワードを含むセッションを監視したりできる。
Claude Code内でccsearchを起動して操作する際に便利

技術的な実装

使ってみて

週に何度かは使っている。特に便利なのは以下のシーン。

  1. 過去のセッションを探すとき: 「あの機能どうやって実装してもらったっけ」がすぐ見つかる
  2. チームメンバーに共有するとき: セッションをエクスポートして「これ見て」と言える
  3. 週次の振り返り: 今週何をやったか、exportしてClaude Codeにまとめさせると便利

Claude Codeを使い倒している人には、ぜひ試してもらいたいなと思います。

興味がある人は、使ってもらいたいです。GitHubにてIssueやPRも歓迎しています。

Discussion