You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: refresh README, README.ru, QUICKSTART for current behaviour
The docs were written against the original spec — flat JSONL with role/content
at the top level and a sessions-index.json sidecar. Reality differs: Claude
Code uses nested message records and has no index, so all metadata is computed
directly from the .jsonl files.
Updates across all three files:
- list output example shows real-shape table: decoded project names
('Documents/Claude' instead of '-Users-macbook-Documents-Claude'),
8-char session prefixes, AI-generated titles in the title column
- export example uses session-prefix lookup ('claude-backup export f7a07eec')
- Markdown output sample shows the real frontmatter (title field, encoded
project, branch=HEAD) and the title-as-heading layout
- new section on --minimal mode (mini-log) explaining what it strips and
the .minimal.md filename suffix
- behaviour list rewritten: no sessions-index.json mention, calls out
AI-title surfacing, prefix matching, encrypted-signature stripping
- test stats updated to 64/64 (91% coverage)
- QUICKSTART adds a new Step 5 covering --minimal, plus FAQ entries
for short session IDs and the prior base64-noise fix
Copy file name to clipboardExpand all lines: QUICKSTART.md
+45-17Lines changed: 45 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -50,47 +50,50 @@ That's it. You can now run `claude-backup` from any folder.
50
50
claude-backup list
51
51
```
52
52
53
-
You'll see a table of every Claude Code session on your machine:
53
+
You'll see a table of every Claude Code session on your machine. The "First Prompt / Title" column shows the AI-generated session title when Claude Code recorded one, and falls back to your literal first prompt otherwise:
54
54
55
55
```
56
-
Project Session ID First PromptMsg Count Created Git Branch
my-webapp abc12345 Fix the login bug 42 2026-05-07T10:42:00
59
+
my-webapp def45678 Add dark mode toggle 18 2026-05-06T14:00:00
60
+
notes-app ghi78901 Refactor parser for nested blocks 7 2026-05-04T09:15:00
61
61
```
62
62
63
-
Each row is one conversation. Pick the one you want to save.
63
+
Each row is one conversation. The **Session** column shows just the first 8 characters of the ID — that's all you need to copy for the next step.
64
64
65
65
---
66
66
67
67
## Step 4 — Export a single conversation
68
68
69
-
Copy the **Session ID** from the table (e.g. `abc-123`) and run:
69
+
Copy the 8-character **Session**prefix from the table (e.g. `abc12345`) and run:
70
70
71
71
```bash
72
-
claude-backup exportabc-123 --output ./backups/
72
+
claude-backup exportabc12345 --output ./backups/
73
73
```
74
74
75
75
You'll see:
76
76
77
77
```
78
-
Exported: backups/2026-05-07--abc-123.md
78
+
Exported: backups/2026-05-07--abc12345-...md
79
79
```
80
80
81
81
Open that `.md` file in any text editor. It looks like this:
82
82
83
83
```markdown
84
84
---
85
-
project: my-webapp
86
-
session_id: abc-123
85
+
project: "-Users-yourname-projects-my-webapp"
86
+
session_id: abc12345-aaaa-bbbb-cccc-dddddddddddd
87
87
branch: main
88
-
model: claude-sonnet-4
88
+
model: claude-sonnet-4-6
89
89
messages: 42
90
90
exported_at: 2026-05-07T15:30:00Z
91
+
title: Fix the login bug
91
92
---
92
93
93
-
# my-webapp / main / abc-123
94
+
# Fix the login bug
95
+
96
+
_-Users-yourname-projects-my-webapp / main / abc12345-..._
94
97
95
98
## User (10:42:46)
96
99
fix the login bug
@@ -101,13 +104,30 @@ Here's the fix...
101
104
102
105
---
103
106
104
-
## Step 5 — Export everything at once
107
+
## Step 5 — Export the mini-log version (just the dialogue)
108
+
109
+
The default export captures **everything** — your prompts, Claude's replies, and every tool call (file reads, shell commands, etc.) plus their outputs. Useful for an audit trail, but noisy if you just want to read the conversation later.
110
+
111
+
For a clean transcript with only your messages and Claude's text replies, add `--minimal`:
Each project gets its own subfolder under `./backups/`. You now have a full Markdown archive.
117
+
This writes a separate file with `.minimal.md` suffix. Tool calls, tool results, and Claude's internal reasoning are dropped. Typically the mini-log is **30–50% the size** of the full export and reads like a normal chat log.
118
+
119
+
You can have both versions of the same session — they don't overwrite each other.
120
+
121
+
---
122
+
123
+
## Step 6 — Export everything at once
124
+
125
+
```bash
126
+
claude-backup export-all --output ./backups/ # full mode
127
+
claude-backup export-all --output ./backups/ --minimal # mini-log of every session
128
+
```
129
+
130
+
Each project gets its own subfolder under `./backups/`. You now have a complete Markdown archive of your Claude Code history.
111
131
112
132
---
113
133
@@ -137,6 +157,14 @@ That means you haven't used Claude Code on this machine yet, or it's installed f
137
157
138
158
No. It will print a warning, skip the bad lines, and continue with the rest.
139
159
160
+
**Why are some Session IDs so short in the table?**
161
+
162
+
The table shows only the first 8 characters of each session ID for readability. The full UUID is in the exported filename. You can pass the short prefix to `export` — the tool resolves it automatically.
163
+
164
+
**My exports used to contain huge walls of base64 — is that still a thing?**
165
+
166
+
No. Earlier versions accidentally rendered Claude's encrypted "thinking signatures" as JSON dumps, which produced kilobytes of base64 noise per assistant turn. The current parser strips those entirely while preserving any visible reasoning text.
New users: see [QUICKSTART.md](./QUICKSTART.md) for the full step-by-step guide (macOS, Linux, Windows/WSL).
@@ -76,27 +79,40 @@ pip install -e .
76
79
claude-backup list
77
80
```
78
81
79
-
Prints a table:
82
+
Prints a compact table — project paths are decoded from the encoded form Claude Code stores them as, and the "First Prompt / Title" column shows the AI-generated session title when present, falling back to the literal first prompt:
80
83
81
84
```
82
-
Project Session ID First Prompt Msg Count Created Git Branch
Documents/Claude f7a07eec Build claude-backup CLI tool with export 296 2026-05-07T07:35:01
86
91
```
87
92
88
93
### Export a single session
89
94
90
95
```bash
91
-
claude-backup export abc-123 --output ./backups/
96
+
claude-backup export f7a07eec --output ./backups/
97
+
```
98
+
99
+
Writes `./backups/2026-05-07--f7a07eec-<full-uuid>.md`. **You only need the first 8 characters of the session ID** — the tool resolves the prefix.
100
+
101
+
### Mini-log mode (`--minimal`)
102
+
103
+
When you just want a clean transcript of the conversation — your prompts and Claude's text replies — without tool calls, tool results, or extended-thinking blocks:
Writes a separate file with a `.minimal.md` suffix, so the full and minimal exports can coexist for the same session. Frontmatter records `mode: dialogue-only` and an adjusted `messages` count. Typically the minimal file is 30–50% the size of the full one.
95
110
96
111
### Export everything
97
112
98
113
```bash
99
114
claude-backup export-all --output ./backups/
115
+
claude-backup export-all --output ./backups/ --minimal # mini-log version of all sessions
100
116
```
101
117
102
118
Each project gets its own subdirectory under `--output`.
@@ -113,37 +129,55 @@ claude-backup --claude-home /path/to/projects list
113
129
114
130
## Output format
115
131
116
-
Each session is written as Markdown with YAML frontmatter:
132
+
Each session is written as Markdown with YAML frontmatter. When Claude Code has auto-generated a session title, it's used as the document heading and added to the frontmatter:
117
133
118
134
```markdown
119
135
---
120
-
project: my-webapp
121
-
session_id: abc-123
122
-
branch: main
123
-
model: claude-sonnet-4
124
-
messages: 42
136
+
project: "-Users-macbook-Documents-Claude"
137
+
session_id: f7a07eec-e18c-4ba5-96da-b798266c7486
138
+
branch: HEAD
139
+
model: claude-opus-4-7
140
+
messages: 296
125
141
exported_at: 2026-05-07T15:30:00Z
142
+
title: Build claude-backup CLI tool with export
126
143
---
127
144
128
-
# my-webapp / main / abc-123
145
+
# Build claude-backup CLI tool with export
146
+
147
+
_-Users-macbook-Documents-Claude / HEAD / f7a07eec-e18c-4ba5-96da-b798266c7486_
148
+
149
+
## User (07:35:01)
150
+
Build a backup tool for my Claude Code sessions...
129
151
130
-
## User (10:42:46)
131
-
fix auth bug
152
+
## Assistant (07:35:08)
153
+
I'll create the utility according to the spec...
132
154
133
-
## Assistant (10:42:50)
134
-
Here's the fix...
155
+
## Assistant (07:35:08)
156
+
[tool_use: Bash]
157
+
158
+
## User (07:35:09)
159
+
(Bash output here)
160
+
161
+
## Assistant (07:35:14)
162
+
[tool_use: Write]
163
+
...
135
164
```
136
165
166
+
`--minimal` mode produces the same frontmatter (with `mode: dialogue-only` added) but the body contains only `## User` and `## Assistant` text turns — no `[tool_use: ...]` markers, no tool-result echoes, no thinking blocks.
167
+
137
168
---
138
169
139
170
## Behaviour
140
171
141
-
-**Graceful degradation** — empty or corrupted `.jsonl` files are skipped with a warning. The tool never crashes on bad data.
142
-
-**Orphan sessions** — sessions discovered via `.jsonl` files but missing from `sessions-index.json` are still exported (with minimal metadata).
143
-
-**Ghost index entries** — sessions in the index without an on-disk `.jsonl` file are listed but cannot be exported.
172
+
-**Reads the real Claude Code format.** Metadata (first prompt, message count, created timestamp, AI title) is computed by streaming the `.jsonl` directly. No `sessions-index.json` is required — Claude Code doesn't actually create one.
173
+
-**AI-titles surfaced.** When Claude Code records an `ai-title` event, the title is shown in `list` output and used as the Markdown heading on export.
174
+
-**Decoded project names.** The encoded folder names Claude Code uses (e.g. `-Users-macbook-Documents-Claude`) are decoded to readable paths (`Documents/Claude`) in the `list` table.
175
+
-**Session ID prefixes.** Any prefix that uniquely identifies a session works — `claude-backup export f7a07eec` resolves to the full UUID. Ambiguous prefixes print all matches and exit.
176
+
-**Encrypted thinking signatures stripped.** Extended-thinking `signature` blobs (multi-kilobyte base64) never reach the output. Visible thinking text, when present, is preserved in italics.
177
+
-**Graceful degradation.** Empty or corrupted `.jsonl` files are skipped with a warning. The tool never crashes on bad data.
144
178
-**Missing `~/.claude/`** exits with code 1 and a clear error message.
145
-
-**Unicode-ready**— correctly handles Russian, emoji, and special characters.
146
-
-**Tool-aware**— preserves `tool_use` / `tool_result` blocks in readable Markdown.
179
+
-**Unicode-ready.**Correctly handles Russian, emoji, and special characters.
180
+
-**Tool-aware.**In full mode, `tool_use` / `tool_result`/ `image`blocks render as compact placeholders (`[tool_use: Bash]`, `[image]`) — never as raw JSON dumps.
147
181
148
182
---
149
183
@@ -156,7 +190,7 @@ pytest -v --cov=claude_backup
156
190
157
191
CI runs on Python 3.10, 3.11, and 3.12 — see [.github/workflows/test.yml](.github/workflows/test.yml).
158
192
159
-
**Test coverage: 93%** (42/42 tests passing).
193
+
**Test coverage: 91%** (64/64 tests passing) — covers the real Claude Code format, the legacy spec format, edge cases (empty/corrupt JSONL, unicode, missing index), the `--minimal` mode, and CLI integration.
0 commit comments