claudex

---

🆕 新着情報

バージョン 1.3.0（2026年2月12日）— MCP サーバー

• 🧠 MCP サーバー: Model Context Protocol サーバーにより、セッションをまたいで Claude Code に永続メモリを提供します
• 🔧 10 個の MCP ツール: プロジェクトコンテキスト、セッション検索、会話の取得、構造化メモリの CRUD
• 💾 構造化メモリシステム: 優先度、信頼度、有効期限（TTL）を設定して、コーディングに関する知識（規約、アーキテクチャ、決定事項、エラーパターン）を保存します
• 📋 3 つの MCP プロンプト: 過去のセッションにすばやくアクセスするための /recall、/catchup、/history
• 🎯 トークン予算管理: コンテキスト管理のための 3 つの詳細レベル（最小／標準／完全）
• 📖 ワンコマンドセットアップ: claude mcp add --transport stdio claudex -- claudex-mcp

以前のリリース

バージョン 1.2.0（2025年11月11日）

• 🎨 包括的なテーマシステム: 10 種類のプロフェッショナルなテーマ（default、emerald、green、blue、purple、orange、red、rose、yellow、classic）
• 🔤 高度なタイポグラフィ: 視覚的なプレビューを備えた 29 種類のフォントファミリー
• 📏 細かなフォントサイズ設定: 5 つの正確なフォントサイズオプション（14px～18px）
• 💾 設定の永続化: すべてのカスタマイズを localStorage に保存

バージョン 1.1.0（2025年10月27日）

• 🎯 スマートなタイトル抽出: 会話内容から意味のあるセッションタイトルを抽出
• 📊 Tremor 分析ダッシュボード: Tailwind ベースのグラフと複数スケールの可視化
• 🐳 Docker マルチプラットフォーム対応: 最適化された約 200MB のイメージで amd64 と arm64 に対応
• ⚡ パフォーマンス: 非同期検索インデックスの再構築を 121 倍高速化

変更履歴の全文を見る | トラブルシューティングガイド

---

📸 スクリーンショット

🎨 v1.2.0 の新機能：テーマ設定とカスタマイズ

10 種類のプロフェッショナルテーマ Classic、Emerald、Blue、Purple、Orange、Red、Rose、Yellow、Green、Default	29 種類のフォントファミリー 実際の書体を確認できるプレビュー
細かなフォントサイズ調整 5 段階の精密なサイズ設定（14px-18px）＋ボーダー半径の調整	設定モーダル 外観設定は利用可能です。その他の設定も近日追加予定です

会話ビュー

全文検索

✨ 機能

• MCP サーバー：Claude Code に永続的なメモリを提供します。規約、アーキテクチャ、決定事項、エラーパターンをセッションをまたいで保持します
• 構造化メモリ：優先度（1～10）、信頼度、有効期限に基づく自動失効を設定して、コーディングに関する知識を保存・呼び出します
• プロジェクトの自動検出：~/.claude/projects ディレクトリを自動的にスキャンし、複数のプロジェクトにまたがるすべての会話を検出します
• 全文検索：プロジェクト、セッション、ロール、期間による高度な絞り込みとコンテンツのハイライト表示に対応した、エンタープライズグレードの SQLite FTS5 検索エンジン
• あらゆるテンプレート形式に対応：すべての Claude Code バージョン（V1.x、V2-mixed、V2.0+）向けのインテリジェントなテンプレート検出・解析と、形式の自動判定
• スマートなコンテンツ表示：構文ハイライト付きコードブロック、Markdown 表示、差分の可視化、JSON の整形、ツール使用状況の追跡
• セッション分析：Tremor React を使用した、メッセージ分布のグラフ、ファイル操作の追跡、会話統計を備えた包括的な分析ダッシュボード
• エクスポートオプション：会話を JSON（構造化データ）、HTML（読みやすい形式）、またはプレーン TXT でエクスポートして、保存・共有できます
• モダンな UI：10 種類のテーマ、29 種類のフォント、セッションのお気に入り機能を備え、開発者のワークフローに最適化されたレスポンシブ React インターフェース

---

💖 このプロジェクトを応援する

