ccs

A terminal UI (TUI) tool for searching, browsing and resuming Claude Code conversations.

⚠️ DISCLAIMER: This is an unofficial third-party tool not affiliated with or endorsed by Anthropic. Use at your own risk.

ccs is a fork of sasazame/ccresume, renamed and extended with incremental search, session titles and layout improvements.

Overview

ccs provides an interactive terminal interface to browse and manage your Claude Code conversation history. It reads conversation data from your local Claude Code configuration and displays them in an easy-to-navigate format.

Key Features

• 🔍 Incremental search from launch — just start typing to filter sessions by title, dialogue content or directory name (single search box, AND across space-separated terms)
• 🏷️ Shows the session titles assigned by Claude Code
• 📋 Browse all Claude Code conversations across projects
• 🚀 Resume a conversation in its original project directory with Enter
• 🐚 Shell integration (ccs --init zsh) so your shell ends up in the session's directory after Claude Code closes
• 🖥️ Runs on the alternate screen (like peco/fzf) — nothing left in your terminal after exit
• 📎 Copy session IDs to clipboard
• 🆕 Start new Claude sessions in selected project directories
• 📁 Filter conversations to current directory with . argument
• 🎭 Hide specific message types for cleaner display
• ⚙️ Edit Claude command options interactively before starting sessions
• 🔄 Toggle full conversation view to see complete message history

Installation

Via npx

npx @malsuke/ccs@latest

Global Installation

npm install -g @malsuke/ccs

Usage

Run the command in your terminal:

ccs

The list opens in search mode: type to filter sessions instantly. Matching runs over session titles, the conversation dialogue (thinking/tool output is excluded) and project directory names.

