claude-session-backup 0.2.2__tar.gz → 0.3.10__tar.gz

{claude_session_backup-0.2.2 → claude_session_backup-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-session-backup
-Version: 0.2.2
+Version: 0.3.10
 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
@@ -47,13 +47,13 @@ Claude Code stores session data in `~/.claude/projects/` as JSONL files. These c
 **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.
 
 > [!WARNING]
-> **Prealpha software.** `csb` is functional and all tests pass, but it is not yet feature-complete and has not been broadly tested outside of active dogfooding. Expect bugs, rough edges, and breaking changes until the first alpha/beta releases. Three items gate the next milestone: distilled conversation backup (#12), end-to-end restore verification (#13), and a CLI launcher for claude-code-history-viewer (#14). By all means use it -- and please file issues -- but don't rely on `csb` as your only backup just yet.
+> **Prealpha software.** `csb` is functional and all tests pass, but it is not yet feature-complete and has not been broadly tested outside of active dogfooding. Expect bugs, rough edges, and breaking changes until the first alpha/beta releases. Three items gate the next milestone: distilled conversation backup ([#12](https://github.com/DazzleML/Claude-Session-Backup/issues/12)), end-to-end restore verification ([#13](https://github.com/DazzleML/Claude-Session-Backup/issues/13)), and a CLI launcher for claude-code-history-viewer ([#14](https://github.com/DazzleML/Claude-Session-Backup/issues/14)). By all means use it -- and please [file issues](https://github.com/DazzleML/Claude-Session-Backup/issues) -- but don't rely on `csb` as your only backup just yet.
 
 ## Quick Start
 
 ```bash
-# 1. Install the CLI (PyPI release coming shortly)
-pip install git+https://github.com/DazzleML/Claude-Session-Backup.git
+# 1. Install the CLI
+pip install claude-session-backup
 
 # 2. (recommended) Install the Claude Code plugin so pre-compact backups fire
 #    automatically. Full commands in the "Claude Code Plugin" section below.
@@ -89,17 +89,54 @@ csb list [keyword]                    # Filter by keyword in name/project/folder
 csb list --sort expiration            # Sort by soonest-to-purge first
 csb list --sort {last-used|expiration|started|oldest|messages|size}
 csb list --deleted                    # Show deleted sessions
-csb scan [path]                       # Find sessions touching this directory
-csb scan [path] -NU                   # Prefix-only match (skip folder-usage search)
+csb scan                              # Find sessions touching cwd (path-prefix)
+csb scan <term>                       # Filter by term: name, project, folder paths
+csb scan ./<dirname>                  # Shortcut: same as -d <dirname> (no flag to remember)
+csb scan -d <pattern>                 # Path-strict: folder + descendants
+csb scan -D <pattern>                 # Path-strict: this folder only, no descendants
+csb scan -s <pattern>                 # start_folder only ("what sessions originated here?")
+csb scan -d <pattern> <term>          # Scope-then-filter combined
+csb scan -d <pattern>* / -D <pattern>* / -s <pattern>*  # Trailing-* wildcard
+csb scan ... -NU                      # Skip folder-usage search (start_folder only)
 csb status                            # Summary stats
 csb show <session-id>                 # Detailed session info with folder analysis
-csb search "query"                    # Search by session name, project, or folder
+csb search "query"                    # Search transcript content (USER/AI/AGENT messages)
+csb search -E "regex.*pattern"        # Regex mode (Python re)
+csb search "X" -C 3                   # Show 3 events of context before AND after each hit
+csb search "X" -A 5 -B 2              # Asymmetric context (5 after, 2 before)
+csb search "X" --source convo         # Force a source channel; auto = convo > sesslog > jsonl
+csb search "X" --session <uuid>       # Constrain to one session by UUID prefix
+csb search "X" --json                 # NDJSON output for piping into jq
 csb restore <session-id>              # Restore deleted session from git history
 csb resume <session-id>               # Launch claude --resume with full UUID
 csb rebuild-index                     # Reconstruct SQLite from scratch
-csb config [key] [value]              # View/edit configuration
+csb config [key] [value]              # View/edit csb's own configuration
+csb config settings:cleanupPeriodDays         # View Claude Code's session purge TTL
+csb config settings:cleanupPeriodDays 365     # Set the TTL (writes ~/.claude/settings.json)
 ```
 
+### Searching conversations
+
+Use `csb search` to find old sessions by **what was discussed**, not just by folder or name. The query is a case-insensitive literal substring by default; `-E` switches to Python regex.
+
+```bash
+# Find every session where you talked about OAuth callbacks
+csb search "oauth callback"
+
+# Regex with context (3 events above and below each hit)
+csb search -E "refresh.*token" -C 3
+
+# Constrain to one session and one source channel
+csb search "auth flow" --session 916441e6 --source convo
+
+# Pipe results into another tool
+csb search "rate limit" --json | jq -r '.session_id' | sort -u
+```
+
+Per-session source preference is `.convo*` (preferred, USER/AI/AGENT-only) -> `.sesslog*` (filtered to USER/AI/AGENT) -> `<uuid>.jsonl` (authoritative fallback). New sessions logged by [claude-session-logger](https://github.com/DazzleML/claude-session-logger) get the cleanest `.convo*` source; older sessions fall through to JSONL automatically. Hits are sorted by session last-used time, so the most recent matches surface first.
+
+For metadata search (folder paths, project, session name), use `csb list <filter>` or `csb scan <term>` -- those are the right tools for "find sessions in this folder" rather than "find sessions about this topic."
+
 ### Finding sessions at risk of purge
 
 Claude Code auto-deletes sessions after `cleanupPeriodDays` (default 30). To see which of your sessions are closest to being purged:
@@ -110,6 +147,19 @@ csb list --sort expiration -n 20
 
 Sessions are sorted by the JSONL file's modification time, so active sessions (which refresh their mtime on every interaction) stay safe while dormant sessions surface to the top of the expiration list.
 
+To **view or change the TTL itself** without hand-editing `settings.json`:
+
+```bash
+csb config settings:cleanupPeriodDays         # show current value + source + guidance
+csb config settings:cleanupPeriodDays 365     # keep transcripts for a year
+csb config settings:cleanupPeriodDays 36500   # effectively never purge (~100 years)
+```
+
+The `settings:` prefix is a fully-qualified namespace: a bare key (e.g. `csb config display_top_folders`) addresses csb's own config, while a `settings:` key addresses Claude Code's `~/.claude/settings.json` -- the two never collide. The write is a read-merge-write that preserves your other settings and refuses to touch a malformed file.
+
+> [!CAUTION]
+> `cleanupPeriodDays` of **`0` does not mean "keep forever"** -- Claude Code treats it as *disable session persistence* and deletes all transcripts at its next startup. csb refuses to write `0` without `--force`. For "never purge", set a large number instead.
+
 ## How It Works
 
 ```mermaid
@@ -197,16 +247,16 @@ schtasks /create /tn "Claude Session Backup" /tr "csb backup --quiet" /sc minute
 ## Installation
 
 ```bash
-# From GitHub (recommended until PyPI publish lands)
+# 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]"
-
-# From PyPI (once published)
-pip install claude-session-backup
 ```
 
 ## Contributing

{claude_session_backup-0.2.2 → claude_session_backup-0.3.10}/README.md

@@ -16,13 +16,13 @@ Claude Code stores session data in `~/.claude/projects/` as JSONL files. These c
 **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.
 
 > [!WARNING]
-> **Prealpha software.** `csb` is functional and all tests pass, but it is not yet feature-complete and has not been broadly tested outside of active dogfooding. Expect bugs, rough edges, and breaking changes until the first alpha/beta releases. Three items gate the next milestone: distilled conversation backup (#12), end-to-end restore verification (#13), and a CLI launcher for claude-code-history-viewer (#14). By all means use it -- and please file issues -- but don't rely on `csb` as your only backup just yet.
+> **Prealpha software.** `csb` is functional and all tests pass, but it is not yet feature-complete and has not been broadly tested outside of active dogfooding. Expect bugs, rough edges, and breaking changes until the first alpha/beta releases. Three items gate the next milestone: distilled conversation backup ([#12](https://github.com/DazzleML/Claude-Session-Backup/issues/12)), end-to-end restore verification ([#13](https://github.com/DazzleML/Claude-Session-Backup/issues/13)), and a CLI launcher for claude-code-history-viewer ([#14](https://github.com/DazzleML/Claude-Session-Backup/issues/14)). By all means use it -- and please [file issues](https://github.com/DazzleML/Claude-Session-Backup/issues) -- but don't rely on `csb` as your only backup just yet.
 
 ## Quick Start
 
 ```bash
-# 1. Install the CLI (PyPI release coming shortly)
-pip install git+https://github.com/DazzleML/Claude-Session-Backup.git
+# 1. Install the CLI
+pip install claude-session-backup
 
 # 2. (recommended) Install the Claude Code plugin so pre-compact backups fire
 #    automatically. Full commands in the "Claude Code Plugin" section below.
@@ -58,17 +58,54 @@ csb list [keyword]                    # Filter by keyword in name/project/folder
 csb list --sort expiration            # Sort by soonest-to-purge first
 csb list --sort {last-used|expiration|started|oldest|messages|size}
 csb list --deleted                    # Show deleted sessions
-csb scan [path]                       # Find sessions touching this directory
-csb scan [path] -NU                   # Prefix-only match (skip folder-usage search)
+csb scan                              # Find sessions touching cwd (path-prefix)
+csb scan <term>                       # Filter by term: name, project, folder paths
+csb scan ./<dirname>                  # Shortcut: same as -d <dirname> (no flag to remember)
+csb scan -d <pattern>                 # Path-strict: folder + descendants
+csb scan -D <pattern>                 # Path-strict: this folder only, no descendants
+csb scan -s <pattern>                 # start_folder only ("what sessions originated here?")
+csb scan -d <pattern> <term>          # Scope-then-filter combined
+csb scan -d <pattern>* / -D <pattern>* / -s <pattern>*  # Trailing-* wildcard
+csb scan ... -NU                      # Skip folder-usage search (start_folder only)
 csb status                            # Summary stats
 csb show <session-id>                 # Detailed session info with folder analysis
-csb search "query"                    # Search by session name, project, or folder
+csb search "query"                    # Search transcript content (USER/AI/AGENT messages)
+csb search -E "regex.*pattern"        # Regex mode (Python re)
+csb search "X" -C 3                   # Show 3 events of context before AND after each hit
+csb search "X" -A 5 -B 2              # Asymmetric context (5 after, 2 before)
+csb search "X" --source convo         # Force a source channel; auto = convo > sesslog > jsonl
+csb search "X" --session <uuid>       # Constrain to one session by UUID prefix
+csb search "X" --json                 # NDJSON output for piping into jq
 csb restore <session-id>              # Restore deleted session from git history
 csb resume <session-id>               # Launch claude --resume with full UUID
 csb rebuild-index                     # Reconstruct SQLite from scratch
-csb config [key] [value]              # View/edit configuration
+csb config [key] [value]              # View/edit csb's own configuration
+csb config settings:cleanupPeriodDays         # View Claude Code's session purge TTL
+csb config settings:cleanupPeriodDays 365     # Set the TTL (writes ~/.claude/settings.json)
 ```
 
+### Searching conversations
+
+Use `csb search` to find old sessions by **what was discussed**, not just by folder or name. The query is a case-insensitive literal substring by default; `-E` switches to Python regex.
+
+```bash
+# Find every session where you talked about OAuth callbacks
+csb search "oauth callback"
+
+# Regex with context (3 events above and below each hit)
+csb search -E "refresh.*token" -C 3
+
+# Constrain to one session and one source channel
+csb search "auth flow" --session 916441e6 --source convo
+
+# Pipe results into another tool
+csb search "rate limit" --json | jq -r '.session_id' | sort -u
+```
+
+Per-session source preference is `.convo*` (preferred, USER/AI/AGENT-only) -> `.sesslog*` (filtered to USER/AI/AGENT) -> `<uuid>.jsonl` (authoritative fallback). New sessions logged by [claude-session-logger](https://github.com/DazzleML/claude-session-logger) get the cleanest `.convo*` source; older sessions fall through to JSONL automatically. Hits are sorted by session last-used time, so the most recent matches surface first.
+
+For metadata search (folder paths, project, session name), use `csb list <filter>` or `csb scan <term>` -- those are the right tools for "find sessions in this folder" rather than "find sessions about this topic."
+
 ### Finding sessions at risk of purge
 
 Claude Code auto-deletes sessions after `cleanupPeriodDays` (default 30). To see which of your sessions are closest to being purged:
@@ -79,6 +116,19 @@ csb list --sort expiration -n 20
 
 Sessions are sorted by the JSONL file's modification time, so active sessions (which refresh their mtime on every interaction) stay safe while dormant sessions surface to the top of the expiration list.
 
+To **view or change the TTL itself** without hand-editing `settings.json`:
+
+```bash
+csb config settings:cleanupPeriodDays         # show current value + source + guidance
+csb config settings:cleanupPeriodDays 365     # keep transcripts for a year
+csb config settings:cleanupPeriodDays 36500   # effectively never purge (~100 years)
+```
+
+The `settings:` prefix is a fully-qualified namespace: a bare key (e.g. `csb config display_top_folders`) addresses csb's own config, while a `settings:` key addresses Claude Code's `~/.claude/settings.json` -- the two never collide. The write is a read-merge-write that preserves your other settings and refuses to touch a malformed file.
+
+> [!CAUTION]
+> `cleanupPeriodDays` of **`0` does not mean "keep forever"** -- Claude Code treats it as *disable session persistence* and deletes all transcripts at its next startup. csb refuses to write `0` without `--force`. For "never purge", set a large number instead.
+
 ## How It Works
 
 ```mermaid
@@ -166,16 +216,16 @@ schtasks /create /tn "Claude Session Backup" /tr "csb backup --quiet" /sc minute
 ## Installation
 
 ```bash
-# From GitHub (recommended until PyPI publish lands)
+# 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]"
-
-# From PyPI (once published)
-pip install claude-session-backup
 ```
 
 ## Contributing

{claude_session_backup-0.2.2 → claude_session_backup-0.3.10}/claude_session_backup/_version.py

@@ -14,14 +14,14 @@ To bump version: python scripts/sync-versions.py --bump patch
 
 # Version components - edit these for version bumps
 MAJOR = 0
-MINOR = 2
-PATCH = 2
+MINOR = 3
+PATCH = 10
 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 = "prealpha"  # Project-wide: "prealpha", "alpha", "beta", "stable"
 
 # Auto-updated by git hooks - do not edit manually
-__version__ = "0.2.2"
+__version__ = "0.3.10_main_29-20260530-e03e14cd"
 __app_name__ = "claude-session-backup"