npm package: @jun-a/ccsession
Description: CLI tool for efficient Claude Code session management and project switching
Author: ccsession development team
Latest version: 1.0.3

# ccsession

[![npm version](https://badge.fury.io/js/@jun-a%2Fccsession.svg)](https://badge.fury.io/js/@jun-a%2Fccsession)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-16%2B-brightgreen.svg)](https://nodejs.org/)

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

## 🚀 Quick Start

```bash
# 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（別途インストール必要）

### グローバルインストール

```bash
npm install -g ccsession
```

### ローカルビルド

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

## 使用方法

### 基本的な使用方法

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

# ヘルプを表示
ccsession --help

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

### コマンド

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

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

# ヘルプを表示
ccsession help
ccsession h
```

### オプション

```bash
# 詳細出力を有効化
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

```bash
# 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

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

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

### Permission errors

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

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

### 診断機能

```bash
# システム状態を確認
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
```

## 開発

### 開発環境のセットアップ

```bash
git clone <repository-url>
cd ccsession
npm install
```

### 開発中の実行

```bash
# 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