ccsession

CLI tool for efficient Claude Code session management and project switching.

🚀 Quick Start

# Install globally
npm install -g @jun-a/ccsession

# Launch interactive session selector
ccsession

# Search projects and sessions
ccsession search "my-project"

# Check system status
ccsession doctor

概要

ccsessionは、Claude Codeのセッション管理を効率化するCLIツールです。プロジェクトとセッションの検索・選択・起動を簡単に行えます。

主な機能

• 📁 プロジェクト管理: Claude Codeプロジェクトの一覧表示・選択
• 🗂️ セッション管理: プロジェクト内セッションの一覧表示・選択（最新順）
• 🔍 インクリメンタル検索: プロジェクト・セッション名での絞り込み
• 🚀 起動制御: Normal/YOLOモードでのClaude Code起動
• ⚡ 高速アクセス: キーボードナビゲーションでの快適操作

インストール

前提条件

• Node.js 16.0.0 以上
• Claude Code CLI（別途インストール必要）

グローバルインストール

npm install -g ccsession

ローカルビルド

git clone <repository-url>
cd ccsession
npm install
npm run build
npm link

使用方法

基本的な使用方法

# インタラクティブランチャーを起動
ccsession

# ヘルプを表示
ccsession --help

# バージョンを表示  
ccsession --version

コマンド

# プロジェクト・セッション検索
ccsession search <query>
ccsession s <query>

# 診断情報を表示
ccsession doctor
ccsession diag

# ヘルプを表示
ccsession help
ccsession h

オプション

# 詳細出力を有効化
ccsession --verbose

# デバッグモードを有効化  
ccsession --debug

操作方法

インタラクティブモード

1. プロジェクト選択

   • ↑/↓ 矢印キー: 選択項目の移動
   • Enter: プロジェクト選択確定
   • Ctrl+C: 終了

2. セッション選択

   • ↑/↓ 矢印キー: 選択項目の移動
   • Enter: セッション選択確定
   • Esc: プロジェクト選択に戻る
   • Ctrl+C: 終了

3. モード選択

   • ↑/↓ 矢印キー: Normal/YOLOモード選択
   • Enter: モード選択確定
   • Esc: セッション選択に戻る
   • Ctrl+C: 終了

画面表示例

ccsession Session Launcher

? Select a project: (Use arrow keys)
❯ my-web-app (/Users/user/projects/my-web-app)
  3 sessions • last accessed 2 hours ago
  data-analysis (/Users/user/projects/data-analysis)  
  5 sessions • last accessed 1 day ago
  api-server (/Users/user/projects/api-server)
  12 sessions • last accessed 3 days ago

Project: my-web-app

? Select a session: (Use arrow keys)
❯ Feature implementation
  2 hours ago - 45 messages
  Bug fixes  
  1 day ago - 23 messages
  Initial setup
  3 days ago - 12 messages

Press Esc to go back

データ構造

ccsessionは、Claude Codeの設定データを以下の場所から読み取ります：

• 設定ディレクトリ: ~/.claude/
• プロジェクトデータ: ~/.claude/projects/
• セッションファイル: {project-id}/{session-id}.jsonl

トラブルシューティング

Claude Code not found

# Claude Code CLIがインストールされていない場合
❌ Claude Code not found. Tried: claude-code, claude, code
💡 Please install Claude Code CLI first: https://claude.ai/code

解決方法:

1. Claude Code CLIをインストール
2. PATHにClaude Codeコマンドが含まれていることを確認

No projects found

❌ No Claude Code projects found
💡 Open a project directory with Claude Code to create your first project.

解決方法:

1. Claude Codeで任意のプロジェクトディレクトリを開く
2. セッションを作成してプロジェクトデータを生成

Permission errors

❌ Cannot access directory: /Users/user/.claude/projects
💡 Check file permissions and ensure the directory exists.

解決方法:

1. Claude Code設定ディレクトリの権限を確認
2. Claude Codeを一度実行して設定ファイルを初期化

診断機能

# システム状態を確認
ccsession doctor

出力例：

ccsession Diagnostics

🔍 Checking Claude Code availability...
✅ Claude Code found: claude
   Version: 1.0.59 (Claude Code)

🔍 Checking project data...
✅ Found 12 projects
   my-web-app: 15 sessions
   data-analysis: 8 sessions
   api-server: 23 sessions
   ... and 9 more

開発

開発環境のセットアップ

git clone <repository-url>
cd ccsession
npm install

開発中の実行

# TypeScriptを直接実行
npm run dev

# ビルド
npm run build

# テスト実行
npm test

# リンター実行
npm run lint

プロジェクト構造

src/
├── cli/
│   ├── index.ts                 # CLI entry point
│   ├── ccsession-cli.ts         # Main CLI logic
│   └── ui/
│       └── interactive-ui.ts    # Interactive UI components
├── core/
│   ├── container.ts             # Dependency injection
│   └── services/                # Business logic
│       ├── project-service.ts
│       ├── launch-service.ts
│       └── search-service.ts
├── data/
│   ├── claude-config.ts         # Claude Code configuration
│   └── repositories/            # Data access
│       ├── project-repository.ts
│       └── session-repository.ts
├── utils/
│   ├── errors.ts                # Error handling
│   └── file-utils.ts            # File operations
└── types/
    └── index.ts                 # Type definitions

ライセンス

MIT License