Claudex は無料のオープンソースです。時間を節約し、ワークフローの改善に役立った場合は、ぜひご協力ください。

• ⭐ リポジトリにスターを付ける - Claudex をより多くの人に知ってもらう
• 🐛 バグを報告する - フィードバックが改善につながります
• 💡 アイデアを共有する - Discussions で機能をリクエストする
• ☕ コーヒーをおごる - 継続的な開発を支援する

---

🚀 クイックスタート

前提条件

• Node.js 18+ と npm
• Claude Code がインストールされており、会話履歴が ~/.claude/projects に保存されていること

インストール

オプション 1：npm（推奨）

# Global installation
npm install -g @kunwarshah/claudex [https://www.npmjs.com/package/@kunwarshah/claudex]

# Then run anywhere:
claudex

# Custom port (if 3400 is in use):
claudex --port 3500

# Custom project directory:
claudex --project-root ~/my-claude-projects

# Or use without installing (npx):
npx @kunwarshah/claudex

MCP サーバーを追加（Claude Code に永続的なメモリを提供します）：

claude mcp add --transport stdio claudex -- claudex-mcp

詳細はMCP サーバーガイドをご覧ください。

CLI オプション：

• --help, -h：ヘルプメッセージを表示します
• --version, -v：バージョンを表示します
• --port, -p <port>：サーバーのカスタムポート（デフォルト：3400）
• --project-root <path>：Claude プロジェクトディレクトリを指定します

環境変数：

• PORT：サーバーポート（デフォルト：3400）
• PROJECT_ROOT：Claude プロジェクトディレクトリ（デフォルト：~/.claude/projects）

オプション 2：ソースから実行

1. リポジトリをクローンします：

git clone https://github.com/kunwar-shah/claudex.git
cd claudex

2. システムチェックを実行します（省略可能ですが、推奨します）：

npm run check

環境を検証し、よくあるセットアップの問題を検出します。

3. 依存関係をインストールします（または自動修正を使用します）：

# Option 1: Manual installation
npm install
cd server && npm install && cd ..
cd client && npm install && cd ..

# Option 2: Auto-fix (installs deps + creates .env)
npm run check:fix

4. 環境を設定します（自動修正を使用しない場合）：

cd server
cp .env.example .env
# Edit .env if needed (default: PROJECT_ROOT=~/.claude/projects)
cd ..

5. アプリケーションを起動します：

# Automatically runs system check, then starts servers
npm run dev

6. ブラウザーを開きます：http://localhost:3000

バックエンド API は http://localhost:3400 で実行されます。

システムチェッカー

Claudex には、環境を検証する包括的なシステムチェッカーが含まれています。

# Quick check
npm run check

# Detailed output
npm run check:verbose

# Auto-fix common issues
npm run check:fix

# JSON output (for CI/CD)
npm run check:json

チェック項目：

• ✅ Node.js と npm のバージョン
• ✅ PROJECT_ROOT のパスと権限
• ✅ ポートの使用可否（3000、3400）
• ✅ 依存関係のインストール状況
• ✅ Claude Code のデータ（プロジェクト、セッション）
• ✅ JSONL ファイルの妥当性
• ✅ データベースの権限
• ✅ 検索インデックスの状態

グローバル CLI インストール（省略可能）

グローバルにインストールすると、どこからでも claudex コマンドを使用できます。

./install.sh

# Then run from anywhere:
claudex

🔧 設定

サーバー設定（.env）

# Path to Claude Code projects directory
# Supports ~ expansion (e.g., ~/.claude/projects)
PROJECT_ROOT=~/.claude/projects

# Server port
PORT=3400

# Environment
NODE_ENV=development

デフォルトのポート

• フロントエンド：http://localhost:3000（Vite 開発サーバー）
• バックエンド：http://localhost:3400（Fastify API）
• フロントエンドのビルド：ポート 3400 を使用します（本番環境ではバックエンドが配信）

📂 プロジェクト構成

claudex/
├── server/                    # Backend (Node.js + Fastify)
│   ├── src/
│   │   ├── parsers/          # Template detection & message parsing
│   │   │   ├── templateDetector.js    # V1/V2/V3 template detection
│   │   │   └── messageParser.js       # Universal message parser
│   │   ├── services/         # Core business logic
│   │   │   ├── fileScanner.js        # Project/session discovery
│   │   │   ├── sessionParser.js      # Full session parsing
│   │   │   ├── searchDatabase.js     # SQLite FTS5 search
│   │   │   ├── searchIndexer.js      # Search index builder
│   │   │   └── memoryService.js      # Structured memory CRUD
│   │   ├── mcp/              # MCP server (Claude Code integration)
│   │   │   ├── index.js              # MCP entry point + stdio transport
│   │   │   ├── tools.js              # 10 MCP tool handlers
│   │   │   ├── resources.js          # MCP resources
│   │   │   └── prompts.js            # 3 MCP prompts
│   │   ├── routes/           # API endpoints
│   │   │   ├── projects.js           # Project/session routes
│   │   │   ├── search.js             # Search routes
│   │   │   └── export.js             # Export routes
│   │   ├── utils/            # Helper utilities
│   │   │   └── pathHelper.js         # Path expansion (~/ support)
│   │   └── server.js         # Main server
│   ├── data/                 # SQLite database (auto-created)
│   ├── .env.example          # Environment template
│   └── package.json
├── client/                   # Frontend (React + Vite)
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── ProjectSelector.jsx
│   │   │   ├── SessionList.jsx
│   │   │   ├── ConversationThread.jsx
│   │   │   ├── MessageBubble.jsx
│   │   │   ├── ClaudeMessageRenderer.jsx
│   │   │   └── SearchPage.jsx
│   │   ├── services/         # API client
│   │   │   └── api.js
│   │   └── App.jsx           # Main app
│   └── package.json
├── bin/                      # CLI entry point
├── test-search.sh           # Search API testing script
├── install.sh               # Global CLI installer
├── SETUP.md                 # Detailed setup guide
├── README.md                # This file
└── package.json             # Root package (CLI + concurrently)

🎯 対応する Claude Code の形式

ビューアーはすべての Claude Code の会話形式を自動的に検出し、解析します。

V3 テンプレート（ユニバーサル - 推奨）

• Claude Code v2.0+：role フィールドを直接使用する新形式
• Claude Code v1.x：type フィールドを使用する元の形式
• エッジケース：混在形式や移行状態
• 新しいメッセージタイプ：file-history-snapshot に対応
• ロールマッピング：すべてのシステムメッセージをアシスタントに割り当てます（二値のユーザー／アシスタント分類）

レガシーテンプレート（自動検出）

• V2-Mixed：V1 と V2 の間の移行形式
• V1：元の Claude Code 形式

テンプレート検出器は段階的な検出戦略を使用し、会話ファイルに最適なパーサーを自動的に選択します。

🔍 検索システム

検索インデックスの構築

検索を行う前に、検索インデックスを構築する必要があります。

# Option 1: Via API
curl -X POST http://localhost:3400/api/search/index/build

# Option 2: Via test script
./test-search.sh

# Option 3: Via UI (Search page → "Rebuild Index" button)

インデックスを再構築するタイミング

次の場合に検索インデックスを再構築します。

• 初回セットアップ時
• テンプレートを変更した後
• 新しい会話を追加したとき
• 検索結果が古いように見える場合

検索 API の例

# Basic search
curl -X POST http://localhost:3400/api/search \
  -H "Content-Type: application/json" \
  -d '{"q": "migration", "limit": 10}'

# Search with filters
curl -X POST http://localhost:3400/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "database",
    "projectId": "my-project",
    "role": "user",
    "limit": 20,
    "offset": 0
  }'

