claude-code-sessions 0.9.0__tar.gz

claude_code_sessions-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craig Stoller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_code_sessions-0.9.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: claude-code-sessions
+Version: 0.9.0
+Summary: Unofficial CLI 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. Journaled, reversible, fails closed.
+Author: Craig Stoller
+License: MIT
+Project-URL: Homepage, https://github.com/craigstoller/claude-code-sessions
+Project-URL: Issues, https://github.com/craigstoller/claude-code-sessions/issues
+Project-URL: Companion post, https://github.com/craigstoller/claude-code-sessions/blob/main/docs/the-session-that-synced-itself.md
+Keywords: claude,claude-code,claude-desktop,sessions,session,sync,move,cli,anthropic
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# claude-code-sessions
+
+See your Claude Code sessions under your other Claude account on the same machine — and move
+sessions between project folders. Journaled, reversible, fails closed.
+
+> **Unofficial.** Not affiliated with Anthropic. Reverse-engineered on-disk formats; fails
+> closed when it sees anything it doesn't recognize.
+>
+> **Not to be confused with** `claude-code-sessions\` — the folder *Claude Desktop* keeps your
+> per-account session list in, which this tool reads. This tool's own bookkeeping lives in
+> `~/.claude-code-journal/` and is safe to delete.
+
+**Companion read:** [The session that synced itself](https://github.com/craigstoller/claude-code-sessions/blob/main/docs/the-session-that-synced-itself.md)
+— what Claude Desktop actually keeps on disk, and why this tool is built out of refusals.
+
+## The problem
+
+**Claude Desktop files its session list per account.** Switch logins and the sessions you
+started under the other one disappear from the sidebar. They are not gone: the conversation
+itself is a single shared file carrying no account identity at all, sitting untouched on your
+disk. Only the *listing row* — the sidebar entry pointing at it — is private to each login, and
+the app reads only the folder belonging to the account you are signed into right now. `sync`
+copies that row into your other account's store, so the session shows up there too.
+
+**Separately, every session is filed under the directory it was started in**, and there is no
+official way to move one afterwards — a session begun in the wrong folder is stuck there.
+`move` relocates the transcript and every listing row that points at it, verifying each side
+before touching the other, so the session reopens cleanly in its new home.
+
+## Install
+
+```
+pipx install claude-code-sessions
+```
+
+This installs two identical commands: `claude-code-sessions`, and `ccs` as a shorter
+alias for everyday use. Examples below use the long form; `ccs doctor` is the same
+thing.
+
+Or download `claude_code_sessions.py` and run it directly — the runtime has no dependencies beyond
+the Python 3.9+ standard library:
+
+```
+python claude_code_sessions.py --help
+```
+
+## Before any move: close the Claude app.
+
+`move`, `undo`, `recover`, and every mutating `sync` route (`--apply`, `undo` of a completed
+sync, `recover --back` on a stuck one) all refuse while they can see the Claude desktop app
+running — whoever the identity files currently say is signed in. Closing the app first avoids
+the refusal and guarantees nothing is actively appending to the sidebar rows you're about to
+touch. A running Claude Code CLI session does **not** count: it's recognised by its own
+install path and excluded from the check, so an open `claude` session never blocks any of this.
+(For `move` specifically, a running CLI session *can* still be writing the transcript being
+relocated — the transcript-freshness check and the last-instant content re-verification cover
+that case; see Safety design.)
+If `~/.claude.json` (the CLI's identity file) and the desktop app's `config.json` disagree
+about which account is signed in, `sync` refuses to even plan — re-authenticate the CLI (run
+`claude`, then `/login`) as the account you use, or switch the desktop app to it, so the two
+files agree. Signing into the desktop app does **not** refresh `~/.claude.json`. A refused
+`sync --apply` (desktop app running) refuses **before anything is journaled** — no lock file,
+no op directory — so there's nothing left behind for `doctor` to flag or `recover` to clean up;
+just close the app and re-run. One measured wrinkle: the desktop ships a helper for its Chrome
+extension (`chrome-native-host.exe`) that can outlive the app itself, and the guard counts it —
+if a refusal names that process, fully exit Chrome too (the refusal always names what it saw).
+
+## Usage
+
+Six commands. All mutating commands default to a dry run; add `--apply` to execute.
+
+**`list`** — inventory sessions, optionally filtered by a search term:
+
+```
+claude-code-sessions list gate
+```
+
+**`doctor`** — read-only health report (stale locks, unresolved operations, orphaned rows,
+encoding-scheme ambiguity):
+
+```
+claude-code-sessions doctor
+```
+
+**`move`** — relocate a session to another project folder:
+
+```
+claude-code-sessions move 3c3c3eae-0e2f-4be4-9fba-407f06816f79 "C:\path\to\project" --apply
+```
+
+Get the full id from `claude-code-sessions list --full`.
+
+**`undo`** — reverse the most recent completed operation:
+
+```
+claude-code-sessions undo --apply
+```
+
+**`recover`** — resolve an operation left non-terminal by a crash or interruption:
+
+```
+claude-code-sessions recover
+```
+
+**`sync`** — copy a session's sidebar **listing row** from your signed-in account into your
+*other* Claude account's store on this machine, so it shows up in that account's sidebar too:
+
+```
+claude-code-sessions sync --apply
+```
+
+There is only one copy of the conversation itself — shared, and carrying no account identity —
+so a synced session opens and resumes normally under the other account. Without `--to`, the
+destination must be unambiguous: exactly one other account store on the machine, or `--to
+<substring>` naming one of several by its account id, org id, **store path**, or — when it can be
+recovered, see below — its email. The path is matchable because ids alone are not
+always enough — Windows exposes two store roots (the MSIX package path and the classic
+`%APPDATA%\Claude` path), and a machine that migrated between installers can hold the same
+account under both, in which case the path is the only thing that tells the two copies apart.
+Both "which store did you mean" refusals print the full path beside each candidate. `sync` refuses outright if it
+cannot tell which account is signed in — either because neither `~/.claude.json` nor
+`config.json` names one, or because the two disagree about which account it is. `--to`
+cannot substitute for that: it only narrows *which* dormant store to use, and if we don't know
+which account is live we cannot verify the one you named isn't it. A disagreement prints both
+files' 8-character id prefixes; the fix is to re-authenticate the CLI (run `claude`, then
+`/login`) as the account you're using, or switch the desktop app to that account, so the two
+files agree.
+
+`--json` prints the plan by itself, the same as the default dry run. Combined with `--apply` it
+runs first and describes what actually happened instead — real `written` flags per row and a
+`result` key, not the plan it would have executed. Automation that assumes `sync --json` output
+is always a preview will misread `sync --apply --json`.
+
+- **Sessions you deleted in the destination stay deleted.** The app writes a small record
+  (`deleted_<id>`) when you delete a session but does not consult it when a row for that session
+  reappears elsewhere — confirmed by restoring a deleted row alongside its own record and
+  reopening the app, which showed the session again. `sync` reads the *destination's* records and
+  skips any source session they cover, and names each skip in its report (`kept deleted: …`).
+  `--include-deleted "<title-or-id>"` overrides the skip for **one** named session; it never
+  applies to a whole run. The name must resolve unambiguously — a full id, or a title
+  substring matching exactly one deleted session. (The app files a deletion under its
+  session id *or* under its local id, and `sync` honours both, so either id works here.) A substring that hits several is a refusal
+  listing the candidates, not a silent multi-resurrection. Anything it does resurrect is printed
+  under a `!! RESURRECTING …` heading *before* the list of rows to copy, and flagged again in
+  that list, so bringing back a session you deliberately deleted is never something the command
+  does quietly.
+- **Connector config and permission grants are not copied by default.** A row can carry a full
+  snapshot of the account's connected MCP servers; across 432 real rows on this machine that
+  field ran as large as 1.36 MB in a single row and totalled 289 MB. Stripping it is verified
+  safe: on a real row it cut 132,264 bytes to 715 (99.5% smaller) with the sidebar entry,
+  history, responses, and connectors all working normally afterward, under the account that owned
+  them. That proves the *app* tolerates the field's absence — it does not prove the *destination
+  account* has the same connectors configured. A session that relies on one opens fine either way
+  and fails at its first tool call if the integration isn't set up there too; set it up in the
+  destination account. The default transform also **resets the row's permission state**
+  (`alwaysAllowedReasons`, `sessionPermissionUpdates`, `chromePermissionMode`,
+  `chromeTabGroupId`) to its defaults: a permission you granted under one login was never granted
+  under the other, and the worst case of resetting it is a re-prompt.
+  `--verbatim` skips the whole transform — it copies connector config **and those permission
+  grants** across the account boundary unchanged. The permission half is the more
+  security-relevant of the two: use `--verbatim` only when you actually want the second account
+  to inherit what the first one had allowed.
+- **It needs the app closed too, the same as `move`, `undo`, and `recover` — regardless of which
+  file resolved the signed-in account.** `sync` only ever writes the store you are *not* signed
+  into, and re-checks that at the moment it writes, not just when it planned; that re-check
+  catches an account *switch* between planning and writing, but it is the same determination run
+  again, not an independent second opinion. An earlier version of this tool trusted
+  `~/.claude.json`'s `oauthAccount` enough to skip the running-app check whenever that file
+  named an account outright. A real desktop account switch measured `oauthAccount` staying
+  *stale* while `config.json`'s `lastKnownAccountUuid` tracked the switch — the opposite of the
+  trust ordering that exemption assumed — and a review had already constructed the reverse
+  (`config.json` stale, `oauthAccount` fresh) in a synthetic store: either identity file can be the stale one, and
+  neither is trusted to certify "the destination is dormant" while the app is running. `--apply`,
+  `undo`, and `recover --back` on a sync op therefore all refuse whenever the Claude desktop app
+  is visible, whoever the files say is signed in. The dry run still labels a source resolved from
+  `config.json` rather than `oauthAccount` (`from  (from config.json)`, plus a warning line) —
+  that's a provenance note now, not a stronger/weaker gate: the guard applies the same way either
+  side. A running Claude Code CLI session does not trip it — only the desktop app does. Closing
+  the desktop app removes the check; signing *into* it does not, since the check is about
+  whether its process is running, not which account it's signed into.
+- **The destination's email is best-effort.** `~/.claude.json` names only the account you are
+  signed into, so for the *other* account `sync` looks in the per-account Claude Code config the
+  desktop app leaves inside its local-agent-mode sandbox
+  (`local-agent-mode-sessions\<accountUuid>\…\.claude\.claude.json`), and uses its email only if
+  the account id inside matches. That directory exists only for an account that has used local
+  agent mode, so it is not always there — when it isn't, the dry run prints `(email unknown)`.
+  Either way both endpoints also print their account/org id prefix and their full store path, so
+  you always have a physical folder to recognise: the home directory becomes `~` and each id is
+  truncated to 8 characters (e.g. `~\AppData\...\claude-code-sessions\aaaaaaaa…\bbbbbbbb…`)
+  unless you pass `--verbose` for the paths and ids in full. Check the path, not just the email,
+  before `--apply`.
+- A synced row is a **snapshot**: title and last-activity time live in the row itself, so a
+  session you keep using shows its copy-time title and sits at its copy-time position in the
+  other account, indefinitely. Re-running does not refresh it — `sync` only ever adds rows that
+  are missing, never rewrites one that's already there. Refreshing a stale row (`--update`) is
+  planned but not yet built.
+- **"Already there" is decided by filename, not by conversation.** A row counts as present in the
+  destination when a file of the *same name* (`local_<appSessionId>.json`) exists there. That is
+  exactly right for rows `sync` itself copied, since it copies the name along with the contents.
+  But a destination row pointing at the same conversation under a *different* local id — one
+  placed by an earlier hand-run script, say — is not detected, and `sync` would add a second row
+  for the same session, showing it twice in that account's sidebar. Deleting the duplicate in the
+  app is enough to fix it.
+- Sign into the other account (or restart the app) to see the results.
+
+## Safety design
+
+- **Dry-run by default.** Every mutating command prints its plan and does nothing until you
+  pass `--apply`.
+- **Journaled copy-verify-commit-delete.** A move journals its complete intended state before
+  touching anything, copies to the destination, re-verifies the copy by hash, rewrites listing
+  rows atomically, re-verifies both sides one last time, and only then deletes the source.
+  Nothing is ever deleted while it is the only copy.
+- **`undo`** reverses the most recent completed move or sync by running the same journaled
+  protocol in reverse (for a sync, that means deleting exactly the rows the op wrote, and only
+  while they still match what was written).
+- **`recover`** classifies and resolves any operation a crash or interruption left in a
+  non-terminal state — nothing is left stranded.
+- **`sync`** only ever writes rows into the store of the account you are *not* currently signed
+  into, re-verifying that at the moment it writes as well as when it planned. It refuses outright
+  if it cannot identify which account is signed in at all, or if `~/.claude.json` and
+  `config.json` disagree about which account that is: `--to` names a destination, but without a
+  confirmed, unambiguous live account there is nothing to check that destination against. Every
+  sync mutation — `--apply`, `undo`, and `recover --back` on a sync op — also refuses while it can
+  see the Claude desktop app running, the same guard `move`/`undo`/`recover` use, applied
+  regardless of which identity file resolved the signed-in account: staleness has been shown in
+  both directions (`oauthAccount` measured stale across a real account switch; `config.json`
+  stale in a review-constructed store), so no file evidence is trusted to certify the
+  destination is dormant while the app is visible. A running Claude Code CLI does not count
+  toward this — only the desktop app does.
+- **Refusal philosophy.** The tool fails closed: an unrecognized on-disk layout, an unreadable
+  row, an ambiguous encoding scheme, or a running Claude process is a refusal, not a guess.
+  "Couldn't look" is never treated as "nothing there."
+
+## Compatibility matrix
+
+| Platform | Status | Mutations |
+|---|---|---|
+| 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 |
+| macOS / Linux desktop | unverified | **read-only only** — desktop-store mutations refuse, with no override |
+| CLI-only sessions (any OS) | transcript layout verified | mutations allowed via `--transcript-only` |
+
+The dates are measurements against specific builds — most recently Claude Desktop
+1.24012.11.0 (Microsoft Store install) and Claude Code CLI 2.1.220. The on-disk format has
+changed once already during this tool's own development; treat a much newer build as
+unverified territory.
+
+**On non-Windows, `move` and every `sync` route refuse to touch the desktop store, and there
+is no flag to override that.** The layout is confirmed on Windows only; macOS reportedly has
+two candidate layouts — the ordinary Application Support path and a sandboxed
+`~/Library/Containers/…` one — and neither has been confirmed here. An override would let you
+waive a risk you have no way to evaluate, which is the opposite of how every other refusal in
+this tool works.
+
+What *does* work there: `list` and `doctor`, which are read-only, and `move` for a session
+that has **no desktop listing row** — a CLI-created one — via `--transcript-only`, because the
+transcript layout is verified cross-platform. (Note `--transcript-only` does not force that
+mode; it permits it when no row exists. A session that *has* a desktop row is not movable on
+an unverified platform.)
+
+**If you're on macOS and want this supported:** `claude-code-sessions doctor --verbose` output
+in an issue is exactly what's needed. It's read-only, mutates nothing, and it reports the store
+roots found and the layout recognised — which is the whole of what's missing.
+
+The Windows row is an end-to-end check on a real store, not just a passing test suite:
+a disposable session was moved between projects, the app was restarted and the session
+resumed at its new location, `undo` correctly **refused** once that resume had appended
+to the transcript (rather than discarding the new messages), and a deliberately
+interrupted move was resolved in both directions with `recover`. Afterwards `doctor`
+reported no new findings and the journal held no unresolved operations.
+
+`sync`'s underlying mechanics were checked against two real, live accounts on this machine before
+the command existed: rows copied by hand between them and confirmed visible in the destination's
+sidebar, and — separately — a deleted session's row restored alongside its own deletion record and
+confirmed visible again, which is the finding that makes `sync`'s tombstone-skipping mandatory
+(see `docs/internals.md`). The `sync` command itself is covered by its test suite and, as of
+2026-08-02, its own end-to-end `--apply` run against two real, live accounts: a row synced from
+one account opened in the other with its full conversation history intact. That run did not send
+a new turn through the synced row; a second verification on 2026-08-03 closed that gap — a live
+session's own listing row was synced across accounts and the conversation was then continued
+from the destination account's sidebar, new turns flowing through the synced row. And on
+2026-08-04, `undo` of a synced row the destination account had since opened was refused on
+real data: the row no longer matched what the op journaled, so the drift refusal declined
+to delete it — exactly the designed behavior.
+
+## What's stored locally
+
+`~/.claude-code-journal/` holds the tool's own bookkeeping, never your conversation content:
+
+- `ops/<op-id>/manifest.json` — the journal for each move/undo/recover/sync operation (paths,
+  hashes, row pre-images, phase history). Rotated: the 10 most recent terminal operations are
+  kept, non-terminal ones never pruned automatically.
+- `ops/lock` — a single-instance lock held for the duration of a mutation.
+- `moved-log.jsonl` — a tiny, append-only, never-rotated record of completed moves (session id,
+  from-path, to-path, date), used to recognize your own past moves during future collision and
+  encoding-evidence checks.
+
+To purge everything the tool has ever written, delete the whole `~/.claude-code-journal/` directory.
+This does not touch any transcript or listing row — only the tool's own journal.
+
+**`--json` output is not redacted.** Plain-text output replaces your home directory with `~`
+and truncates any UUID-shaped identifier (session ids, org/account ids in store paths) to its
+first 8 characters by default — pass `--verbose` to see paths and ids in full. `--json` output
+always contains full paths, titles, and ids, unredacted, so it can be consumed programmatically.
+Do not paste `--json` output into a public issue or forum post — copy only the fields you mean
+to share.
+
+`sync --json` is the one place this discloses **a second account's** identifiers: unlike every
+other command, its output carries the destination account's account/org uuids and full store path
+in the clear, regardless of `--verbose`, because those are what the plan is *about*. The
+plain-text report redacts them like everything else; the JSON does not.
+
+**Windows durability note.** The commit step fsyncs every file it writes before deleting the
+source, but Windows has no equivalent of a directory fsync, so the directory-entry update
+itself (the rename, the delete) is not separately forced to disk. The spec accepts this as a
+residual risk rather than a defect: file-level fsync plus delete-last ordering means a power
+loss in this window can only lose an already-fsynced deletion, never earlier fsynced writes —
+worst case is a leftover duplicate, never lost data, and `recover` classifies exactly this
+window into `journaled`/`completed`/`rolled_back`.
+
+## Roadmap
+
+- **`sync --update`** (refreshing a previously synced row that the destination account has kept
+  using) is deferred, not dismissed. Refreshing means overwriting a row the destination account
+  may have changed itself since the copy — the one place `sync` could destroy something instead
+  of just adding to it — so it needs the same drift-refusal treatment `undo` already has before
+  it ships.
+- Platform rows above move from "unverified" to "verified" as contributors confirm the store
+  paths and behavior on their own machines.
+
+## Reporting problems
+
+This is a one-person project and support is best-effort. The fastest reports to act on
+carry the failing command's plain-text output, `claude-code-sessions doctor` output, and —
+if an operation was involved — the journal op id; the issue templates ask for each. Please
+don't paste `--json` output into an issue: it is deliberately unredacted (see above).
+
+## More
+
+Companion post: [The session that synced itself](https://github.com/craigstoller/claude-code-sessions/blob/main/docs/the-session-that-synced-itself.md).
+
+MIT licensed — see [LICENSE](https://github.com/craigstoller/claude-code-sessions/blob/main/LICENSE).