cc-sessions

A session bookmark manager for Claude Code

Browse and resume Claude Code sessions across all your projects. Bookmark important conversations, fork sessions to explore alternatives, and never lose context again.

✨ Features

• 🔖 Bookmark sessions — Name and bookmark important conversations directly from inside Claude Code with /bookmark
• ▶️ Resume from anywhere — Open any bookmarked session from any directory, always in the correct project context
• 📚 Session browser — Browse bookmarked and all sessions in an interactive TUI with live filtering
• 🔀 Fork sessions — Branch off a conversation to explore an alternative without touching the original
• 🆕 Start named sessions — Launch Claude with a session name already set, so it's bookmarked from the start
• 📊 Stats — Usage overview across all your projects

🎬 See it in action

Bookmark a session inside Claude Code and resume it later

Use /bookmark my-session-name inside any Claude Code conversation to save it. Then open cc-sessions list from anywhere to resume it in the correct project context.

Bookmark sessions from the TUI

Delete sessions

Mark one or more sessions with X, then confirm deletion with Z.

⚡ Quick Start

npm install -g @i-am-nio/cc-sessions
cc-sessions init

That's it! cc-sessions will set up hooks, import your existing sessions, and register the /bookmark slash command inside Claude Code.

Restart Claude Code after running init for the hooks to take effect.

📋 Prerequisites

• Node.js 20+
• Claude Code

🖥️ The TUI

Bookmarks tab

Your named sessions, always one keystroke away. Press ENTER to resume in the original project directory.

Stats tab

Usage overview across all your projects — session counts, activity, and more.

📦 Commands

Inside Claude Code

| Command | Description | |---|---| | /bookmark name | Bookmark the current session with a name |

In your terminal

| Command | Description | |---|---| | cc-sessions init | One-time setup — configures hooks, imports existing sessions, registers /bookmark | | cc-sessions list | Open the interactive session browser (--all to show all sessions, not just bookmarks) | | cc-sessions new name | Start a new Claude session in the current directory, bookmarked under the given name | | cc-sessions import | Manually scan ~/.claude/projects/ and sync the session index | | cc-sessions uninstall | Remove cc-sessions hooks from Claude settings, keep bookmarks | | cc-sessions uninstall --nuke | Remove hooks, all session data, and the /bookmark command |

⌨️ Key Bindings

Letter keys are case-sensitive — use uppercase.

| Key | Action | |---|---| | ↑ ↓ | Navigate sessions | | ENTER | Resume selected session | | F | Fork selected session (with confirmation) | | B | Bookmark selected session | | R | Rename bookmark | | D | Unbookmark (with confirmation) | | O | Open project in Cursor / VS Code | | A | Toggle between bookmarks only / all sessions | | X | Mark session for deletion | | Z | Delete all marked sessions | | ESC | Clear filter / Quit | | Type anything | Filter sessions live |

🔧 How It Works

Running cc-sessions init will:

1. Create ~/.config/cc-sessions/ to store your session index
2. Register Claude Code lifecycle hooks (session tracking)
3. Import all your existing sessions from ~/.claude/projects/
4. Add the /bookmark slash command inside Claude Code
5. Add a status line showing the current session's bookmark name

cc-sessions integrates with Claude Code via its native hook system:

• SessionStart — Registers the new session and runs import to prune stale entries
• UserPromptSubmit — Updates lastActiveAt for the current session
• Stop — Marks the session as inactive
• statusLine — Displays the current session's bookmark name in the Claude Code status bar

Sessions are stored in ~/.config/cc-sessions/index.json. Each entry tracks the session ID, project path, git branch, first prompt, Claude's auto-generated summary (when available), bookmark name, and timestamps.

Resume across projects

When you resume a session from cc-sessions list, the claude process is spawned in the session's original project directory — not wherever you ran cc-sessions list from. This ensures the correct project context is always used.

Fork

Forking uses claude --resume <id> --fork-session, which creates a new session branching from the selected conversation's full context. The original session is never modified.

📂 File Structure

~/.config/cc-sessions/
└── index.json       # Session index with bookmarks, names, summaries

~/.claude/
├── settings.json    # Auto-updated with hooks, statusLine, permissions
└── commands/
    └── bookmark.md  # /bookmark slash command

🩺 Troubleshooting

"No conversation found" when resuming a session

If resuming fails with:

No conversation found with session ID: <id>

This is a Claude server-side issue — the session has become stale on Anthropic's servers even though the local file still exists.

Fix: manually re-register the session by running the resume command directly from the project directory:

cd /path/to/your/project
claude --resume <session-id>

Once Claude successfully resumes it, it re-registers server-side and cc-sessions list will work again.

You can find the session's project path in the preview pane of cc-sessions list under Project.

This can happen when:

• Claude experiences a temporary server-side incident
• The session has been idle for an extended period
• The session encountered API errors during a previous conversation

🔗 Related

• Claude Code — Official documentation

📄 License

MIT — see LICENSE for details.