# Check index status
curl http://localhost:3400/api/search/index/status

📡 API エンドポイント

プロジェクトとセッション

エンドポイント	メソッド	説明
/api/projects	GET	すべてのプロジェクトを一覧表示します
/api/projects/:id/sessions	GET	プロジェクトのセッションを取得します
/api/projects/:id/sessions/:sessionId	GET	メッセージを含むセッション全体を取得します

検索

エンドポイント	メソッド	説明
/api/search	POST	会話を検索します（FTS5）
/api/search/index/build	POST	検索インデックスを構築／再構築します
/api/search/index/status	GET	インデックスの統計情報を取得します
/api/search/index/clear	POST	検索インデックスを消去します

エクスポート

エンドポイント	メソッド	説明
/api/export/session/:projectId/:sessionId?format=json	GET	JSON としてエクスポートします
/api/export/session/:projectId/:sessionId?format=html	GET	HTML としてエクスポートします
/api/export/session/:projectId/:sessionId?format=txt	GET	TXT としてエクスポートします

ヘルスチェック

エンドポイント	メソッド	説明
/api/health	GET	ヘルスチェックとシステム情報

🛠️ 開発

開発モード

# Run both frontend + backend with hot reload
npm run dev

# Or run separately:
# Terminal 1 - Backend (auto-restarts on changes)
cd server && npm run dev

