claude-replay

Name: claude-replay
Author: constripacity

ローカル

github.com/constripacity開発ツール110 週間前に更新

リポジトリ

claude-replay について

claude-replayは、セッションの復旧や履歴分析を必要とする開発者向けに、Claude CodeのセッションをローカルのSQLiteデータベースへ記録します。Claude Code標準の復旧機能に加え、履歴検索、指標、比較、エクスポート、ダッシュボード、ターミナルUIを提供します。

主な機能

01セッションとチェックポイントをローカル記録
02セッション履歴を検索・絞り込み
03再開用ブリーフと分析情報を生成
04セッション比較とタグ管理
05HTML、JSON、Markdownでトレースを出力
06ダッシュボードまたはTUIでセッションを閲覧

活用シーン

01Claude Codeのセッション終了後に文脈を復旧
02過去のツール呼び出しやプロジェクト活動を検索
032つのセッションの結果を比較
04確認用にセッションの記録を出力

MCP 対応

記録済みセッションの状態、チェックポイント、再開用ブリーフ、検索、分析、比較、タグ付け、エクスポートを行うMCPツールを提供します。クライアントはSSEで接続するか、stdio経由で起動できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "constripacity-claude-replay": {
      "command": "uvx",
      "args": [
        "claude-replay"
      ],
      "env": {
        "CLAUDE_REPLAY_DB": "<CLAUDE_REPLAY_DB>"
      }
    }
  }
}

起動コマンドuvx claude-replay

設定が必要な環境変数

CLAUDE_REPLAY_DBSQLite database path (default: ~/.claude-replay/sessions.db). Point HTTP and stdio instances at the same path to share recorded sessions.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypiclaude-replay0.4.3stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

このツールにパラメーターはありません。

詳細

Claude Replay

Claude Code セッションの可観測性レイヤー — すべてのプロジェクトにわたる検索、分析、可視化を実現します。

Claude Code の --resume／--continue と /rewind で復元できるのは、現在のセッションです。Claude Replay はそれらではできないことを実現します。すべてのセッションを受動的にフックし、発生した内容をローカルの SQLite ストアに記録することで、すべてのプロジェクトにわたる過去のすべてのセッションを検索、比較、測定、エクスポートできるようにします。全文検索、セッションごとのインサイト指標、終了原因の分類（セッションが終了した理由）、セッションの差分比較、ウェブダッシュボード、ターミナル UI を利用できます。これらはいずれも Claude Code に標準搭載されていません。

Claude Code session
        |
   hooks (PreToolUse · PostToolUse · Stop)
        |
        v
   ~/.claude-replay/sessions.db   ← events + checkpoints
        |
   +----+--------------------+
   |          |              |
 MCP tools  Dashboard      TUI
 (resume)   :8766          (browse)

受動的なフックが書き込みを行い、MCP ツール、ウェブダッシュボード、ターミナル UI が読み取ります。マシンの外にデータが送信されることはありません。

Claude Code 標準機能との連携

Claude Replay は機能を追加するものであり、組み込み機能の上に重ねて動作します。置き換えるものではありません。

したいこと	使用する機能
現在のセッションを再開／継続する	標準 `claude --continue`、`--resume`
セッション内のファイルと会話の変更を取り消す	標準 `/rewind`
内容、ツール、結果で過去のすべてのセッションを検索する	Replay `search`
セッションが終了した理由とセッションごとの指標を確認する	Replay `status`／`replay_insights`
2 つの実行を並べて比較する	Replay `diff`
セッションのタイムラインを可視化する／すべてのプロジェクトを閲覧する	Replay ダッシュボード + TUI
セッションを HTML／JSON／Markdown 形式でエクスポートする	Replay `export --format`

標準の再開／巻き戻し機能は復元、Replay は履歴全体の可観測性を提供するものと考えてください。

アーキテクチャ

受動的なフックが SQLite に書き込みます。MCP ツールが SQLite から読み取ります。ダッシュボードと TUI が SQLite のデータを可視化します。システム全体はこれだけです。

レイヤー	ファイル	役割
ストア	`claude_replay/store.py`	すべての DB アクセス — セッション、イベント、チェックポイント
フック	`claude_replay/hooks.py`	ツール呼び出しの記録とチェックポイントの自動作成。`claude-replay hook <type>` によって呼び出されます
復元	`claude_replay/resume.py`	セッションから再開用の概要を生成します
エクスポート	`claude_replay/export.py`	セッションを自己完結型の HTML トレースとしてレンダリングします
サーバー	`claude_replay/server.py`	Starlette アプリ — MCP SSE + JSON API + 静的ダッシュボード
TUI	`claude_replay/tui.py` + `tui_client.py`	JSON API 経由の Textual セッションブラウザー
CLI	`claude_replay/cli.py`	すべてのサブコマンド

