claude-logbook

Browse every Claude Code conversation stored on your machine — as a table in your terminal, or as a single self-contained HTML page you open with a double click.

Español · English · No dependencies, standard library only.

  #   SESSION                        PATH                  DATE   WHEN       MSG    DUR ID
  1 | Migrate the connection pool t… /home/ana/api         16 Aug today        4     9m 5d10f1ee
  2 | Intermittent timeouts in the … /home/ana/api         16 Aug today        2     3m 0f60f37a
  3 | Rewrite search with Fuse.js    /home/ana/web         15 Aug yesterday    7    18m b69c1fc2
  4 | why is npm ci so slow          /home/ana/web         13 Aug 3d ago       1    <1m d4d2a5be
  5 | session opened with n… [empty] /home/ana/infra       08 Aug 1w ago       —    <1m e0a4300e

5 sessions · 3 projects · -s <#> to read one

The command reads local files and never sends anything anywhere.

⚠️ Your transcripts are private

--json and --html write out the full text of your conversations and your projects' memories: prompts, answers, file paths, branch names. The generated sessions.html is a complete, readable copy of everything you ever typed into Claude Code. Exporting a single session (-s 3 --html) is still that whole conversation: read it before you share it.

--share uploads one conversation on purpose, to a public link: see Sharing a session.

Do not commit it, do not upload it, do not paste it into a bug report. The repository's .gitignore already excludes sessions.html and data.json, but the file itself is yours to look after.

Install

Requires Python 3.9 or newer. Nothing else.

pipx install claude-logbook

Or with pip, from the latest commit, or straight from a clone:

pip install claude-logbook

pipx install git+https://github.com/ElvisClaros/claude-logbook   # unreleased

git clone https://github.com/ElvisClaros/claude-logbook && cd claude-logbook
python3 -m claude_logbook          # no install needed

Usage

claude-logbook                     # table of every session
claude-logbook docker              # filter by title, path or branch
claude-logbook -s 3                # read conversation #3 from the table
claude-logbook -s 5d10f1ee         # same, by UUID prefix
claude-logbook -g "port already"   # search inside the conversations
claude-logbook -r 3                # print the command that resumes it
eval "$(claude-logbook -r 3)"      # …or resume it right away
claude-logbook --html --open       # build sessions.html and open it
claude-logbook -s 3 --html         # export only #3 → session-<id>.html
claude-logbook -m                  # your projects' memories
claude-logbook -P                  # permissions, extra directories and trust

The number is the row's position in the table you are looking at, so if you filtered, repeat the filter to read that row:

claude-logbook docker              # shows 3 results
claude-logbook docker -s 2         # reads the 2nd of those three

Options

Deleting sessions

Irreversible, and it asks first unless you pass -y:

claude-logbook --delete-empty --dry-run   # what it would delete
claude-logbook --delete-empty             # delete the empty ones
claude-logbook -D 101 -D e0a4300e         # delete specific sessions
claude-logbook -p /tmp --delete-empty     # only the empty ones of that project

It warns you about any file written in the last five minutes: that is very likely a session Claude Code still has open, and it will write it back on exit.

Project memory

Claude Code stores per-project memories in ~/.claude/projects/<project>/memory/: one .md per memory, with YAML frontmatter and a markdown body, plus a MEMORY.md that indexes them.

The index is the only part loaded into context when a session starts. A memory that is on disk but missing from MEMORY.md stops being remembered even though the file is still there, so the gap between the two is worth watching.

-m swaps the noun and reuses the verbs you already know:

claude-logbook -m                  # table of memories
claude-logbook -m docker           # search name, description and body
claude-logbook -m --type user      # only one kind
claude-logbook -m -s 3             # read memory #3
claude-logbook -m -s deadlock      # same, by name
claude-logbook -m -p /home/u/proj  # only one project's

Claude picks the kind when it writes them: project is work in progress, user is who you are and how you work, feedback is corrections you gave, and reference points at external resources.

Auditing

claude-logbook -m --check

Exits 1 if it finds anything, and reports:

• projects with memories but no MEMORY.md;
• memories missing from their project's index;
• index entries pointing at a file that no longer exists;
• [[...]] links with no target — the format allows them, they mark something not written yet;
• memories whose origin session is gone from disk: the memory outlived the conversation that created it.

Deleting memories

Same as sessions: irreversible, asks first unless you pass -y. Besides removing the file it drops its line from MEMORY.md, so the index is not left pointing at nothing.

claude-logbook -m -D 3 --dry-run   # what it would delete
claude-logbook -m -D deploy-docker # delete that memory

Permissions

Claude Code keeps its permission rules in settings.json files and the "do you trust this folder?" answer in ~/.claude.json. -P shows them all together, and a handful of flags edit them without opening any JSON:

claude-logbook -P                          # user rules + every project with rules
claude-logbook -P -p api                   # one project, with or without rules
claude-logbook --allow "Bash(npm test:*)" -p .
claude-logbook --deny "Read(./.env)" --scope project -p .
claude-logbook --remove-rule WebFetch      # out of allow, ask and deny
claude-logbook --add-dir ~/shared -p .     # additionalDirectories
claude-logbook --trust -p ~/code/api       # mark that folder as trusted
claude-logbook --untrust -p ~/code/api     # Claude Code will ask again

Where each change goes:

-p takes a directory, or any piece of a project path Claude Code has seen as long as it matches only one. Rules use Claude Code's syntax: Tool or Tool(specifier). A rule lives in one list only, so --deny X takes X out of allow and ask. Every other key in those files is kept as it was, the file is replaced atomically with its permissions intact, and --dry-run shows the change without making it. Sessions that are already open may need a restart to notice.

~/.claude.json also holds your account and the state of every running Claude Code, which rewrite it often: claude-logbook reads it right before changing it, and retries if it moves in between.

Sharing a session

--share publishes one session on https://claude-logbook.all.ar and prints its link:

claude-logbook -s 3 --share               # shows what goes up and asks
claude-logbook -s 3 --share --expire 7d   # gone in a week (default 30 days)
claude-logbook -s 3 --share               # again later: same link, new content
claude-logbook --shares                   # what you have shared, and until when
claude-logbook --unshare 5d10f1ee         # take it down (id, URL or session)

Each share has three forms:

Before uploading it shows the title, the project path, the size and a warning for anything that looks like an API key, a token or a private key (where it is, never the value). --dry-run stops there.

What to keep in mind:

• Anyone with the link can read the whole conversation, tool calls and paths included. It is not encrypted; the server can read it too.
• Only the machine that created a share can update or delete it: the server returns a secret that is kept in $XDG_STATE_HOME/claude-logbook/shares.json (~/.local/state/...), mode 600. Lose that file and the share stays until it expires.
• Memories are never shared.

The server lives in server/: Go, standard library only, a FROM scratch Docker image. You can run your own and point CLAUDE_LOGBOOK_SERVER at it.

The HTML page

claude-logbook --html produces one file with the data embedded inside it. No server, no network, no build step — copy it to another machine and it still works.

• Search by title, path, branch or UUID, and optionally inside the transcripts, with the matching snippet shown under the row.
• Filter by project, sort by any column, hide empty sessions.
• Click a row to read the conversation in a side panel, with code fences, headings and one line per tool call.
• Copy the cd … && claude --resume … command for any session.
• Light and dark themes, with a toggle that remembers your choice.
• Each session gets its own URL fragment, so sessions.html#5d10f1ee-… opens that conversation directly.
• Keyboard: / or Ctrl+K focuses the search box, Esc clears it or closes the reader.

Dates are relative to when the data was read, not to your clock, so "today" keeps meaning what it meant when you generated the page.

How it works

Claude Code writes one JSON Lines file per conversation:

~/.claude/projects/<url-encoded-project-path>/<uuid>.jsonl

(CLAUDE_CONFIG_DIR is honoured if you moved that directory.)

Every line is an event. claude-logbook walks them and keeps the conversation itself — your messages, Claude's replies, and a one-line summary per tool call such as Bash: git status. It deliberately drops tool results, which are about 95% of the bytes on disk and almost none of the meaning.

A few details worth knowing:

• Titles. The one you set with /rename wins (custom-title events); otherwise the one Claude generates during the session (ai-title), the most recent of each. Without either, the first thing you typed is used instead — which is visible, because it starts in lowercase or reads like a loose question.
• Compaction. When the context runs out (or on /compact) Claude Code replaces the earlier conversation with a summary. That summary is shown as a "context compacted here" mark, not as a message of yours, and is not counted.
• Duration is active time: the gaps between messages, leaving out pauses longer than 30 minutes. A session resumed over several days does not count the days in between.
• Empty sessions were opened but never received a message: a cancelled /resume, a /login.
• Non-interactive sessions are claude -p with something piped into stdin — typically a git diff to write a commit message. They are detected as a single very long message with no back and forth.
• Inferred paths. A cancelled /resume never records a cwd, and the directory name cannot be reversed reliably (both / and . encode as -), so the path is borrowed from another session of the same project and flagged.
• Sidechains (subagent transcripts) are skipped.
• Cache. Parsed sessions are cached in $XDG_CACHE_HOME/claude-logbook/cache.json, keyed by size and mtime. It is only an optimisation: if it is missing, stale or corrupt, everything is re-parsed. --no-cache skips it entirely.

JSON schema

--json prints an object with two arrays: s holds the sessions, most recently active first, and m the memories, most recently modified first.

{"s": [ … ], "m": [ … ]}

Keys are one letter because the same records are embedded in the HTML, where the cost is paid once per record.

Each session in s:

Each memory in m:

Development

git clone https://github.com/ElvisClaros/claude-logbook && cd claude-logbook
python3 -m unittest discover -s tests -t .

The tests build fake .jsonl trees in a temporary directory and never touch ~/.claude. There is nothing to install: no test runner, no dependencies.

License

Apache-2.0.