# Terminal 2 - Frontend (hot module replacement)
cd client && npm run dev

検索システムのテスト

# Run comprehensive search tests
./test-search.sh

このスクリプトでは、次の処理を行います。

1. サーバーの状態を確認する
2. インデックスの状態を取得する
3. インデックスを構築／再構築する
4. さまざまなフィルターを使ってテスト検索を実行する
5. 結果を表示する

新しいテンプレートの追加

1. テンプレート検出器を更新する（server/src/parsers/templateDetector.js）：

'my-template': {
  name: 'My Template Name',
  detect: (samples) => {
    return samples.some(s => s.myUniqueField !== undefined);
  },
  parser: 'my-template'
}

2. パーサーメソッドを追加する（server/src/parsers/messageParser.js）：

parseMyTemplate(rawMessage) {
  return {
    id: rawMessage.id || this.generateId(),
    role: rawMessage.myRole === 'user' ? 'user' : 'assistant',
    content: rawMessage.myContent || '',
    timestamp: rawMessage.myTimestamp,
    // ... other fields
  };
}

3. 検索インデックスを再構築する：新しいテンプレートが自動的に検出され、使用されます。

📝 スクリプトのリファレンス

Claudex ディレクトリ

• npm run dev - フロントエンドとバックエンドを同時に実行（事前チェック付き）
• npm start - フロントエンドとバックエンドを実行（本番モード）
• npm run check - システムのヘルスチェックを実行
• npm run check:verbose - 詳細なシステムチェックを実行
• npm run check:fix - よくあるセットアップの問題を自動修正
• npm run check:json - CI/CD 用に JSON 形式で出力
• ./install.sh - グローバル CLI コマンドとしてインストール
• ./test-search.sh - 検索 API エンドポイントをテスト

Server ディレクトリ

• npm run dev - nodemon を使って実行（自動再起動）
• npm start - 本番モードで実行

Client ディレクトリ

• npm run dev - Vite 開発サーバー（http://localhost:3000）
• npm run build - 本番用にビルド
• npm run preview - 本番ビルドをプレビュー

🐛 トラブルシューティング

クイック診断

まずシステムチェッカーを実行して、問題を特定してください。

npm run check:verbose

よくある問題をすべて確認し、実行可能な対処方法を提示します。

よくある問題

メッセージが存在するのに「メッセージが見つかりません」と表示される

v1.1.1 で修正済み - セッションが断続的に空になったり、重複キーの警告が表示されたりする場合：

# Update to latest version
cd claude-viewer
git pull origin main
npm install && cd server && npm install && cd ../client && npm install && cd ..
npm run dev

詳しくは詳細なトラブルシューティングガイドをご覧ください。

プロジェクトが見つからない

# Check what the system sees
npm run check

# Verify path
cat server/.env | grep PROJECT_ROOT

• .env の PROJECT_ROOT が ~/.claude/projects を指していることを確認してください
• Claude Code が会話ファイルを作成していることを確認してください
• npm run check:fix を実行して、不足しているディレクトリを自動作成してください

検索が機能しない

# Quick fix via UI
# Visit http://localhost:3000/search → Click "Rebuild Index"

# Or via command line
curl -X POST http://localhost:3400/api/search/index/build

ポートの競合

# System checker will detect port conflicts
npm run check