ポート 8766 は Claude Bridge の 8765 より意図的に 1 つ大きく設定しており、2 つの関連ツールをポート競合なしで同時に実行できます。

クイックスタート

1. インストール

pip install claude-replay

または、コードを変更してみたい場合はクローンからインストールします。

git clone https://github.com/constripacity/Claude-Replay.git
cd Claude-Replay
pip install -e .[dev]              # editable install with test/lint deps
pip install -e .[tui]             # add the terminal UI deps (textual, httpx)

お使いの環境で pip install -e が失敗する場合（環境によっては hatchling の編集可能インストールに既知の問題があります）、代わりに依存関係を直接インストールしてください。 pip install mcp starlette uvicorn anyio textual httpx。

2. フックをインストールする

3 つのフックを ~/.claude/settings.json に統合し、Replay を Claude Code に接続します。何度実行しても安全で、他のツールのフックには影響しません。

claude-replay install

✓ Installed Claude Replay hooks into ~/.claude/settings.json
  PreToolUse  → claude-replay hook pre-tool
  PostToolUse → claude-replay hook post-tool
  Stop        → claude-replay hook stop

これ以降、すべての Claude Code セッションが自動的に記録されます。claude-replay uninstall を実行すれば、いつでもフックを削除できます（Replay のフックのみを削除します）。

正しく接続されていることを確認します。重要な確認項目はこれだけです。

claude-replay doctor

Claude Replay — doctor

  ✓ Hooks installed: PreToolUse / PostToolUse / Stop are in settings.json
  ✓ Hook command on PATH: claude-replay → …/claude-replay
  ✓ Database: ~/.claude-replay/sessions.db
  ✓ Sessions recorded: 3 sessions; most recent 5m ago

All good — Replay is installed and recording. ✓

doctor が claude-replay が PATH にないと警告する場合、フックを実行できず、何も記録されません。インストール先のディレクトリを PATH に追加して、もう一度実行してください。

3. サーバーを起動する（ダッシュボード + MCP ツール）

claude-replay serve                 # defaults: 127.0.0.1:8766
claude-replay serve --port 9000     # custom port
claude-replay serve --host 0.0.0.0  # bind all interfaces

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Claude Replay — Session checkpoint & recovery server
  Version: 0.4.1
  DB: ~/.claude-replay/sessions.db
  http://localhost:8766/             ← Dashboard
  http://localhost:8766/sse          ← MCP config
  http://localhost:8766/api/state    ← JSON state
  http://localhost:8766/status       ← Health check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

4. （任意）MCP ツールを Claude Code に登録する

実行中の Claude Code セッションから replay_resume、replay_checkpoint などを直接呼び出せるようになります。方法は 2 つあります。

SSE（ダッシュボードと併用 — claude-replay serve の実行が必要です）：

claude mcp add --transport sse -s user claude-replay http://localhost:8766/sse

stdio（サーバープロセス不要 — クライアントが必要に応じて Replay を起動します）：

claude mcp add -s user claude-replay -- claude-replay mcp
# or, without installing: uvx claude-replay mcp

claude mcp list で確認してください。claude-replay に ✓ Connected と表示されるはずです。すでに実行中のセッション内では、/mcp と入力して再ハンドシェイクします。

セッションが終了したとき

# What's the state of the last session?
claude-replay status

# Print a paste-ready resume brief (most recent session, or pass an id)
claude-replay resume
claude-replay resume <session-id>

# Browse every recorded session in the terminal
claude-replay tui                   # needs `claude-replay serve` running

# Export a session as a self-contained HTML trace
claude-replay export                # → ~/.claude-replay/exports/<id>.html

resume の出力を新しい Claude Code セッションに貼り付けると、終了したセッションの続きから再開できます。目標、完了した作業、次に行う作業、変更されたファイルが引き継がれます。

MCP ツール

接続された Claude Code セッションでは、以下の 10 個のツールを利用できます。

ツール	説明
`replay_status`	現在のセッションの概要 — 目標、ステータス、終了理由、イベント／チェックポイント数、最終アクティビティ
`replay_checkpoint`	任意のメモを添えて、現在のセッションのチェックポイントをただちに作成します
`replay_resume`	セッションの構造化された再開用概要を生成します（デフォルト：最新のセッション）
`replay_sessions`	ステータス、モデル、所要時間、チェックポイント数を含む最近のセッションを一覧表示します
`replay_insights`	セッションごとのメトリクス：終了理由、所要時間、ツール呼び出し数、エラー率、変更されたファイル、使用頻度の高いツール
`replay_stats`	セッション横断の分析：ツール呼び出し数、エラー率、セッションの終了理由、ツールの内訳、プロジェクトごとの集計
`replay_search`	フィルター（ツール、原因、日付、プロジェクト）を使ってセッションを全文検索し、一致件数順に表示します
`replay_diff`	2 つのセッションを比較します：メトリクスの差分と、それぞれで変更されたファイル
`replay_tag`	後で検索できるように、セッションに名前を付けてタグを追加／削除します
`replay_export`	セッションを自己完結型のトレース（html / json / md）としてレンダリングし、パスを返します

