Skip to content

Commit 66c9c79

Browse files
committed
Add Claude Cowork support; recover subagents in both sources
The biggest functional change since the initial release. Two things land together because they share most of the plumbing: 1. CLAUDE COWORK SUPPORT The local-agent desktop app stores sessions at ~/Library/Application Support/Claude/local-agent-mode-sessions/, in a deeper hierarchy: <account>/<workspace>/local_<session>/.claude/projects/<cwd>/<id>.jsonl. The JSONL format is identical to Claude Code, so the parser is reused; the scanner gets a new walk to discover them. Both sources are auto-detected — no flag required. CLI now shows a Source column ('Code' or 'Cowork') in 'list' output, and 'export-all' organises output as <output>/<source>/<project>/<files> so the two are clearly separated on disk. 2. SUBAGENT RECOVERY (BOTH SOURCES) Subagent transcripts live at <project>/<session_id>/subagents/agent-*.jsonl and were silently dropped before — including 5 subagents in one of my own test sessions. Now they're discovered alongside the main JSONL and rendered as a '# Subagents' section appended to the full export, with each one as its own '## Subagent N: <id>' block. Minimal export drops them (subagent runs are tool plumbing, not human dialogue). Frontmatter gains: - 'source: code|cowork' on every export - 'subagents: N' when N > 0 in full mode DESIGN CHOICES IN SERVICE OF USABILITY - Folder layout chosen to mirror the user's mental model: 'I have Claude Code and Claude Cowork' -> 'backups/code/' and 'backups/cowork/'. - Cowork session directories use the friendly codenames Cowork itself generates ('beautiful-charming-curie') rather than UUIDs, when available. Sessions whose cwd is the internal outputs dir fall back to 'session-<8-char-id>'. - 'list' table now has Source as the first column. AI-titles are prioritised in the 'First Prompt / Title' column for readability. - Error message updated for the both-sources case: lists every root tried. TESTS +12 new tests (was 73, now 85). New fixtures-cowork/ tree mirrors real on-disk Cowork structure including a subagent file. test_cowork.py covers: - Cowork scanner discovery - Subagent linkage (in both sources) - Source column in CLI list - Source-based folder layout in export-all - 'works with only Cowork data' (no Code root) - 'errors when neither source exists' Existing tests updated for new frontmatter ('source:'), new folder layout ('<output>/code/...'), and the unified error path. A new conftest auto-fixture isolates every test from the developer's real ~/.claude/ and ~/Library/Application Support/Claude/, preventing tests from accidentally scanning real data. DOCS README, README.ru, QUICKSTART, PROMPT all updated for the dual-source reality. New behaviour bullets, new tree diagrams, new error messages, new total test count (85).
1 parent e036c2d commit 66c9c79

14 files changed

Lines changed: 642 additions & 153 deletions

File tree

PROMPT.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Copy everything between the lines:
1818
---
1919

