Skip to main content

ccbookmark

Bookmark, resume, and export your Claude Code conversations.

Claude Code keeps every session on disk, but there's no good way to curate the ones that matter: bookmark them, tag them, keep them past the 30‑day cleanup, jump back into one by id, or seed a conversation into a different project. ccbookmark does exactly that — from the terminal, from a web UI, or from inside Claude Code itself via MCP.

CI License: MIT Python 3.11+

ccbookmark web UI


Why

Claude Code already does a lot natively — --resume, --continue, /rewind, forking, and a plain‑text /export. What it doesn't do:

Gap ccbookmark
Resume is scoped to the project it started in Export a conversation into any other project and resume it there
Transcripts are auto‑deleted after ~30 days Bookmark the ones you care about into a durable library
No way to curate / tag / search your own picks A SQLite‑indexed library with extracted summaries, tags, and search
History tooling is read‑only viewers A save → list → restore/export workflow over CLI + MCP + web

There are plenty of JSONL viewers and "search my history" MCP servers. The thing that's genuinely rare — and what this tool is built around — is a curated, resumable library you can move between projects.

How it works

Claude Code stores each session as a JSONL file:

~/.claude/projects/<encoded-cwd>/<session-id>.jsonl

where <encoded-cwd> is the absolute working directory with every / and . replaced by -. claude --resume <session-id> finds a session by reading that file from the project dir derived from the cwd. The JSONL holds the full history: user/assistant turns, embedded file contents, cwd, gitBranch, version, an ai-title, and any compaction summaries.

ccbookmark reads those files, copies the ones you bookmark into its own library, and indexes their metadata:

~/.ccbookmark/                 # override with CCBOOKMARK_HOME
  archive/<session-id>.jsonl   # verbatim copy (preserves embedded files)
  index.db                     # SQLite metadata + extracted summaries
Command What it does
save Parse a live session, copy its JSONL into the library, index metadata + an extracted summary (ai-title + compaction summary + first prompt). No API key needed.
list Browse bookmarks (newest first); filter by text / tag.
show Title, summary, cwd, branch, message & token counts, touched files.
restore Copy the JSONL back to its project dir so claude --resume <id> works again.
export Copy a bookmark into a different project, re‑pathing its cwd.
delete Remove from the library (optionally purge the archived JSONL).

Install

Requires uv and Python 3.11+.

git clone https://github.com/kiliancm94/ccbookmark.git
cd ccbookmark
uv sync --extra dev

Quick start

# Bookmark the most recent session in the current project (or pass --id / --cwd)
uv run ccbookmark save --tag work
uv run ccbookmark save --id <session-id> --tag research

uv run ccbookmark list --query parser
uv run ccbookmark show <session-id>

# Make a bookmark resumable again, then run the printed command
uv run ccbookmark restore <session-id>

# Copy a conversation into another project (fresh id avoids collisions);
# embedded file paths under the old cwd are re-pathed too (--no-rewrite-paths to skip)
uv run ccbookmark export <session-id> /path/to/other/repo --new-id

# Delete one, or bulk-delete by tag / text query
uv run ccbookmark delete <session-id> --purge
uv run ccbookmark delete --tag scratch --purge

Optional: richer summaries via the Claude API

Summaries are extracted from the JSONL by default (no key, no cost). To rewrite a summary with the Claude API instead, install the extra and set a key:

uv sync --extra summary           # adds the `anthropic` dependency
export ANTHROPIC_API_KEY=sk-ant-...
uv run ccbookmark save --regenerate
# model defaults to claude-opus-4-8; override with CCBOOKMARK_SUMMARY_MODEL

Web UI

uv run ccbookmark-web        # http://127.0.0.1:8765

A single‑page UI (no build step) with two tabs:

  • Saved — browse/search your bookmarks; click a row for a detail drawer with the summary, files, and metadata, plus Restore, Export to project…, and Delete. Restore/Export show the exact claude --resume command (click to copy).
  • Available to save — lists live Claude Code sessions (across all projects, or filtered by cwd) with one‑click Save.

Override the bind address with CCBOOKMARK_HOST / CCBOOKMARK_PORT.

Use it from inside Claude Code (MCP)

Register the MCP server, then ask Claude things like "bookmark this conversation" or "list my bookmarked conversations":

# run from your clone of this repo
claude mcp add --scope user ccbookmark -- uv run --directory "$(pwd)" ccbookmark-mcp

Tools exposed: save_conversation, list_saved, show_conversation, restore_conversation, export_conversation, delete_saved.

An MCP server can't reliably know the current session id, so save_conversation defaults to the most recently modified session in the given cwd. Pass an explicit session_id to be certain.

Architecture

cli.py / mcp_server.py / web.py   thin interfaces (CLI · MCP · FastAPI + static UI)
            |
          core.py            save / list / list_live / show / restore / export / delete
           /    \
      store.py   parser.py   SQLite index   |   stream-parse JSONL -> SessionMeta
            \    /
           paths.py          path<->project-dir encoding, locate session files

All three interfaces are thin wrappers over one engine (core.py), so they stay in lockstep.

How it compares

Tool Bookmark/curate Resume Export to other project Web UI MCP server
ccbookmark ✅ ✅ ✅ ✅ ✅
Claude Code (native --resume//export) – ✅ (same project) – – –
claude-session-restore – ✅ – – ✅
claude-vault ✅ – – – –
claude-code-viewer – ✅ – ✅ –

Resume‑by‑id, viewers, and history‑search MCP servers are well covered elsewhere; the curated, cross‑project‑exportable library over CLI + MCP + web is what ccbookmark adds.

Notes / limitations

  • Restore only copies the JSONL back if it's missing; it never overwrites a live session.
  • Export rewrites the top‑level cwd (and sessionId with --new-id) and, by default, any embedded file path under the original cwd — so file references follow the conversation to the new project. Pass --no-rewrite-paths to keep the original absolute paths. Content that merely mentions a path (not a path value) is left untouched.

Development

uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run pyright

License

MIT © Kilian Cañizares Mata

Metadata

Release files for ccbookmark 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ccbookmark 0.2.0
File Size Uploaded Provenance Actions
ccbookmark-0.2.0.tar.gz 126.9 kB Without provenance Details for ccbookmark-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ccbookmark 0.2.0
File Interpreter ABI Platform Actions
ccbookmark-0.2.0-py3-none-any.whl Python 3 none any Details for ccbookmark-0.2.0-py3-none-any.whl

Total release size: 152.1 kB

Release files / ccbookmark-0.2.0.tar.gz

Download URL ccbookmark-0.2.0.tar.gz
Size 126.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5e88af402812000dcaed2f189473e359a563328b44d6475fcc8e2a50c335f348
BLAKE2b-256 checksum
How to use checksums
e856528c45b4f7360d54aaed6dbbbc7b465ec0f85ca70eef19365af9ae2cb40a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ccbookmark-0.2.0-py3-none-any.whl

Download URL ccbookmark-0.2.0-py3-none-any.whl
Size 25.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
48c95fe01fcb2f5365b225c5cc8427612163df4bd3538f8ad40cdab7cd41823d
BLAKE2b-256 checksum
How to use checksums
96a1da9393a33abe65d2ed5fbab97d1a89c06d9a9b68b41831d4303857ff2b44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ccbookmark 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page