claude-session-backup 0.4.0__tar.gz → 0.4.2__tar.gz

claude_session_backup-0.4.2/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: claude-session-backup
+Version: 0.4.2
+Summary: Git-backed Claude Code session backup with timeline view, folder analysis, deletion detection, and session restore.
+Author-email: djdarcy <6962246+djdarcy@users.noreply.github.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/DazzleML/Claude-Session-Backup
+Project-URL: Repository, https://github.com/DazzleML/Claude-Session-Backup
+Project-URL: Issues, https://github.com/DazzleML/Claude-Session-Backup/issues
+Keywords: claude,claude-code,session,backup,restore,git,archive,conversation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Requires-Dist: dazzle-filekit>=0.2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# Claude-Session-Backup
+
+[![PyPI](https://img.shields.io/pypi/v/claude-session-backup?color=green)](https://pypi.org/project/claude-session-backup/)
+[![Release Date](https://img.shields.io/github/release-date/DazzleML/Claude-Session-Backup?color=green)](https://github.com/DazzleML/Claude-Session-Backup/releases)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: GPL v3](https://img.shields.io/badge/license-GPL%20v3-green.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
+[![Installs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/7aa669e4d85856079eacc71f88c58f6b/raw/installs.json)](https://dazzleml.github.io/Claude-Session-Backup/stats/#installs)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platforms.md)
+
+**Git-backed Claude Code session backup with timeline view, folder analysis, deletion detection, and session restore.**
+
+## The Problem
+
+Claude Code stores session data in `~/.claude/projects/` as JSONL files. These can be silently deleted during upgrades, lossy-compacted via `/compact`, or lost when session compatibility breaks between versions. Once gone, your conversation history -- including debugging sessions, architectural decisions, and code review context -- is unrecoverable.
+
+**csb** preserves every session in your existing `~/.claude` git repository, builds a searchable metadata index, detects deletions, and can restore lost sessions from git history.
+
+> [!NOTE]
+> **Alpha software (cusp of beta) -- nearly feature-complete.** Everything on the original roadmap has shipped: backup, deletion detection, content search (JSONL+sesslogs+FTS5), full session restore (a deleted session's complete footprint recovered from git -- transcript, subagents, tool-results, logger sesslogs -- with original timestamps and symlinks, resumable in Claude Code), a viewer launcher (`csb view`), and a human-readable chat-log layer (`csb distill`).
+>
+> Staying alpha a little longer while the tires get kicked; beta follows once v0.4.0 has settled. Expect occasional rough edges and breaking changes between minor versions until then. By all means use it (and please [file issues](https://github.com/DazzleML/Claude-Session-Backup/issues)) but, as with any backup tool, keep a second copy of anything irreplaceable.
+
+## Quick Start
+
+Three commands install everything -- the CLI plus the Claude Code plugin that fires backups automatically on PreCompact and SessionEnd:
+
+```bash
+# 1. Install the csb CLI
+pip install claude-session-backup
+
+# 2. Add the DazzleML marketplace (one-time)
+claude plugin marketplace add "DazzleML/Claude-Session-Backup"
+
+# 3. Install the plugin -- registers the PreCompact + SessionEnd hooks
+claude plugin install claude-session-backup@dazzle-claude-session-backup
+```
+
+Then verify it works:
+
+```bash
+# Build the index from existing sessions (no git commits yet)
+csb backup --no-commit
+
+# See your session timeline
+csb list
+
+# Full backup with git commits (separate noise + user commits, unsigned)
+csb backup
+```
+
+> [!TIP]
+> **Pair with [claude-session-logger](https://github.com/DazzleML/claude-session-logger/)** for full searchable history. csb preserves Claude Code's session transcripts (`projects/<slug>/<uuid>.jsonl`). The logger captures the *richer* per-session data alongside them -- tool calls, shell commands, agent dispatches -- written to `~/.claude/sesslogs/`. csb backs up those logger files too (it backs up everything under `~/.claude/` via the noise commits), and `csb restore` brings the whole footprint back together: transcript + subagents + tool-results + logger state + sesslogs. The two projects are independent (csb works fine without the logger) but they're designed to complement each other.
+
+## Features
+
+- **Full session preservation**: Every byte of JSONL, subagent data, tool results backed up via git
+- **Timeline view**: Sessions sorted by last use with relative dates, start folder, and top N working directories
+- **Folder analysis**: See where work actually happened -- the most-used folder is highlighted
+- **Deletion detection**: Know when Claude Code removes a session you previously tracked
+- **Session restore**: Recover deleted sessions from git history with `csb restore`
+- **Readable chat logs**: `csb distill` renders any session as an IM-style log -- the full JSONL stays preserved regardless
+- **Two-commit model**: Noise (transient state) and user (configs, skills) committed separately
+- **Unattended operation**: `--no-gpg-sign`, `--quiet`, lock file -- designed for cron and Task Scheduler
+- **Cross-platform**: Works on Windows, Linux, macOS, BSD
+
+## Commands
+
+The daily drivers:
+
+```bash
+csb backup                      # Scan, index, git commit
+csb list                        # Timeline of sessions (filter, sort, --deleted)
+csb scan -d <path> --deleted    # Find (and bulk-restore) what was purged in a folder
+csb search "oauth callback"     # Full-text search across every conversation
+csb distill <query>             # Read a session as a chat log -> ~/.claude/distilled/
+csb resume <query>              # Reopen in Claude Code (UUID, prefix, name, keyword...)
+csb view <query>                # Open in Claude Code History Viewer
+csb restore <session-id>        # Recover a deleted session from git history
+csb status                      # Summary stats
+```
+
+Every command, every flag, and the nitty-gritties live in **[docs/commands.md](docs/commands.md)**.
+
+### Common workflows
+
+The patterns that come up every day:
+
+```bash
+# "What sessions touched THIS project?" -- cd into any folder you were
+# working in and ask. The shortcut form needs no flags to remember.
+cd ~/code/my-project
+csb scan .
+
+# "What was I working on before the reboot / crash / weekend?"
+csb list -n 5
+
+# "I remember discussing it, but in WHICH session?" -- search by content,
+# then read the winner like a chat log.
+csb search "rate limiter backoff"
+csb distill <uuid-from-the-hit>
+
+# "Pick up exactly where I left off" -- by name, prefix, or keyword.
+csb resume MY-PROJECT__2026-6-6__that-refactor
+
+# "Claude Code purged something I needed."
+csb list --deleted
+csb restore MY-PROJECT__2025-5-25__redesign  #or <session-id / id-fragment>
+```
+
+### Searching conversations
+
+`csb search` finds old sessions by **what was discussed**, not just by folder or name -- sub-second across tens of thousands of messages via per-project FTS5 indexes (run `csb update build-fts5` once to build them).
+
+```bash
+csb search "oauth callback"                 # literal substring, case-insensitive
+csb search -E "refresh.*token" -C 3         # regex, with 3 events of context
+```
+
+Full details (what's indexed, source channels, JSON output, freshness semantics): **[docs/commands.md](docs/commands.md#searching-conversations)**.
+
+### Reading conversations (distill)
+
+`csb search` finds the needle; `csb distill` lets you read the haystack comfortably, with an instant-messenger-style log with timestamped speaker turns (`<User>`, `<Claude>`, `<Agent:explore>`) and one-line tool calls instead of walls of tool output. Markdown-friendly (Typora) and editor-friendly (Vim / VSCode / etc).
+
+```bash
+csb distill <anything-that-identifies-a-session>     # writes ~/.claude/distilled/<slug>/<uuid>.md
+```
+
+The distilled file is a *reading layer* -- the full JSONL remains the preserved record. Filters, channels, and the `distill_policy` config: **[docs/commands.md](docs/commands.md#reading-conversations-distill)**.
+
+### Recovery
+
+When Claude Code purges a session that you wanted to keep, csb recovers it from git history **byte+metadata-exact**. This includes the full footprint (transcript, subagents, tool-results, logger files), recreated symlinks, and original timestamps -- a recovered session is indistinguishable from one that was never deleted. `resume`/`view`/`distill` all offer the restore inline when they hit a pruned session.
+
+```bash
+csb list --deleted                                   # what's gone?
+csb restore <session-id>                             # bring one back
+csb scan -d <path> --deleted --restore --dry-run     # preview a bulk recovery
+```
+
+Single + bulk recovery, guarantees and limits, purge-TTL management: **[docs/commands.md](docs/commands.md#recovery)**. Maintenance verbs (`csb update *`): **[docs/maintenance.md](docs/maintenance.md)**.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    subgraph GitRepo["~/.claude/ (your git repo)"]
+        direction TB
+        Data["projects/*.jsonl<br>session-states/<br>file-history/"]
+    end
+
+    subgraph CSB["csb Tool"]
+        direction TB
+        Scripts["scanner.py<br>metadata.py<br><i>(extract names, dates, folders)</i>"]
+        Restore["restore.py"]
+    end
+
+    DB[("session-backup.db<br>(rebuildable metadata cache)")]
+
+    Data -- "scan & read" --> Scripts
+    Scripts -- "upsert" --> DB
+    Scripts -- "git add + commit" --> Data
+    Data -- "git show {commit}:path" --> Restore
+```
+
+**Key principle**: Git is the source of truth. The SQLite database is a rebuildable index for fast queries. If the DB is lost or corrupted, `csb update rebuild-index` reconstructs it while preserving deleted-session metadata. See [`docs/maintenance.md`](docs/maintenance.md) for the `csb update` family of maintenance verbs.
+
+## Automation
+
+The Claude Code plugin (from Quick Start above) covers most users: PreCompact fires before `/compact`, SessionEnd on exit. For manual hooks, cron, Task Scheduler, and distill-on-backup, see **[docs/automation.md](docs/automation.md)**.
+
+## Requirements
+
+- **Python 3.10+**
+- **Git** (for backup storage)
+- **`~/.claude/`** initialized as a git repository (`git -C ~/.claude init`)
+- Moved your Claude directory? csb follows `CLAUDE_CONFIG_DIR` automatically; `--claude-dir`, `CLAUDE_DIR`, and the `claude_dir` config key also work
+
+## Installation
+
+```bash
+# From PyPI (recommended)
+pip install claude-session-backup
+
+# Latest unreleased build from GitHub
+pip install git+https://github.com/DazzleML/Claude-Session-Backup.git
+
+# From source (development / contributing)
+git clone https://github.com/DazzleML/Claude-Session-Backup.git
+cd Claude-Session-Backup
+pip install -e ".[dev]"
+```
+
+Full documentation index: **[docs/README.md](docs/README.md)**.
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.
+
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
+- Development setup (`pip install -e ".[dev]"`)
+- Running the test suite and human test checklists (`tests/checklists/`)
+- Version management with `sync-versions.py`
+- Pull request checklist
+
+Like the project?
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)
+
+## Related Projects
+
+- [claude-session-logger](https://github.com/DazzleML/claude-session-logger) - Real-time per-session tool/conversation logging; csb backs up and restores its files, and its session naming + state-file conventions shaped csb's
+- [dazzle-filekit](https://github.com/DazzleLib/dazzle-filekit) - Cross-platform file operations toolkit (symlink recreation, timestamp restore)
+
+## Acknowledgements
+
+- [claude-vault](https://github.com/kuroko1t/claude-vault) by [@kuroko1t](https://github.com/kuroko1t) -- FTS5 search design, JSONL parsing patterns, Claude Code hook integration. Serendipitously started development on `csb` a week or so before [kuroko1t's blog post](https://dev.to/kuroko1t/i-built-a-tool-to-stop-losing-my-claude-code-conversation-history-5500) laying out the problem.
+- [claude-code-history-viewer](https://github.com/jhlee0409/claude-code-history-viewer) by [@jhlee0409](https://github.com/jhlee0409) - GUI session reader that `csb view` launches.
+
+## License
+
+Claude-Session-Backup, Copyright (C) 2026 Dustin Darcy
+
+Licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html) (GPL-3.0) -- see [LICENSE](LICENSE)

claude_session_backup-0.4.2/README.md

@@ -0,0 +1,224 @@
+# Claude-Session-Backup
+
+[![PyPI](https://img.shields.io/pypi/v/claude-session-backup?color=green)](https://pypi.org/project/claude-session-backup/)
+[![Release Date](https://img.shields.io/github/release-date/DazzleML/Claude-Session-Backup?color=green)](https://github.com/DazzleML/Claude-Session-Backup/releases)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: GPL v3](https://img.shields.io/badge/license-GPL%20v3-green.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
+[![Installs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/7aa669e4d85856079eacc71f88c58f6b/raw/installs.json)](https://dazzleml.github.io/Claude-Session-Backup/stats/#installs)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platforms.md)
+
+**Git-backed Claude Code session backup with timeline view, folder analysis, deletion detection, and session restore.**
+
+## The Problem
+
+Claude Code stores session data in `~/.claude/projects/` as JSONL files. These can be silently deleted during upgrades, lossy-compacted via `/compact`, or lost when session compatibility breaks between versions. Once gone, your conversation history -- including debugging sessions, architectural decisions, and code review context -- is unrecoverable.
+
+**csb** preserves every session in your existing `~/.claude` git repository, builds a searchable metadata index, detects deletions, and can restore lost sessions from git history.
+
+> [!NOTE]
+> **Alpha software (cusp of beta) -- nearly feature-complete.** Everything on the original roadmap has shipped: backup, deletion detection, content search (JSONL+sesslogs+FTS5), full session restore (a deleted session's complete footprint recovered from git -- transcript, subagents, tool-results, logger sesslogs -- with original timestamps and symlinks, resumable in Claude Code), a viewer launcher (`csb view`), and a human-readable chat-log layer (`csb distill`).
+>
+> Staying alpha a little longer while the tires get kicked; beta follows once v0.4.0 has settled. Expect occasional rough edges and breaking changes between minor versions until then. By all means use it (and please [file issues](https://github.com/DazzleML/Claude-Session-Backup/issues)) but, as with any backup tool, keep a second copy of anything irreplaceable.
+
+## Quick Start
+
+Three commands install everything -- the CLI plus the Claude Code plugin that fires backups automatically on PreCompact and SessionEnd:
+
+```bash
+# 1. Install the csb CLI
+pip install claude-session-backup
+
+# 2. Add the DazzleML marketplace (one-time)
+claude plugin marketplace add "DazzleML/Claude-Session-Backup"
+
+# 3. Install the plugin -- registers the PreCompact + SessionEnd hooks
+claude plugin install claude-session-backup@dazzle-claude-session-backup
+```
+
+Then verify it works:
+
+```bash
+# Build the index from existing sessions (no git commits yet)
+csb backup --no-commit
+
+# See your session timeline
+csb list
+
+# Full backup with git commits (separate noise + user commits, unsigned)
+csb backup
+```
+
+> [!TIP]
+> **Pair with [claude-session-logger](https://github.com/DazzleML/claude-session-logger/)** for full searchable history. csb preserves Claude Code's session transcripts (`projects/<slug>/<uuid>.jsonl`). The logger captures the *richer* per-session data alongside them -- tool calls, shell commands, agent dispatches -- written to `~/.claude/sesslogs/`. csb backs up those logger files too (it backs up everything under `~/.claude/` via the noise commits), and `csb restore` brings the whole footprint back together: transcript + subagents + tool-results + logger state + sesslogs. The two projects are independent (csb works fine without the logger) but they're designed to complement each other.
+
+## Features
+
+- **Full session preservation**: Every byte of JSONL, subagent data, tool results backed up via git
+- **Timeline view**: Sessions sorted by last use with relative dates, start folder, and top N working directories
+- **Folder analysis**: See where work actually happened -- the most-used folder is highlighted
+- **Deletion detection**: Know when Claude Code removes a session you previously tracked
+- **Session restore**: Recover deleted sessions from git history with `csb restore`
+- **Readable chat logs**: `csb distill` renders any session as an IM-style log -- the full JSONL stays preserved regardless
+- **Two-commit model**: Noise (transient state) and user (configs, skills) committed separately
+- **Unattended operation**: `--no-gpg-sign`, `--quiet`, lock file -- designed for cron and Task Scheduler
+- **Cross-platform**: Works on Windows, Linux, macOS, BSD
+
+## Commands
+
+The daily drivers:
+
+```bash
+csb backup                      # Scan, index, git commit
+csb list                        # Timeline of sessions (filter, sort, --deleted)
+csb scan -d <path> --deleted    # Find (and bulk-restore) what was purged in a folder
+csb search "oauth callback"     # Full-text search across every conversation
+csb distill <query>             # Read a session as a chat log -> ~/.claude/distilled/
+csb resume <query>              # Reopen in Claude Code (UUID, prefix, name, keyword...)
+csb view <query>                # Open in Claude Code History Viewer
+csb restore <session-id>        # Recover a deleted session from git history
+csb status                      # Summary stats
+```
+
+Every command, every flag, and the nitty-gritties live in **[docs/commands.md](docs/commands.md)**.
+
+### Common workflows
+
+The patterns that come up every day:
+
+```bash
+# "What sessions touched THIS project?" -- cd into any folder you were
+# working in and ask. The shortcut form needs no flags to remember.
+cd ~/code/my-project
+csb scan .
+
+# "What was I working on before the reboot / crash / weekend?"
+csb list -n 5
+
+# "I remember discussing it, but in WHICH session?" -- search by content,
+# then read the winner like a chat log.
+csb search "rate limiter backoff"
+csb distill <uuid-from-the-hit>
+
+# "Pick up exactly where I left off" -- by name, prefix, or keyword.
+csb resume MY-PROJECT__2026-6-6__that-refactor
+
+# "Claude Code purged something I needed."
+csb list --deleted
+csb restore MY-PROJECT__2025-5-25__redesign  #or <session-id / id-fragment>
+```
+
+### Searching conversations
+
+`csb search` finds old sessions by **what was discussed**, not just by folder or name -- sub-second across tens of thousands of messages via per-project FTS5 indexes (run `csb update build-fts5` once to build them).
+
+```bash
+csb search "oauth callback"                 # literal substring, case-insensitive
+csb search -E "refresh.*token" -C 3         # regex, with 3 events of context
+```
+
+Full details (what's indexed, source channels, JSON output, freshness semantics): **[docs/commands.md](docs/commands.md#searching-conversations)**.
+
+### Reading conversations (distill)
+
+`csb search` finds the needle; `csb distill` lets you read the haystack comfortably, with an instant-messenger-style log with timestamped speaker turns (`<User>`, `<Claude>`, `<Agent:explore>`) and one-line tool calls instead of walls of tool output. Markdown-friendly (Typora) and editor-friendly (Vim / VSCode / etc).
+
+```bash
+csb distill <anything-that-identifies-a-session>     # writes ~/.claude/distilled/<slug>/<uuid>.md
+```
+
+The distilled file is a *reading layer* -- the full JSONL remains the preserved record. Filters, channels, and the `distill_policy` config: **[docs/commands.md](docs/commands.md#reading-conversations-distill)**.
+
+### Recovery
+
+When Claude Code purges a session that you wanted to keep, csb recovers it from git history **byte+metadata-exact**. This includes the full footprint (transcript, subagents, tool-results, logger files), recreated symlinks, and original timestamps -- a recovered session is indistinguishable from one that was never deleted. `resume`/`view`/`distill` all offer the restore inline when they hit a pruned session.
+
+```bash
+csb list --deleted                                   # what's gone?
+csb restore <session-id>                             # bring one back
+csb scan -d <path> --deleted --restore --dry-run     # preview a bulk recovery
+```
+
+Single + bulk recovery, guarantees and limits, purge-TTL management: **[docs/commands.md](docs/commands.md#recovery)**. Maintenance verbs (`csb update *`): **[docs/maintenance.md](docs/maintenance.md)**.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    subgraph GitRepo["~/.claude/ (your git repo)"]
+        direction TB
+        Data["projects/*.jsonl<br>session-states/<br>file-history/"]
+    end
+
+    subgraph CSB["csb Tool"]
+        direction TB
+        Scripts["scanner.py<br>metadata.py<br><i>(extract names, dates, folders)</i>"]
+        Restore["restore.py"]
+    end
+
+    DB[("session-backup.db<br>(rebuildable metadata cache)")]
+
+    Data -- "scan & read" --> Scripts
+    Scripts -- "upsert" --> DB
+    Scripts -- "git add + commit" --> Data
+    Data -- "git show {commit}:path" --> Restore
+```
+
+**Key principle**: Git is the source of truth. The SQLite database is a rebuildable index for fast queries. If the DB is lost or corrupted, `csb update rebuild-index` reconstructs it while preserving deleted-session metadata. See [`docs/maintenance.md`](docs/maintenance.md) for the `csb update` family of maintenance verbs.
+
+## Automation
+
+The Claude Code plugin (from Quick Start above) covers most users: PreCompact fires before `/compact`, SessionEnd on exit. For manual hooks, cron, Task Scheduler, and distill-on-backup, see **[docs/automation.md](docs/automation.md)**.
+
+## Requirements
+
+- **Python 3.10+**
+- **Git** (for backup storage)
+- **`~/.claude/`** initialized as a git repository (`git -C ~/.claude init`)
+- Moved your Claude directory? csb follows `CLAUDE_CONFIG_DIR` automatically; `--claude-dir`, `CLAUDE_DIR`, and the `claude_dir` config key also work
+
+## Installation
+
+```bash
+# From PyPI (recommended)
+pip install claude-session-backup
+
+# Latest unreleased build from GitHub
+pip install git+https://github.com/DazzleML/Claude-Session-Backup.git
+
+# From source (development / contributing)
+git clone https://github.com/DazzleML/Claude-Session-Backup.git
+cd Claude-Session-Backup
+pip install -e ".[dev]"
+```
+
+Full documentation index: **[docs/README.md](docs/README.md)**.
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.
+
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
+- Development setup (`pip install -e ".[dev]"`)
+- Running the test suite and human test checklists (`tests/checklists/`)
+- Version management with `sync-versions.py`
+- Pull request checklist
+
+Like the project?
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)
+
+## Related Projects
+
+- [claude-session-logger](https://github.com/DazzleML/claude-session-logger) - Real-time per-session tool/conversation logging; csb backs up and restores its files, and its session naming + state-file conventions shaped csb's
+- [dazzle-filekit](https://github.com/DazzleLib/dazzle-filekit) - Cross-platform file operations toolkit (symlink recreation, timestamp restore)
+
+## Acknowledgements
+
+- [claude-vault](https://github.com/kuroko1t/claude-vault) by [@kuroko1t](https://github.com/kuroko1t) -- FTS5 search design, JSONL parsing patterns, Claude Code hook integration. Serendipitously started development on `csb` a week or so before [kuroko1t's blog post](https://dev.to/kuroko1t/i-built-a-tool-to-stop-losing-my-claude-code-conversation-history-5500) laying out the problem.
+- [claude-code-history-viewer](https://github.com/jhlee0409/claude-code-history-viewer) by [@jhlee0409](https://github.com/jhlee0409) - GUI session reader that `csb view` launches.
+
+## License
+
+Claude-Session-Backup, Copyright (C) 2026 Dustin Darcy
+
+Licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html) (GPL-3.0) -- see [LICENSE](LICENSE)

{claude_session_backup-0.4.0 → claude_session_backup-0.4.2}/claude_session_backup/_version.py

@@ -15,13 +15,13 @@ To bump version: python scripts/sync-versions.py --bump patch
 # Version components - edit these for version bumps
 MAJOR = 0
 MINOR = 4
-PATCH = 0
+PATCH = 2
 PHASE = ""  # Per-MINOR feature set: None, "alpha", "beta", "rc1", etc.
 PRE_RELEASE_NUM = 1  # PEP 440 pre-release number (e.g., a1, b2)
 PROJECT_PHASE = "alpha"  # Project-wide: "prealpha", "alpha", "beta", "stable"
 
 # Auto-updated by git hooks - do not edit manually
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 __app_name__ = "claude-session-backup"
 
 

{claude_session_backup-0.4.0 → claude_session_backup-0.4.2}/claude_session_backup/commands.py

@@ -744,41 +744,37 @@ def cmd_restore(args) -> int:
     conn = open_db(config["index_path"])
     init_schema(conn)
 
-    # Resolve the input against the DB. Three outcomes matter here:
-    #   - Success: use the DB row's jsonl_path.
-    #   - No match + input is a full UUID: fall through to git-history
-    #     fallback (#28). Don't exit -- the DB may be missing the row
-    #     (post-rebuild-index, fresh clone, etc.) while git still has the
-    #     JSONL.
-    #   - No match + input is a prefix/suffix: exit 1. Prefix matching
-    #     requires a DB row to disambiguate; without one we can't help.
-    #   - Ambiguous / invalid input: propagate the resolver's exit code.
-    from .ids import (
-        AmbiguousSessionID,
-        InvalidSessionIDInput,
-        NoSuchSessionID,
-        format_ambiguous_error,
-        resolve_session_id,
+    # Resolve the input (#44 -- restore was the last command without the
+    # shared multi-modal resolver). Order:
+    #   1. Strict ID resolver (prefix/suffix; ambiguity still exits 2).
+    #      A plain miss falls through silently (miss_ok) -- the input may
+    #      be a session NAME, path, folder, or keyword.
+    #   2. Shared multi-modal resolver (same surface as resume/view/
+    #      distill). Multi-match -> candidates timeline, exit 1.
+    #   3. Still nothing + input is a full UUID: git-history fallback
+    #      (#28) below -- the DB may be missing the row while git still
+    #      has the JSONL. Names can't use the fallback (filenames carry
+    #      UUIDs, not titles).
+    full_id, exit_code = _resolve_session_or_exit(
+        conn, args.session_id, miss_ok=True
     )
-    full_id: str | None = None
-    session = None
-    try:
-        full_id = resolve_session_id(conn, args.session_id)
-        session = get_session(conn, full_id)
-    except AmbiguousSessionID as e:
-        print(format_ambiguous_error(e), file=sys.stderr)
-        conn.close()
-        return 2
-    except InvalidSessionIDInput as e:
-        print(f"Error: {e}", file=sys.stderr)
-        conn.close()
-        return 2
-    except NoSuchSessionID:
-        # Don't print yet -- maybe git history can save us if the input is
-        # a full UUID.
-        pass
-    finally:
+    if full_id is None and exit_code:
         conn.close()
+        return exit_code
+    session = get_session(conn, full_id) if full_id else None
+    if session is None:
+        result, method = _resolve_session_query(
+            args.session_id, conn, claude_dir
+        )
+        if isinstance(result, list):
+            label = method.split(":", 1)[1] if ":" in method else method
+            _show_view_candidates(result, args.session_id, label)
+            conn.close()
+            return 1
+        if result is not None:
+            session = result
+            full_id = session["session_id"]
+    conn.close()
 
     # Resolve jsonl_path via DB row if present, otherwise via git history.
     jsonl_path: str | None = None

{claude_session_backup-0.4.0 → claude_session_backup-0.4.2}/claude_session_backup/config.py

@@ -44,14 +44,39 @@ DEFAULT_CONFIG = {
 
 # Environment variable overrides (CLI flag > env var > config file > default)
 ENV_CLAUDE_DIR = "CLAUDE_DIR"
+# Claude Code's OWN relocation variable (#45). Honoring it means csb
+# automatically follows setups that moved the data directory the way
+# Claude Code itself supports (multi-workspace containers, host-mounted
+# dirs, worktree-isolated agent environments) -- zero csb configuration.
+# csb's CLAUDE_DIR wins when both are set (the more specific override).
+ENV_CLAUDE_CONFIG_DIR = "CLAUDE_CONFIG_DIR"
 ENV_DB_PATH = "CLAUDE_SESSION_BACKUP_DB"
 
 CONFIG_FILENAME = "session-backup-config.json"
 
 
+def _env_claude_dir():
+    """The effective env-var override for the Claude data directory:
+    csb's own CLAUDE_DIR first, then Claude Code's CLAUDE_CONFIG_DIR.
+    None when neither is set."""
+    return os.environ.get(ENV_CLAUDE_DIR) or os.environ.get(ENV_CLAUDE_CONFIG_DIR)
+
+
+def _default_claude_dir() -> Path:
+    """The default Claude directory when no explicit path is given:
+    env override (CLAUDE_DIR / CLAUDE_CONFIG_DIR) or ~/.claude.
+
+    The SINGLE place this default lives (#45) -- every fallback site
+    routes through here so relocated setups are followed everywhere,
+    including the chicken-and-egg reads of csb's own config file and
+    Claude Code's settings.json."""
+    env = _env_claude_dir()
+    return Path(env).expanduser() if env else Path.home() / ".claude"
+
+
 def get_config_path(claude_dir=None):
     """Return the config file path."""
-    base = Path(claude_dir).expanduser() if claude_dir else Path.home() / ".claude"
+    base = Path(claude_dir).expanduser() if claude_dir else _default_claude_dir()
     return base / CONFIG_FILENAME
 
 
@@ -64,7 +89,7 @@ def get_settings_path(claude_dir=None):
     purge countdown and (via the ``settings:`` namespace in ``csb config``)
     can edit the TTL through it.
     """
-    base = Path(claude_dir).expanduser() if claude_dir else Path.home() / ".claude"
+    base = Path(claude_dir).expanduser() if claude_dir else _default_claude_dir()
     return base / "settings.json"
 
 
@@ -77,7 +102,7 @@ def load_config(claude_dir=None):
     config = dict(DEFAULT_CONFIG)
 
     # Apply env var overrides before config file (config file can still override)
-    env_claude_dir = os.environ.get(ENV_CLAUDE_DIR)
+    env_claude_dir = _env_claude_dir()  # CLAUDE_DIR, else CLAUDE_CONFIG_DIR (#45)
     env_db = os.environ.get(ENV_DB_PATH)
     if env_claude_dir:
         config["claude_dir"] = env_claude_dir
@@ -103,6 +128,16 @@ def load_config(claude_dir=None):
     if env_db:
         config["index_path"] = env_db
 
+    # The DB lives INSIDE the claude_dir unless explicitly overridden
+    # (#45): when index_path is still the stock default but claude_dir
+    # was relocated (flag / CLAUDE_DIR / CLAUDE_CONFIG_DIR / config),
+    # follow the relocation -- otherwise sessions would scan from the
+    # new dir while the index silently pinned to ~/.claude.
+    if config["index_path"] == DEFAULT_CONFIG["index_path"]:
+        config["index_path"] = str(
+            Path(config["claude_dir"]).expanduser() / "session-backup.db"
+        )
+
     return config