Shell Integration (cd into the session's directory)

While a resumed Claude Code session is running, it already works in the session's original directory. However, a child process can never change its parent shell's directory — so after Claude Code exits, your shell is back where you launched ccs.

To have your shell cd into the selected session's directory after ccs exits, add the shell wrapper to your rc file:

# ~/.zshrc or ~/.bashrc
eval "$(ccs --init zsh)"    # or bash

# ~/.config/fish/config.fish
ccs --init fish | source

With this installed, running ccs and resuming a session leaves your shell in that session's project directory when Claude Code closes.

Command Line Options

ccs Options

# Hide specific message types
ccs --hide              # Default: hides tool and thinking messages
ccs --hide tool         # Hide only tool messages
ccs --hide thinking     # Hide only thinking messages
ccs --hide user         # Hide only user messages
ccs --hide assistant    # Hide only assistant messages
ccs --hide tool thinking user  # Hide multiple types

# Filter to current directory
ccs .

# Show help
ccs --help
ccs -h

# Show version
ccs --version
ccs -v

Passing Options to Claude

All unrecognized command-line arguments are passed directly to the claude command when resuming a conversation.

# Pass options to claude
ccs --dangerously-skip-permissions

# Multiple options
ccs --model opus --dangerously-skip-permissions

# Combine ccs and claude options
ccs --hide tool --model opus
ccs . --hide --dangerously-skip-permissions

⚠️ Warning: Since unrecognized arguments are passed to claude, avoid using options that conflict with ccs's functionality:

• Don't use options like --resume or something like that changes claude's interactive behavior

Requirements

• Node.js 22 / 24 (LTS)
• Claude Code - Must be installed and configured
• Operating System - Works on macOS, Linux, and Windows (both native & WSL)

Command Editor

Press - (in key mode) to open the command editor, where you can configure Claude CLI options before starting or resuming a session. The editor provides:

• Autocomplete suggestions - Type - to see matching Claude options
• Official help text - View all available Claude CLI options
• Interactive editing - Use arrow keys, Tab for autocomplete, Enter to confirm

The configured options will be passed to Claude when you start a new session (n) or resume a conversation (Enter).

Note: The options list is based on Claude's help text at a specific point in time. Please refer to claude --help for the latest available options. Some options like -r, -c, -h may interfere with ccs's functionality.

Keyboard Controls

Search Mode (default at launch)

| Action | Keys | |--------|------| | Filter sessions | just type (title / dialogue / directory) | | Select Previous / Next | ↑ / ↓ | | Resume selected conversation | Enter | | Delete last character | Backspace | | Switch to key mode | Tab | | Quit | Esc |

Key Mode (after Tab)

| Action | Keys | |--------|------| | Return to search mode | / | | Quit | q, Esc | | Select Previous / Next | ↑ / ↓ | | Confirm/Resume | Enter | | Start New Session | n | | Edit Command Options | - | | Copy Session ID | c | | Scroll Up / Down | k / j | | Page Up / Down | u, PageUp / d, PageDown | | Scroll to Top / Bottom | g / G | | Next / Previous Page | → / ← | | Toggle Full View | f |

Custom Key Bindings

You can customize key bindings by creating a configuration file at ~/.config/ccs/config.toml (the legacy ~/.config/ccresume/config.toml is still read as a fallback):

[keybindings]
quit = ["q", "ctrl+c", "esc"]
selectPrevious = ["up", "k"]
selectNext = ["down", "j"]
confirm = ["enter", "l"]
copySessionId = ["y"]
scrollUp = ["u", "ctrl+u"]
scrollDown = ["d", "ctrl+d"]
scrollPageUp = ["b", "ctrl+b"]
scrollPageDown = ["f", "ctrl+f"]
scrollTop = ["g"]
scrollBottom = ["shift+g"]
pageNext = ["right", "n"]
pagePrevious = ["left", "p"]
startNewSession = ["n"]
openCommandEditor = ["-"]
toggleFullView = ["f"]

See config.toml.example in the repository for a complete example.

Development

Setup

Install mise if it is not already available in your environment.

Install mise

curl https://mise.run | sh

See the official getting-started guide for platform-specific steps: https://mise.jdx.dev/getting-started.html

# Clone the repository
git clone https://github.com/malsuke/ccresume.git
cd ccresume

# Ensure mise is installed before proceeding
# (skip if already installed)

# Install tools via mise
mise install

# Install dependencies and git hooks
mise run init

Available Scripts

# Run in development mode
mise run dev

# Build the project
mise run build

# Run tests
mise run test

# Run tests in watch mode
mise run test:watch

# Generate test coverage
mise run test:coverage

# Run linter
mise run lint

# Type check
mise run typecheck

Local CI

Run the same checks as CI:

mise run ci

Compatibility Checks

Validate against all supported Node LTS versions:

mise run ci:matrix

Project Structure

ccs/
├── src/              # Source code
│   ├── cli.tsx       # CLI entry point
│   ├── App.tsx       # Main application component
│   └── ...           # Other components and utilities
├── dist/             # Compiled output
├── tests/            # Test files
└── package.json      # Project configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT

Credits

ccs is based on ccresume by sasazame.

Support

For issues and feature requests, please use the GitHub issue tracker.

🐞 Known Issues

Below are known issues and limitations (inherited from upstream ccresume). Contributions and suggestions are welcome!

| No. | Title | Description | Issue | |:---:|:------|:-------------|:-----| | 1 | Incomplete conversation history restoration on resume | When resuming with ccs, sometimes, only the tail end of the history is restored. Although the interactive claude -r can restore full history. Workaround: use claude -r interactively or claude -c. | upstream #2 | | 2 | Resume ordering may be incorrect | For performance reasons, ccs sorts logs by file system timestamps (not chat content), so display order may not match actual chronology after migration. Workaround: preserve file timestamps. | – | | 3 | Windows native terminal limitations | On Windows native terminals, interactive features may have limited functionality due to terminal input handling differences. Temporarily, in the Windows native environment, a warning message will be displayed before startup. | upstream #32 |

Remember: This is an unofficial tool. For official Claude Code support, please refer to Anthropic's documentation.