CLI リファレンス

コマンド	動作
`claude-replay install`	Replay のフックを `~/.claude/settings.json` にマージします（繰り返し実行しても安全です）
`claude-replay uninstall`	Replay のフックのみを削除します
`claude-replay status`	インサイトのメトリクスを含む、現在／直近のセッションの概要を表示します
`claude-replay sessions [--limit N]`	最近のセッションを一覧表示します（名前とタグを含む）
`claude-replay search <query> [--tool T] [--cause C] [--since 7d] [--project P]`	フィルターを使って全文検索します（クエリを省略すると、フィルターで絞り込んで閲覧します）
`claude-replay diff <session-a> <session-b>`	2 つのセッションを並べて比較します
`claude-replay resume [session_id]`	再開用の概要を出力します（デフォルト：最新のセッション）
`claude-replay export [session_id] [--output DIR] [--format html\|json\|md]`	トレースをレンダリングします
`claude-replay tag [session_id] [--name N] [--add a,b] [--remove c] [--clear]`	セッションに名前またはタグを付けます
`claude-replay prune [--older-than 30d] [--yes]`	最近アクティビティのないセッションを削除します（破壊的操作）
`claude-replay serve [--host H] [--port P]`	MCP とダッシュボードのサーバーを起動します（ポート 8766）
`claude-replay mcp`	stdio 経由で MCP ツールを提供します（`uvx claude-replay mcp`／MCP クライアント用）
`claude-replay tui [--url URL]`	ターミナルのセッションブラウザーを起動します
`claude-replay reset [--yes]`	記録されたすべてのセッションを削除します（破壊的操作）
`claude-replay hook <pre-tool\|post-tool\|stop>`	内部用 — Claude Code のフックから呼び出されます

ダッシュボードと TUI

Web ダッシュボード（claude-replay serve を実行してから、http://localhost:8766/ を開きます）は、2 秒ごとにポーリングするバニラ JavaScript 製のビューです。セッション一覧（終了方法のバッジとタグ付き）、ライブ検索ボックス、セッションごとのタイムライン、ワンクリックで使える「再開用ブリーフをコピー」／「HTML をエクスポート」を備えています。CDN もビルド手順も不要です。

ターミナル UI（claude-replay tui）は、同じダークテーマの Textual ブラウザーです。セッションのサイドバー、ライブイベントフィード、セッションの終了方法、タグ、最新のチェックポイント、変更されたファイルを表示する詳細インスペクターを備えています。キー操作：

↑↓ navigate   Tab switch panel   Space pause
r  resume (copies the brief to your clipboard)
e  export HTML trace
?  help        q quit

TUI は HTTP 経由でサーバーと通信します。先に claude-replay serve を起動してください（デフォルトは http://127.0.0.1:8766 です。別の URL を指定するには --url を使います）。

設定

環境変数	デフォルト	用途
`CLAUDE_REPLAY_DB`	`~/.claude-replay/sessions.db`	SQLite ストアの場所
`CLAUDE_SESSION_ID` / `CLAUDE_CODE_SESSION_ID`	—	セッション ID（Claude Code はフックのペイロードにこれを設定します）。まずこれらの環境変数を参照し、次にプロジェクトディレクトリのハッシュを使用します
`CLAUDE_REPLAY_CORS_ORIGIN`	localhost のみ	サーバーで許可する追加の CORS オリジン（カンマ区切り）
`CLAUDE_REPLAY_NO_DASHBOARD`	—	静的ダッシュボードのマウントを無効にします（MCP／JSON のみ）

フックのパスはオフライン優先になるよう設計されています。ネットワーク呼び出しは一切行わず、50 ミリ秒を大幅に下回る時間で完了します。実行するのは SQLite への書き込み 1 回だけです。データベースのサイズを抑えるため、大きなツールペイロードはイベントごとに 8 KB で切り詰められます。

開発

pip install -e .[dev]               # or install deps directly (see install note)
python -m pytest                    # full suite
ruff check .

テストでは分離された tmp_path SQLite データベース（fresh_db フィクスチャ）を使用し、実際の ~/.claude-replay/sessions.db には一切触れません。適用範囲とコーディング規則については、CONTRIBUTING.md を参照してください。

ライセンス

MIT です。LICENSE を参照してください。

Claude Bridge の姉妹プロジェクトです。Constripacity の名のもとに開発されました。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。