claude-code-sessions 0.16.5__tar.gz → 0.18.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/LICENSE +21 -21
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/PKG-INFO +294 -12
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/README.md +293 -11
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions.egg-info/PKG-INFO +294 -12
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions.egg-info/SOURCES.txt +4 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions.py +5973 -265
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions_gui.py +337 -109
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/pyproject.toml +50 -50
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_alignment.py +144 -144
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_anonymize.py +140 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_cli.py +172 -172
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_containment.py +71 -71
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_converge.py +2183 -1
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_discovery.py +48 -48
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_encoding.py +41 -41
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_engine.py +274 -274
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_golden.py +18 -18
- claude_code_sessions-0.18.0/tests/test_gui_dpi.py +171 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_gui_models.py +292 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_helpers.py +39 -39
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_journal.py +87 -87
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_journal_reroot.py +42 -0
- claude_code_sessions-0.18.0/tests/test_lineage.py +1092 -0
- claude_code_sessions-0.18.0/tests/test_realign.py +1830 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_rows.py +73 -73
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_scaffold.py +18 -18
- claude_code_sessions-0.18.0/tests/test_split_rows.py +654 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_sync.py +2140 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_transcripts.py +24 -24
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_undo.py +55 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions.egg-info/dependency_links.txt +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions.egg-info/entry_points.txt +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/claude_code_sessions.egg-info/top_level.txt +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/setup.cfg +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_commands.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_data_root.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_duplicate_transcripts.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_gui_destination.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_gui_env_rebuild.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_plan_move.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_recover.py +0 -0
- {claude_code_sessions-0.16.5 → claude_code_sessions-0.18.0}/tests/test_retitle.py +0 -0
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Craig Stoller
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Craig Stoller
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: claude-code-sessions
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.18.0
|
|
4
4
|
Summary: Unofficial tool for Claude Code sessions on disk: make a session visible under your other Claude account on the same machine, or move one between project folders. Command line or GUI. Journaled, reversible, fails closed.
|
|
5
5
|
Author: Craig Stoller
|
|
6
6
|
License: MIT
|
|
@@ -157,7 +157,7 @@ read. See `docs/internals.md`, RULING 7.
|
|
|
157
157
|
|
|
158
158
|
## Before any move: close the Claude app.
|
|
159
159
|
|
|
160
|
-
`move`, `undo`, `recover`, `repoint --apply`, `new-row --apply`, and every mutating `sync`
|
|
160
|
+
`move`, `undo`, `recover`, `repoint --apply`, `new-row --apply`, `realign --apply`, and every mutating `sync`
|
|
161
161
|
route (`--apply`, `undo` of a completed sync, `recover --back` on a stuck one) all refuse
|
|
162
162
|
while they can see the Claude desktop app running - whoever the identity files currently say
|
|
163
163
|
is signed in. That includes `undo` of a completed `repoint` or `new-row`, and `recover` on an
|
|
@@ -183,7 +183,7 @@ itself, and the guard counts it - if a refusal names that process, fully exit th
|
|
|
183
183
|
|
|
184
184
|
## Usage
|
|
185
185
|
|
|
186
|
-
|
|
186
|
+
Thirteen commands. All mutating commands default to a dry run; add `--apply` to execute.
|
|
187
187
|
(`trust-signed-helper` is the opt-in described above; it changes a setting, not your
|
|
188
188
|
sessions.)
|
|
189
189
|
|
|
@@ -204,8 +204,9 @@ claude-code-sessions list gate
|
|
|
204
204
|
```
|
|
205
205
|
|
|
206
206
|
**`doctor`** - read-only health report (stale locks, unresolved operations, orphaned rows,
|
|
207
|
-
encoding-scheme ambiguity, a synthesized row that has since vanished,
|
|
208
|
-
account's sidebar points at**
|
|
207
|
+
encoding-scheme ambiguity, a synthesized row that has since vanished, **conversations no
|
|
208
|
+
account's sidebar points at**, and **conversations whose accounts open different copies of one
|
|
209
|
+
transcript**):
|
|
209
210
|
|
|
210
211
|
```
|
|
211
212
|
claude-code-sessions doctor
|
|
@@ -219,6 +220,30 @@ Resuming a session while signed into a different account repoints its row, which
|
|
|
219
220
|
conversation you were in an hour ago reachable from no sidebar at all. That is what this
|
|
220
221
|
ranking is for, and `repoint` is how you put it back.
|
|
221
222
|
|
|
223
|
+
The copies check covers a case every other number misses. A conversation's transcript can end
|
|
224
|
+
up in two project folders, usually after a session moves into a second worktree. Each account's
|
|
225
|
+
row names a folder through its `cwd`, and the app opens the copy in that folder, even a stale
|
|
226
|
+
one. So one sidebar can show a conversation as it was weeks ago while another shows it today,
|
|
227
|
+
and `alignment` still counts it complete. `doctor` lists each such conversation, which
|
|
228
|
+
copy each account's row opens, and how each pair of copies relates: one behind the other (one
|
|
229
|
+
history, one copy stopped growing), the same conversation, byte-identical, or diverged (each
|
|
230
|
+
holds turns the other lacks). It compares the bytes first and then reads what lies past the
|
|
231
|
+
bytes two copies share, because the app writes bookkeeping records (`tools-used` when it opens
|
|
232
|
+
a copy, `cost-state` when it quits) to whichever copy it has open, the stale one included. A
|
|
233
|
+
copy ahead only by those records holds the same conversation; a stale copy the app has opened
|
|
234
|
+
and quit is still behind, although its bytes no longer match. Any other record type counts as
|
|
235
|
+
conversation. `doctor` exits 1 when an unarchived row opens an older or a diverged copy.
|
|
236
|
+
Identical copies and copies that differ only in bookkeeping are listed and do not change the
|
|
237
|
+
exit code. Neither does a row whose folder holds no copy at all. A row whose `cwd` names a main repository while the transcript sits in
|
|
238
|
+
one of its worktree folders is the app's normal placement, not a fault.
|
|
239
|
+
|
|
240
|
+
Deleting the stale copy is a catch-up, not a fix. On one conversation, measured on Desktop
|
|
241
|
+
5.11492.5, opening a row whose folder held no copy made the app copy the transcript back into
|
|
242
|
+
that folder, so the split returns once the conversation is worked from one account and opened
|
|
243
|
+
from another. For the same reason `doctor` also lists, without counting them, conversations with
|
|
244
|
+
a single copy and a row whose folder holds none: opening that row starts a split. `realign`
|
|
245
|
+
(below) is the repair for both.
|
|
246
|
+
|
|
222
247
|
**`alignment`** - read-only scoreboard: how close your accounts are to holding one shared
|
|
223
248
|
history. `doctor` answers "is anything broken"; this answers "how far apart are my sidebars,
|
|
224
249
|
and which way is it moving":
|
|
@@ -237,8 +262,10 @@ Two of those actively trade against each other: making a conversation reachable
|
|
|
237
262
|
both halves of a disagreeing pair in every sidebar under one name, which is a direct hit to
|
|
238
263
|
*distinguishable*. A single "aligned: yes/no" would hide exactly the decision you have to make.
|
|
239
264
|
|
|
240
|
-
It reads row files and transcript **filenames** only - no transcript content - so it
|
|
241
|
-
on a store with gigabytes behind it.
|
|
265
|
+
It reads row files and transcript **filenames and sizes** only - no transcript content - so it
|
|
266
|
+
stays fast on a store with gigabytes behind it. That is why its line on conversations whose
|
|
267
|
+
accounts open different copies only counts them, and how many differ in length; telling a stale
|
|
268
|
+
copy from a diverged one means reading both, which `doctor` does. **It always exits 0** when it could produce the report. It
|
|
242
269
|
is a scoreboard, not a check: these numbers stay non-zero for as long as the work takes, and a
|
|
243
270
|
command that exits 1 for months trains you to stop reading it.
|
|
244
271
|
|
|
@@ -423,6 +450,22 @@ is always a preview will misread `sync --apply --json`.
|
|
|
423
450
|
grants** across the account boundary unchanged. The permission half is the more
|
|
424
451
|
security-relevant of the two: use `--verbatim` only when you actually want the second account
|
|
425
452
|
to inherit what the first one had allowed.
|
|
453
|
+
- **A row's link to its parent is translated, not copied.** A row `sync` adds carries the same
|
|
454
|
+
translated link and chain that `converge` writes (see `converge`, below), or none, and the plan
|
|
455
|
+
prints the same `links :` and `chains :` lines. A refresh replaces the whole row, link
|
|
456
|
+
included, so the destination's own link is dropped or translated, never merged. A refresh that
|
|
457
|
+
drops it or points it at another row says so, one line per row (`link : local_c1 loses its
|
|
458
|
+
link`, `link : local_c1 now links to another row`, and `chain :` for the chain), and the
|
|
459
|
+
fields line leaves the link out so it is reported once. One exception: a destination link that
|
|
460
|
+
already names the same row and `taskId` is kept as it is. A refresh whose bytes already match
|
|
461
|
+
the destination's row is reported unchanged, unless the source row carries a link or a chain:
|
|
462
|
+
then the link is translated first, and the row is written when the translated link differs, so
|
|
463
|
+
a copy that names a row in the source account is corrected. (Under `--newer-only` such a row
|
|
464
|
+
meets the age holds first, like any refresh.) In the window the sync pane shows the
|
|
465
|
+
same lines. An apply that ends with nothing to write says "Nothing to copy: the destination
|
|
466
|
+
already holds these rows" and leaves Undo as it was.
|
|
467
|
+
**`--verbatim` copies links as they are**, so a link may name a row that does not exist in the
|
|
468
|
+
destination. Such an add is counted: `links : 2 copied verbatim (not translated)`.
|
|
426
469
|
- **It needs the app closed too, the same as `move`, `undo`, and `recover` - regardless of which
|
|
427
470
|
file resolved the signed-in account.** `sync` only ever writes the store you are *not* signed
|
|
428
471
|
into, and re-checks that at the moment it writes, not just when it planned; that re-check
|
|
@@ -579,6 +622,154 @@ stopped being redundant is presence it leaves alone. `doctor`'s vanished-row che
|
|
|
579
622
|
converge-created rows the same way it watches `new-row`'s, with the same journal-retention
|
|
580
623
|
window.
|
|
581
624
|
|
|
625
|
+
**Side sessions keep their parent.** A side session's row names its parent's row (`spawnedFrom`),
|
|
626
|
+
and a row deep in a chain of them names the chain's first row (`startChain`). Both name a row by
|
|
627
|
+
its id in the same account, so a copy would point at a row the other account does not have.
|
|
628
|
+
`converge` and `sync` therefore write them translated. The link becomes
|
|
629
|
+
`{"sessionId": <that account's own row for the parent>, "taskId": <copied unchanged>}`, and the
|
|
630
|
+
chain becomes `{"firstSessionId": <that account's own row for the root>, "depth": <copied>}`.
|
|
631
|
+
Everything else in the source link (`title`, `sideSession`, `name`, `sharedFolder`, `wakeParent`,
|
|
632
|
+
`pendingPop` and any key this tool has not seen) is left behind and recorded. The `taskId` is not
|
|
633
|
+
optional: on the one side session measured per link shape, a link without it hid the child from
|
|
634
|
+
the sidebar, and a link with it nested the child under its parent. Only the link shapes that were
|
|
635
|
+
measured are carried: an app-written side-session link, the older `{sessionId, taskId, title}`,
|
|
636
|
+
and this tool's own output, so a carried link can be carried again.
|
|
637
|
+
|
|
638
|
+
The row is still created when its link is left out, and the plan says why. A link is left out
|
|
639
|
+
when the holders disagree on the parent or on `taskId`; when it names the conversation itself;
|
|
640
|
+
when the parent's transcript is gone; when that account has no row for the parent, or the
|
|
641
|
+
parent's own row is held in this plan, or its row there opens another conversation; when the
|
|
642
|
+
link's shape is not one that was measured; or when it would close a cycle. A link is written only
|
|
643
|
+
to a row that will exist, including a parent created in the same run, which is written first.
|
|
644
|
+
The plan reports it:
|
|
645
|
+
|
|
646
|
+
```
|
|
647
|
+
links : 4 to carry, 1 left out (holders disagree on the parent 1)
|
|
648
|
+
chains : 2 to carry
|
|
649
|
+
cycles : 1 already present, left as they are
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
Each part prints only when its count is not zero, the most frequent reason first. A row whose
|
|
653
|
+
link was left out carries `[link: <reason>]` on its own line. The apply resolves every link
|
|
654
|
+
again under the lock, against the store as it then stands, and its last lines say what changed
|
|
655
|
+
since the plan: `links : 4 carried, 1 left out (...); since the plan: 1 changed, 1 gained`.
|
|
656
|
+
`changed` and `dropped` count links the plan had, `gained` one it did not. With `--verbose` the
|
|
657
|
+
apply also lists them, one line per written row whose link or chain was left out or changed
|
|
658
|
+
since the plan, with its account:
|
|
659
|
+
|
|
660
|
+
```
|
|
661
|
+
local_c3 -> bob@example.com (cccc1111/dddd2222) [link: the parent's own row is held in this plan; dropped since the plan]
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
The journal records the final link per row, and recovery never resolves again. It writes the
|
|
665
|
+
journaled bytes, skips a row (`parent_not_written`) whose planned parent it did not write, and
|
|
666
|
+
skips one (`parent_changed`) whose parent's row is gone or now opens another conversation.
|
|
667
|
+
`recover --forward` names each row it skipped that way, with its reason, in the `skipped :` line
|
|
668
|
+
`converge` prints for a skipped row.
|
|
669
|
+
|
|
670
|
+
`undo` can leave a link dangling. When a row it created has become the last pointer to its
|
|
671
|
+
conversation, `undo` keeps it, while it still removes the parent row the same operation created.
|
|
672
|
+
It says so, for `undo` of a `converge`, a `sync` or a `new-row`, and for `recover --back` and a
|
|
673
|
+
finished `recover --forward`:
|
|
674
|
+
|
|
675
|
+
```
|
|
676
|
+
link left dangling: local_c1 (its parent's row was removed)
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
A child whose parent's row is missing is listed on its own and opens, which was measured. A
|
|
680
|
+
chain root's row that is missing is reported the same way ("its chain root's row"), but how the
|
|
681
|
+
app shows that was not measured. `link redirected: ... (its parent's row now opens another
|
|
682
|
+
conversation)` names a link whose target row survives and now opens a different conversation,
|
|
683
|
+
and `links not checked: N could not be read` counts what the report could not read. The report
|
|
684
|
+
covers rows that link to a row the command removed, and for `recover --forward` the operation's
|
|
685
|
+
own targets. It is not a check of every link in the store. A reversal cut short and run again
|
|
686
|
+
counts a row the first run removed as removed, so a link to it is still named. The window's Undo
|
|
687
|
+
shows the same lines, for a copy and a converge alike.
|
|
688
|
+
|
|
689
|
+
**`realign`** - point every account's row of a split conversation at the folder holding its
|
|
690
|
+
live transcript copy:
|
|
691
|
+
|
|
692
|
+
```
|
|
693
|
+
claude-code-sessions realign
|
|
694
|
+
claude-code-sessions realign --apply
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
These are the split rows `doctor` reports. A probe on Desktop 5.11492.5, run on one plain and
|
|
698
|
+
one worktree conversation, found that a row's `cwd` alone decides which copy it opens; that the
|
|
699
|
+
app rewrites the row's `folderPlace` to match `cwd`, and never writes `cwd` back; and that a
|
|
700
|
+
turn typed after `cwd` moved runs in the new folder, in the same transcript. So `realign`
|
|
701
|
+
rewrites `cwd`, and `folderPlace.cwd` and `folderPlace.realPath` where the row has a
|
|
702
|
+
`folderPlace` (it never adds one), and leaves every other key alone, including `originCwd` and
|
|
703
|
+
the title. The rewritten rows then open the live copy. No row opens the stale copy any more, so
|
|
704
|
+
it moves into the operation's journal, with its sidecar folder, where `undo` can put it back
|
|
705
|
+
and `doctor` lists it. Without that step, `move`, `repoint`, `new-row` and `converge` would
|
|
706
|
+
keep refusing the conversation for its duplicated transcript. A copy that no row opened even
|
|
707
|
+
before `realign` stays where it is: that is the duplicated-transcript case, which `realign` did
|
|
708
|
+
not cause.
|
|
709
|
+
|
|
710
|
+
By default it plans conversations with a copy behind the live one, and rows whose folder holds
|
|
711
|
+
no copy. Copies that hold the same conversation (byte-identical, or different only in
|
|
712
|
+
bookkeeping records) are realigned only with `--include-identical`, onto the copy the most
|
|
713
|
+
recently active row opens. `--only` narrows to one conversation, resolved the way `converge
|
|
714
|
+
--only` is. A conversation is **held**, with the reason printed, when:
|
|
715
|
+
|
|
716
|
+
- its copies have diverged (each holds turns the other lacks), so which history to keep is
|
|
717
|
+
your decision;
|
|
718
|
+
- a copy no row opens holds turns the live copy lacks;
|
|
719
|
+
- a row to change has a worktree link (`worktreePath` or `worktreeName`). In the probe, moving
|
|
720
|
+
such a row's path keys either detached it from its worktree or left it unable to start;
|
|
721
|
+
- the live copy is reached only through the worktree placement, sits in a legacy-encoded
|
|
722
|
+
folder, or has no path on record that encodes to its folder;
|
|
723
|
+
- the paths that reach the live copy's folder disagree, or its directory no longer exists;
|
|
724
|
+
- an unfinished operation involves it, or anything about it changed between plan and apply.
|
|
725
|
+
|
|
726
|
+
`--apply` needs the desktop app fully closed, re-plans under its lock and writes only the
|
|
727
|
+
conversations whose rows, copies and target are unchanged, prints any it held at that point,
|
|
728
|
+
and exits 3 when any conversation was held. An interrupted run recovers in both directions:
|
|
729
|
+
`recover --forward` finishes from the journal, and is offered only when every row and copy it
|
|
730
|
+
would touch is as the journal expects; `recover --back` puts each conversation's copies and
|
|
731
|
+
rows back, and keeps realign's placement for a conversation whose copy cannot go back (its
|
|
732
|
+
place is taken, for instance), saying why. `undo` works per conversation. It puts back only
|
|
733
|
+
the keys realign changed, keeps whatever the app wrote to other keys since, and refuses a
|
|
734
|
+
conversation, naming the reason, when its rows no longer hold what realign wrote, now open
|
|
735
|
+
another conversation, were written by a later operation, or when the conversation has gained
|
|
736
|
+
turns since (bookkeeping records do not count). The other conversations go ahead, and a later
|
|
737
|
+
`undo --apply` retries the refused ones.
|
|
738
|
+
|
|
739
|
+
A copy realign sets aside stays in its journal until `undo` puts it back or `realign --release`
|
|
740
|
+
sends it to the Recycle Bin; `doctor` lists every copy held. Once a conversation has gained
|
|
741
|
+
turns, undo refuses it for good, which is what release is for:
|
|
742
|
+
|
|
743
|
+
```
|
|
744
|
+
claude-code-sessions realign --release
|
|
745
|
+
claude-code-sessions realign --release --apply
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
A copy is released only when every row of its conversation now opens one copy, that copy holds
|
|
749
|
+
the set-aside copy's whole conversation (the bookkeeping records `tools-used` and `cost-state`
|
|
750
|
+
aside, which carry no conversation), and its sidecar folder holds every file the set-aside
|
|
751
|
+
copy's does, with the same content: a copy that holds anything else the live one lacks stays in
|
|
752
|
+
the journal, with the reason printed. It goes to the Windows Recycle Bin, and the step is built
|
|
753
|
+
so that a permanent delete cannot happen silently. A shell that cannot recycle a file destroys
|
|
754
|
+
it instead. So release refuses a bin turned off (by you or by policy), one whose capacity the
|
|
755
|
+
registry does not record, one without room for the whole run without pushing out your older
|
|
756
|
+
deleted files (asked again just before each move), and a path too long for the shell, and it
|
|
757
|
+
asks Windows to warn rather than delete in any case it cannot see. After each move it checks
|
|
758
|
+
that a new bin record names the file, with its size and its contents present. It needs the
|
|
759
|
+
desktop app closed, since its checks read the rows and transcripts the app rewrites. A copy
|
|
760
|
+
whose release is interrupted is finished by the next run, and only after the same checks; once
|
|
761
|
+
its transcript is in the bin, only while the live copy still starts with everything it held
|
|
762
|
+
when the release began. One gap is stated rather than closed: a case the checks cannot see
|
|
763
|
+
rests on Windows' warning, whose behaviour beside the silent flags release uses is untested. Once
|
|
764
|
+
every copy of an operation is released, the journal ages the operation out like any other;
|
|
765
|
+
`undo` refuses a conversation whose copy was released or is part-way through release, and
|
|
766
|
+
`--json` gives each copy's outcome, a failed run included.
|
|
767
|
+
|
|
768
|
+
A released copy can be restored from the Recycle Bin by hand until the bin is emptied or
|
|
769
|
+
Windows clears it to make room. It comes back to its journal folder, not to its project folder;
|
|
770
|
+
the operation's record names where each part went. Windows only, like every other store mutation
|
|
771
|
+
here.
|
|
772
|
+
|
|
582
773
|
## Safety design
|
|
583
774
|
|
|
584
775
|
- **Dry-run by default.** Every mutating command prints its plan and does nothing until you
|
|
@@ -620,13 +811,20 @@ window.
|
|
|
620
811
|
| Platform | Status | Mutations |
|
|
621
812
|
|---|---|---|
|
|
622
813
|
| Windows 11 + Claude Desktop | verified 2026-07-31; sync end-to-end incl. live continuation 2026-08-03; sync-undo drift refusal live 2026-08-04 | read-only + mutations |
|
|
623
|
-
| Windows 11 + Claude Desktop 2.42304.2 (user data moved to `%LOCALAPPDATA%\Claude-Data`) | from 0.16.3: read-only paths probed 2026-10-19 against the moved store. 0.16.2 and earlier find no store | read-only + mutations, `--apply`
|
|
814
|
+
| Windows 11 + Claude Desktop 2.42304.2 (user data moved to `%LOCALAPPDATA%\Claude-Data`) | from 0.16.3: read-only paths probed 2026-10-19 against the moved store. 0.16.2 and earlier find no store where the app moved the folder, and read the old copy where it copied the folder and left the original in place | read-only + mutations, `--apply` never run on this build (the app updated to 3.x first) |
|
|
815
|
+
| Windows 11 + Claude Desktop 3.6556.2 (user data still in `%LOCALAPPDATA%\Claude-Data`) | on 0.16.5: read-only paths and `converge --apply` verified 2026-10-23, the apply with the app closed and the browser helper running. Needs 0.16.3 or later to find the store | read-only + mutations |
|
|
816
|
+
| Windows 11 + Claude Desktop 4.4212.0 (user data still in `%LOCALAPPDATA%\Claude-Data`) | on 0.16.5: `doctor`, `alignment` and `converge --apply` verified 2026-11-01, the apply with the app closed and the browser helper running. Needs 0.16.3 or later to find the store | read-only + mutations |
|
|
817
|
+
| Windows 11 + Claude Desktop 5.1231.0 (user data still in `%LOCALAPPDATA%\Claude-Data`) | on 0.16.5: `doctor` and `alignment` verified read-only 2026-11-10. Needs 0.16.3 or later to find the store | read-only + mutations, `--apply` not yet run on this build |
|
|
818
|
+
| Windows 11 + Claude Desktop 6.6395.0 (user data still in `%LOCALAPPDATA%\Claude-Data`) | from 0.17.0: `doctor` and `realign --apply` verified 2026-11-17, the apply with the app closed; after the app reopened, `doctor` and a fresh `realign` plan found every rewritten row opening the live copy and no set-aside copy back in its old folder. From 0.18.0: `converge --apply` with carried links verified 2026-11-19, the apply with the app closed; the app nested both children opened, and after a reopen every carried link and chain read back as written. Needs 0.16.3 or later to find the store | read-only + mutations |
|
|
624
819
|
| macOS / Linux desktop | unverified | **read-only only** - desktop-store mutations refuse, with no override |
|
|
625
820
|
| CLI-only sessions (any OS) | transcript layout verified | mutations allowed via `--transcript-only` |
|
|
626
821
|
|
|
627
|
-
The dates are measurements against specific builds
|
|
628
|
-
|
|
629
|
-
|
|
822
|
+
The dates are measurements against specific builds of the MSIX that Anthropic signs and
|
|
823
|
+
distributes itself from claude.ai - most recently Claude Desktop 6.6395.0.0 with Claude Code
|
|
824
|
+
CLI 2.1.326 for `doctor` and the last two `--apply` runs, a `realign` on 2026-11-17 and a
|
|
825
|
+
`converge` on 2026-11-19. The Microsoft Store build is a separate package, `AnthropicPBC.Claude_<id>`.
|
|
826
|
+
This tool does not look in that package's folder and has never been run against it.
|
|
827
|
+
On 2026-10-14 the
|
|
630
828
|
read-only paths were verified against a real Desktop 2.x store, build 2.37337.1.0 (`list`,
|
|
631
829
|
`doctor`, `alignment`, `recover` without `--apply`, and a `converge` dry run): the row format
|
|
632
830
|
had only gained keys, and every row this tool had written under 1.x was still present, some
|
|
@@ -647,6 +845,30 @@ the move. 0.16.4 reads those paths under the moved store: `doctor` checks
|
|
|
647
845
|
the rows where they now are, and `undo` and `recover` treat such an operation as they did
|
|
648
846
|
before the move. A row in a store the tool cannot read at all is listed by `doctor` apart, not
|
|
649
847
|
counted in its exit code, and `undo` refuses it.
|
|
848
|
+
On 2026-10-23, under 3.6556.2.0, the data folder had not moved again, and rows written by the
|
|
849
|
+
3.x builds had only gained two keys. A `converge --apply` on 0.16.5 ran with the app closed while the browser
|
|
850
|
+
helper kept running, and the running-app guard excused the helper under the
|
|
851
|
+
`trust-signed-helper` opt-in. After the app restarted, every row the apply had written was
|
|
852
|
+
present and byte-identical to what it wrote, and `doctor` reported none vanished.
|
|
853
|
+
On 2026-11-01, under 4.4212.0.0, the data folder had not moved again. A `converge --apply` on
|
|
854
|
+
0.16.5 ran with the app closed and the browser helper running, and the guard excused the
|
|
855
|
+
helper as it had under 3.x. After the app restarted, every row the apply had written was
|
|
856
|
+
present and `doctor` reported none vanished. Within a few minutes the app had re-saved six of
|
|
857
|
+
those rows, and each had only gained keys. By 2026-11-02 the 4.x app had created 36 rows for
|
|
858
|
+
itself. None lacked a key that every older row carries, and four had gained one new key,
|
|
859
|
+
`isStarred`.
|
|
860
|
+
On 2026-11-10, under 5.1231.0.0, the data folder had not moved again, and `doctor` and
|
|
861
|
+
`alignment` on 0.16.5 found the store where 4.x left it. That build's release notes say
|
|
862
|
+
Windows 10 21H2 or later and Windows Server 2022 now keep the app's data in
|
|
863
|
+
`%LOCALAPPDATA%\Claude-Data` too, as the Windows 11 machine these measurements come from has
|
|
864
|
+
since 2.42304.2, so on those systems the move happens at 5.1231.0. If the folder layout there
|
|
865
|
+
matches that machine's, the same versions apply: 0.16.3 or later to find the store, 0.16.4 or
|
|
866
|
+
later for operations from before the move. The notes also say the Microsoft Store build keeps
|
|
867
|
+
its data where it was, and they mention moves that copied the folder instead of moving it.
|
|
868
|
+
Where such a copy leaves the old store in place, run this tool from an ordinary terminal: from
|
|
869
|
+
a shell the desktop app started, `%APPDATA%\Claude` is the app's view of its old folder, and
|
|
870
|
+
0.16.5 can read the old copy through it. Not measured here: a Windows 10 machine, a Microsoft
|
|
871
|
+
Store install, and an `--apply` under 5.1231.0.
|
|
650
872
|
The on-disk format has changed once already during this tool's own development; treat a
|
|
651
873
|
much newer build as unverified territory.
|
|
652
874
|
|
|
@@ -1007,7 +1229,9 @@ window into `journaled`/`completed`/`rolled_back`.
|
|
|
1007
1229
|
README, the window's checkbox and the command's help, says Chrome or Edge, since either can
|
|
1008
1230
|
launch the helper. Three constants left unused since the August anti-fabrication fix are gone.
|
|
1009
1231
|
- **0.16.3 finds the session store where Desktop 2.42304.2 moved it.** That build moved the
|
|
1010
|
-
app's whole user-data folder out of the Microsoft Store package
|
|
1232
|
+
app's whole user-data folder out of the Microsoft Store package (corrected 2026-11-10: out of
|
|
1233
|
+
the MSIX package Anthropic distributes itself, not the Microsoft Store build, whose data the
|
|
1234
|
+
5.1231.0 release notes say does not move), from
|
|
1011
1235
|
`%LOCALAPPDATA%\Packages\Claude_<pkg>\LocalCache\Roaming\Claude` to
|
|
1012
1236
|
`%LOCALAPPDATA%\Claude-Data\claude_<pkg>`, and left a 0-byte file in the old folder naming
|
|
1013
1237
|
the new one. 0.16.2 looked only in the old places, so `doctor` and `alignment` reported no
|
|
@@ -1058,6 +1282,64 @@ window into `journaled`/`completed`/`rolled_back`.
|
|
|
1058
1282
|
left every route refusing until a restart, or, when the app copied its data instead of moving
|
|
1059
1283
|
it, left the window writing into the old copy. A press whose store layout changed since its
|
|
1060
1284
|
plan now stops and replans before its next write.
|
|
1285
|
+
- **0.17.0 shows which copy of a transcript each account's row opens, and repairs it.** A
|
|
1286
|
+
conversation's transcript can end up in two project folders, and each account's row opens
|
|
1287
|
+
the copy in the folder its `cwd` names, so one sidebar can show a conversation as it was
|
|
1288
|
+
weeks ago while another shows it today. `doctor` now lists each such conversation, which copy
|
|
1289
|
+
each row opens, and how the copies relate, reading past the bookkeeping records the app
|
|
1290
|
+
writes to whichever copy it has open; it exits 1 when an unarchived row opens an older or a
|
|
1291
|
+
diverged copy. It also lists, without counting them, conversations with one copy and a row
|
|
1292
|
+
whose folder holds none, because opening such a row made the app copy the transcript into
|
|
1293
|
+
that folder (measured on Desktop 5.11492.5). The new `realign` command points those rows at
|
|
1294
|
+
the folder holding the live copy, by rewriting `cwd` and the `folderPlace` keys the app keeps
|
|
1295
|
+
in step with it, and moves the stale copy into its journal, where `undo` can put it back. It
|
|
1296
|
+
holds anything it cannot decide safely, with the reason: diverged copies, a row with a
|
|
1297
|
+
worktree link, a live copy whose folder is gone, and identical copies unless
|
|
1298
|
+
`--include-identical` is given. On the machine it was built on, the first apply realigned 43
|
|
1299
|
+
conversations (84 rows) and held 52; `doctor` then listed 26 split conversations where it
|
|
1300
|
+
had listed 30, and 26 waiting ones where it had listed 65. `realign --release` sends a
|
|
1301
|
+
set-aside copy to the Recycle Bin once every row of its conversation opens one copy and that
|
|
1302
|
+
copy holds everything the set-aside one did, sidecar files included. It refuses each case it
|
|
1303
|
+
can see in which Windows would delete the copy outright, and asks Windows to warn in any
|
|
1304
|
+
other; how that warning behaves beside the silent flags release passes is untested, and no
|
|
1305
|
+
`--release --apply` had run when this shipped. The window's health report counts the split
|
|
1306
|
+
conversations, the waiting ones and the copies realign holds. `realign` itself is CLI-only,
|
|
1307
|
+
and while one is the latest operation the window offers no undo.
|
|
1308
|
+
The window also declares system DPI awareness before it opens, on Windows with Tk 9.0, so
|
|
1309
|
+
at 250 % it draws its text and widgets at the display's resolution and at the size it had
|
|
1310
|
+
before, where it used to be a stretched bitmap. Every pixel constant goes through one factor,
|
|
1311
|
+
the process's DPI over 96. Verified at 250 % and in a faithful 100 % run, and every other
|
|
1312
|
+
GUI harness passes in an aware process. 150 %, a common laptop setting, is untested; Tk 8.6
|
|
1313
|
+
is unchanged.
|
|
1314
|
+
- **0.18.0 keeps a side session under its parent in every account.** A side session's row names
|
|
1315
|
+
its parent's row (`spawnedFrom`) and its chain's first row (`startChain`), each by an id that
|
|
1316
|
+
exists only in that account. `converge` used to write its rows without either, and `sync`
|
|
1317
|
+
copied both as they stood, so a copied link named a row the destination does not have. Both
|
|
1318
|
+
commands now write them translated to the destination's own rows, the link as `{sessionId,
|
|
1319
|
+
taskId}`. On the machine it was built on, probes found that the app hides a child whose link
|
|
1320
|
+
lacks `taskId` and nests it when the link has both keys, for the app's side-session links and
|
|
1321
|
+
for its older `{sessionId, taskId, title}` links, one candidate each. Only those measured
|
|
1322
|
+
shapes and this tool's own output are carried. Any other link is left out with its reason, as
|
|
1323
|
+
are the cases "Side sessions keep their parent" above lists: holders that disagree, a parent
|
|
1324
|
+
the account lacks, a link that would close a cycle. A parent created in the same run is
|
|
1325
|
+
written first. The apply resolves every link again under the lock, and the journal keeps the
|
|
1326
|
+
final link per row. Recovery never resolves again. When a pending row's parent was not
|
|
1327
|
+
written, or its row is gone or now opens another conversation, `converge` skips that row and
|
|
1328
|
+
`sync` stops offering to go forward. `undo` and
|
|
1329
|
+
`recover --back` remove children before their parents and report any link they leave
|
|
1330
|
+
dangling, or naming a row that now opens another conversation; the window's Undo shows the
|
|
1331
|
+
same lines. A
|
|
1332
|
+
`spawnedFrom` or `startChain` that is not an object, a null say, counts as no link. Before
|
|
1333
|
+
the release, a `converge --apply` on that machine created 20 rows and carried 20 links and 18
|
|
1334
|
+
chains. The app nested both children opened, one whose source link also carried
|
|
1335
|
+
`sharedFolder` and one with `userFork`, and after a reopen every carried link and chain read
|
|
1336
|
+
back as written. A child with the older link shape written by a release run, and a child
|
|
1337
|
+
`sync` added, have not been looked at in the app. `sync` now decodes its stores a second time
|
|
1338
|
+
for the links. On a store of about 3,000 rows (400 MB) its dry run took about 30% longer and
|
|
1339
|
+
peaked at 879 MB against 229 MB, and with `--update` at 1.13 GB against 452 MB. A fix is
|
|
1340
|
+
planned. `converge` recovery also keeps a row that landed before a hard kill: it records the
|
|
1341
|
+
row as written before re-checking anything, so `undo` still removes it, even after the app
|
|
1342
|
+
has rewritten it.
|
|
1061
1343
|
- Platform rows above move from "unverified" to "verified" as contributors confirm the store
|
|
1062
1344
|
paths and behavior on their own machines.
|
|
1063
1345
|
|