🎺 Overview

CLI to manage Claude Code sessions with built-in web dashboard and AI-powered compaction.

⭐ Features

• Session Compaction - Parse and summarize Claude Code sessions with AI
• Web Dashboard - Built-in server for session analysis
• Shell Completion - Tab completion for bash and zsh
• Auto-updates - Built-in update mechanism
• Detached Mode - Run web server in background
• Interactive Selection - User-friendly session picker

🚀 Installation

npm install -g better-claude-code

After installation, the bcc command will be available globally.

💡 Usage

Commands Overview

bcc --help                       # Show help
bcc compact                      # Interactively select a session to compact
bcc server --start               # Start the server
bcc update                       # Update to latest version

# Start server in foreground
bcc server --start

# Start on custom port
bcc server --start --port 3000

# Start in background (detached mode)
bcc server --start --detach

# Stop background server
bcc server --stop

The server runs the full BCC web dashboard at http://localhost:5000 by default.

Web Dashboard Features:

• Session browser with filtering and grouping
• Search by date, tokens, labels
• Project discovery with git integration
• Live Claude Code sessions
• Settings management

# Interactive session selection (up to 20)
bcc compact

# Show all sessions for selection
bcc compact --all

# Auto-compact latest session
bcc compact --latest

# Compact specific session by ID
bcc compact --id abc123

# Use last Claude message as title
bcc compact --last

Output:

Generates two files in your project root:

• Parsed markdown conversation
• AI-generated summary (cc-session-summary-{id}.md)

Compaction Workflow:

1. Parse: Converts JSONL session file to readable markdown
2. Summarize: Uses Claude Code CLI to generate AI summary

# Install completion for your shell (zsh or bash)
bcc completion install

Automatically detects your shell and installs to the appropriate location.

Reload shell:

source ~/.zshrc    # for zsh
source ~/.bashrc   # for bash

🔧 Development

pnpm install                     # Install dependencies
pnpm run dev                     # Run in development mode
pnpm run build                   # Build for production
pnpm run postbuild               # Bundle assets
pnpm run typecheck               # Type checking
pnpm run start                   # Run built CLI locally

Build Process:

The CLI bundles the entire backend and frontend as static assets:

1. TypeScript compilation
2. Backend + frontend bundled into dist/
3. Import paths fixed for distribution
4. Prompts and assets copied

This makes the CLI a self-contained executable.

📜 License

MIT License - see LICENSE file for details.