2020
```
21-
I want to install and try `claude-backup` — a CLI tool that exports my Claude Code session history to local Markdown files. The repo is https://github.com/parallelclaw/claude-backup.
21+
I want to install and try `claude-backup` — a CLI tool that exports my Claude Code AND Claude Cowork session history (both apps) to local Markdown files. The repo is https://github.com/parallelclaw/claude-backup.
2222
2323
Walk me through it step by step. After each step, wait for me to paste the output before moving on. Be terse — no walls of text, one short paragraph per step is fine. Don't run commands yourself; print the command and let me run it.
2424
@@ -28,13 +28,13 @@ The full path:
2828
2. Have me `git clone https://github.com/parallelclaw/claude-backup.git` somewhere convenient (default: `~/Desktop`) and `cd` into the repo.
2929
3. Have me run `pip3 install --user -e .`. If pip warns that the install dir isn't on PATH, give me the right `export PATH=...` line for my OS AND tell me how to make it permanent (in `~/.zshrc` on macOS / `~/.bashrc` on Linux).
3030
4. Have me run `claude-backup --version` to confirm the CLI is reachable.
31-
5. Have me run `claude-backup list` and help me read the table — explain what each column means (Project / Session / First Prompt or Title / Msgs / Created).
32-
6. Pick an interesting session with me and have me run `claude-backup export <8-char-prefix> --output ./backups/`. By default this writes two files: `<id>.md` (clean dialogue, only my prompts and Claude's text replies) and `<id>.full.md` (everything, including tool calls and tool results). Explain when to use each.
31+
5. Have me run `claude-backup list` and help me read the table. Columns: Source (Code or Cowork) / Project / Session (8-char prefix) / First Prompt or Title / Msgs / Created. Note that the tool auto-finds both Claude Code (`~/.claude/projects/`) and Claude Cowork (`~/Library/Application Support/Claude/local-agent-mode-sessions/`); if I have only one, the other is silently skipped.
32+
6. Pick an interesting session with me and have me run `claude-backup export <8-char-prefix> --output ./backups/`. By default this writes two files: `<id>.md` (clean dialogue, only my prompts and Claude's text replies) and `<id>.full.md` (everything tool calls, tool results, AND any subagent transcripts the session spawned). Explain when to use each.
3333
7. Have me `open ./backups/<filename>.md` (macOS) or `xdg-open` (Linux) to view the result. Ask what I think.
34-
8. If I want a full backup of everything, have me run `claude-backup export-all --output ~/claude-backups`. Explain that the resulting folders mirror my real working directories (with the home prefix stripped).
34+
8. If I want a full backup of everything, have me run `claude-backup export-all --output ~/claude-backups`. Explain that the output is split first by source — `code/` and `cowork/` subfolders — and inside each, organised by project (Code mirrors my real working dirs, Cowork uses the friendly codename like `beautiful-charming-curie` that Cowork itself generates).
3535
3636
If a command errors: help me debug, don't just dump a fix. Common issues —
37-
- `~/.claude/projects/` not found → I haven't used Claude Code on this machine yet
37+
- "Claude data not found" → I haven't used either Claude Code or Cowork on this machine yet
3838
- `pip: command not found` → try `python3 -m pip` instead
3939
- `command not found: claude-backup` after install → PATH issue, see step 3
4040
- "externally-managed-environment" pip error → use `pip3 install --user --break-system-packages -e .` or a venv
@@ -51,7 +51,7 @@ Start with step 1.
5151
---
5252

5353
```
54-
Я хочу установить и попробовать `claude-backup` — CLI-утилиту, которая экспортирует историю моих сессий Claude Code в локальные Markdown-файлы. Репозиторий — https://github.com/parallelclaw/claude-backup.
54+
Я хочу установить и попробовать `claude-backup` — CLI-утилиту, которая экспортирует историю моих сессий Claude Code И Claude Cowork (обе утилиты) в локальные Markdown-файлы. Репозиторий — https://github.com/parallelclaw/claude-backup.
5555
5656
Проведи меня по шагам. После каждого шага жди когда я вставлю вывод. Будь лаконичен — никаких стен текста, один короткий абзац на шаг достаточно. Сам команды не выполняй — печатай команду и жди пока я выполню.
5757
@@ -61,13 +61,13 @@ Start with step 1.
6161
2. `git clone https://github.com/parallelclaw/claude-backup.git` куда-нибудь удобно (по умолчанию `~/Desktop`) и `cd` в репозиторий.
6262
3. `pip3 install --user -e .`. Если pip ругается что папка не в PATH — дай правильную строку `export PATH=...` для моей системы И объясни как сделать перманентным (в `~/.zshrc` на macOS / `~/.bashrc` на Linux).
6363
4. `claude-backup --version` — проверить что CLI работает.
64-
5. `claude-backup list` — помоги прочитать таблицу, объясни колонки (Project / Session / First Prompt или Title / Msgs / Created).
65-
6. Выбери со мной одну сессию и вели мне `claude-backup export <8-символьный-префикс> --output ./backups/`. По умолчанию создаются два файла: `<id>.md` (чистый диалог — только мои промпты и текстовые ответы Claude) и `<id>.full.md` (всё, включая tool-вызовы и tool-результаты). Объясни когда использовать каждый.
64+
5. `claude-backup list` — помоги прочитать таблицу. Колонки: Source (Code или Cowork) / Project / Session (8-символьный префикс) / First Prompt или Title / Msgs / Created. Заметь что утилита авто-находит и Claude Code (`~/.claude/projects/`), и Claude Cowork (`~/Library/Application Support/Claude/local-agent-mode-sessions/`); если есть только один — другой молча пропускается.
65+
6. Выбери со мной одну сессию и вели мне `claude-backup export <8-символьный-префикс> --output ./backups/`. По умолчанию создаются два файла: `<id>.md` (чистый диалог — только мои промпты и текстовые ответы Claude) и `<id>.full.md` (всё: tool-вызовы, tool-результаты И transcripts subagent'ов которые сессия порождала). Объясни когда использовать каждый.
6666
7. `open ./backups/<filename>.md` (macOS) или `xdg-open` (Linux) — посмотреть результат. Спроси что я думаю.
67-
8. Если хочу выгрузить всё — `claude-backup export-all --output ~/claude-backups`. Объясни что папки в результате зеркалят реальные рабочие директории (с вырезанным home-префиксом).
67+
8. Если хочу выгрузить всё — `claude-backup export-all --output ~/claude-backups`. Объясни что вывод сначала разделён по источнику — подпапки `code/` и `cowork/`, — а внутри каждой организован по проекту (Code зеркалит реальные рабочие директории, Cowork использует дружелюбный кодноим типа `beautiful-charming-curie` который Cowork сам генерирует).
6868
6969
Если команда выдаёт ошибку — помоги отладить, не вываливай готовый фикс. Частые проблемы:
70-
- `~/.claude/projects/` отсутствует → я ещё не пользовался Claude Code на этой машине
70+
- "Claude data not found" → я ещё не пользовался ни Claude Code, ни Cowork на этой машине
7171
- `pip: command not found` → попробовать `python3 -m pip`
7272
- `command not found: claude-backup` после установки → PATH, см. шаг 3
7373
- ошибка "externally-managed-environment" от pip → `pip3 install --user --break-system-packages -e .` или venv

QUICKSTART.md

Lines changed: 27 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
## What this tool does
1111

12-
Claude Code stores every conversation on your computer in a folder called `~/.claude/projects/`. Those files are in a format (`.jsonl`) that's hard to read. **`claude-backup`** turns them into nice, readable Markdown files you can open in any text editor, search, or archive.
12+
Claude Code and Claude Cowork (the local-agent desktop app) both store every conversation on your computer in `~/.claude/projects/` and `~/Library/Application Support/Claude/local-agent-mode-sessions/` respectively. Those files are in a format (`.jsonl`) that's hard to read. **`claude-backup`** finds both, walks any subagents they spawned, and turns the lot into nice, readable Markdown files you can open in any text editor, search, or archive.
1313

1414
---
1515

@@ -51,14 +51,14 @@ That's it. You can now run `claude-backup` from any folder.
5151
claude-backup list
5252
```
5353

54-
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+
You'll see a table of every conversation on your machine — across **both** Claude Code and Claude Cowork. The Source column tells you which app it came from. The "First Prompt / Title" column shows the AI-generated session title when Claude recorded one, and falls back to your literal first prompt otherwise:
5555

5656
```
57-
Project Session First Prompt / Title Msgs Created
58-
──────────────── ──────── ──────────────────────────────────────────── ──── ───────────────────
59-
my-webapp abc12345 Fix the login bug 42 2026-05-07T10:42:00
60-
my-webapp def45678 Add dark mode toggle 18 2026-05-06T14:00:00
61-
notes-app ghi78901 Refactor parser for nested blocks 7 2026-05-04T09:15:00
57+
Source Project Session First Prompt / Title Msgs Created
58+
────── ──────────────────────── ──────── ──────────────────────────────────────────── ──── ───────────────────
59+
Code my-webapp abc12345 Fix the login bug 42 2026-05-07T10:42:00
60+
Code my-webapp def45678 Add dark mode toggle 18 2026-05-06T14:00:00
61+
Cowork beautiful-charming-curie ghi78901 Q2 results slide deck 88 2026-05-04T09:15:00
6262
```
6363

6464
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.
@@ -85,7 +85,7 @@ Exported: backups/2026-05-07--abc12345-...full.md
8585
| File | What's inside | When to use |
8686
|------|---------------|-------------|
8787
| `2026-05-07--abc12345-….md` | The conversation: your prompts + Claude's text replies, nothing else | Re-reading later, archiving, sharing |
88-
| `2026-05-07--abc12345-….full.md` | Everything: every tool call, every shell command, every internal reasoning step | Debugging or auditing what the agent actually did |
88+
| `2026-05-07--abc12345-….full.md` | Everything: every tool call, every shell command, every internal reasoning step, **plus full transcripts of any subagents the session spawned** | Debugging or auditing what the agent actually did |
8989

9090
Open the `.md` file in any text editor — that's the readable one. It looks like this:
9191

@@ -140,33 +140,42 @@ claude-backup export-all --output ./backups/ # both files per
140140
claude-backup export-all --output ./backups/ --mode minimal # only the clean .md files
141141
```
142142

143-
The backup tree mirrors the real directories where you ran Claude Code (with your home prefix stripped). For example:
143+
The backup tree is split by source first, then mirrors how each app organises sessions. For example:
144144

145145
```
146146
backups/
147-
├── Documents/Claude/
148-
│ ├── 2026-04-22--<id>.md
149-
│ └── 2026-05-07--<id>.md
150-
└── code/some-project/
151-
└── 2026-04-10--<id>.md
147+
├── code/ ← Claude Code sessions, mirroring your real working dirs
148+
│ └── Documents/Claude/
149+
│ ├── 2026-04-22--<id>.md
150+
│ └── 2026-05-07--<id>.md
151+
└── cowork/ ← Claude Cowork sessions, by friendly codename
152+
├── beautiful-charming-curie/
153+
│ └── 2026-04-06--<id>.md
154+
└── upbeat-epic-feynman/
155+
└── 2026-04-20--<id>.md
152156
```
153157

154-
You now have a complete Markdown archive of your Claude Code history, organised the way your projects are organised.
158+
You now have a complete Markdown archive of every Claude conversation across both apps.
155159

156160
---
157161

158162
## Common questions
159163

160164
**Where does it look for my conversations?**
161165

162-
Default: `~/.claude/projects/` on macOS/Linux, `C:\Users\YourName\.claude\projects\` on Windows (WSL path: `/mnt/c/Users/YourName/.claude/projects/`).
166+
Two places, both auto-detected:
167+
- **Claude Code:** `~/.claude/projects/` (Windows/WSL: `/mnt/c/Users/YourName/.claude/projects/`)
168+
- **Claude Cowork:** `~/Library/Application Support/Claude/local-agent-mode-sessions/` (macOS only)
169+
170+
If only one exists, the tool just uses that one. No flag needed.
163171

164172
**Can I point it at a different folder?**
165173

166-
Yes — use `--claude-home`:
174+
Yes — each source has its own override:
167175

168176
```bash
169-
claude-backup --claude-home /some/other/path list
177+
claude-backup --claude-home /some/other/code-path list
178+
claude-backup --cowork-home /some/other/cowork-path list
170179
```
171180

172181
**Does it modify or delete anything?**

0 commit comments

Comments
 (0)