# Auto-detected ports in use show PID
# Kill process: kill <PID>
# Or change PORT in server/.env

権限エラー

# Check permissions
npm run check:verbose

# Fix permissions
chmod +r ~/.claude/projects
chmod +w claude-viewer/server/data

依存関係の問題

# Auto-install all dependencies
npm run check:fix

🚢 本番環境へのデプロイ

Docker を使用する（推奨）

Claudex には、イメージサイズを最適化するマルチステージビルドを備えた、本番環境対応の Docker 構成が含まれています。

Docker でのクイックスタート

# Build and start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

http://localhost:3400 からアクセスできます。

Docker の設定

デフォルトの docker-compose.yml では、Claude のプロジェクトディレクトリが読み取り専用でマウントされます。

volumes:
  # Adjust path to match your system
  - ~/.claude/projects:/root/.claude/projects:ro

一般的なパス設定：

# Linux/macOS
~/.claude/projects:/root/.claude/projects:ro

# Windows (WSL2)
/mnt/c/Users/YourName/.claude/projects:/root/.claude/projects:ro

# Custom path
/path/to/your/projects:/root/.claude/projects:ro

Docker コマンド

# Build image manually
docker build -t claudex:latest .

# Run container manually
docker run -d \
  -p 3400:3400 \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v claudex-data:/app/data \
  --name claudex-web \
  claudex:latest

# Check health
docker ps  # Check STATUS column for "healthy"

# View logs
docker logs claudex-web -f

# Stop and remove
docker stop claudex-web && docker rm claudex-web

Docker の機能

• マルチステージビルド：イメージサイズを最適化（約 200MB）
• 非 root ユーザー：セキュリティのため、nodejs ユーザーとして実行
• ヘルスチェック：ヘルス状態を自動監視
• 永続ボリューム：検索インデックスとログを保存
• 読み取り専用マウント：安全のため、Claude のプロジェクトを読み取り専用でマウント
• ログローテーション：最大 10MB の JSON ログ、3 ファイルでローテーション

Docker 環境変数

# Override in docker-compose.yml or docker run
-e PORT=3400                           # Server port
-e HOST=0.0.0.0                        # Bind address
-e NODE_ENV=production                 # Environment
-e PROJECT_ROOT=/root/.claude/projects # Claude projects path

手動での本番ビルド

Docker を使わずにデプロイする場合：

# 1. Install dependencies
npm run install-deps

# 2. Build client
npm run build

# 3. Start server (serves built client)
cd server && NODE_ENV=production npm start

http://localhost:3400 からアクセスできます。

📋 ロードマップ

• SQLite FTS5 全文検索
• 汎用テンプレート対応（V1/V2/V3）
• JSON/HTML/TXT へのエクスポート
• Docker デプロイ（v1.1.0）
• 会話分析ダッシュボード（v1.1.0）
• テーマシステム — 10 種類のテーマ、29 種類のフォント（v1.2.0）
• セッションのお気に入り登録／ブックマーク（v1.2.4）
• Claude Code 用 MCP サーバー（v1.3.0）
• 構造化メモリシステム（v1.3.0）
• トークンコスト計算ツール
• WebSocket によるリアルタイム更新
• カスタムパーサー用プラグインシステム

---

📄 ライセンス

MIT ライセンス - 詳細は LICENSE ファイルをご覧ください。

🤝 コントリビューション

1. リポジトリをフォークする
2. フィーチャーブランチを作成する：git checkout -b feature/amazing-feature
3. 変更をコミットする：git commit -m 'Add amazing feature'
4. ブランチにプッシュする：git push origin feature/amazing-feature
5. プルリクエストを作成する

📚 関連ドキュメント

• SETUP.md - 詳細なセットアップおよび設定ガイド
• INSTALL.md - 従来のインストール手順

💡 ヒント

• 検索ページを使って、すべてのプロジェクトの会話を検索できます
• 会話をエクスポートして、チームメンバーと共有できます
• 新しい会話を追加した後は、検索インデックスを再構築してください
• /api/health エンドポイントを確認して、システムの状態を検証してください
• ホットリロードに対応した最適な開発環境には、npm run dev を使ってください