claude-jacked 0.2.2__tar.gz → 0.2.7__tar.gz

{claude_jacked-0.2.2 → claude_jacked-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-jacked
-Version: 0.2.2
+Version: 0.2.7
 Summary: Cross-machine semantic search for Claude Code sessions
 Project-URL: Homepage, https://github.com/jackneil/claude-jacked
 Project-URL: Repository, https://github.com/jackneil/claude-jacked
@@ -30,29 +30,52 @@ Description-Content-Type: text/markdown
 
 Supercharge your Claude Code workflow with cross-machine session search, review agents, and workflow commands.
 
-## Install (Copy This Into Claude Code)
+## Quick Install
+
+**One-liner (Linux/macOS/Git Bash):**
+```bash
+curl -sSL https://raw.githubusercontent.com/jackneil/claude-jacked/master/install.sh | bash
+```
+
+**Or manual two-step:**
+```bash
+pipx install claude-jacked && jacked install
+```
+
+Then set up Qdrant credentials (see [Qdrant Setup](#set-up-qdrant-cloud)) and run `jacked backfill`.
+
+---
+
+## Guided Install (Copy Into Claude Code)
+
+> 📋 [View on GitHub](https://github.com/jackneil/claude-jacked#guided-install-copy-into-claude-code) for copy button
 
 ```
 Install claude-jacked for me. First check what's already set up, then help me with anything missing:
 
 DIAGNOSTIC PHASE (run these first to see current state):
 - Detect my operating system
-- Check if pipx is installed: pipx --version
+- Check if pipx is installed: pipx --version (or: python -m pipx --version)
 - Check if jacked CLI is installed: jacked --version (or on Windows: where jacked)
-- Check if Qdrant credentials are set: echo $QDRANT_CLAUDE_SESSIONS_ENDPOINT (bash) or echo %QDRANT_CLAUDE_SESSIONS_ENDPOINT% (cmd)
-- Check current config: jacked configure --show (if jacked exists)
+- Check if Qdrant credentials are set in current shell: echo $QDRANT_CLAUDE_SESSIONS_ENDPOINT
 - Check if hook is installed: look in ~/.claude/settings.json for "jacked index"
-- Check indexed sessions: jacked status (if connected)
+- If jacked exists and env vars visible: jacked status && jacked configure --show
+
+WINDOWS EXTRA CHECK (Git Bash doesn't inherit Windows System Environment):
+- If env vars NOT visible in bash, check Windows System Environment:
+  powershell.exe -Command "[System.Environment]::GetEnvironmentVariable('QDRANT_CLAUDE_SESSIONS_ENDPOINT', 'Machine')"
+  powershell.exe -Command "[System.Environment]::GetEnvironmentVariable('QDRANT_CLAUDE_SESSIONS_ENDPOINT', 'User')"
+- If vars exist in Windows but not bash: they need to be added to ~/.bashrc
 
 REPORT what's already configured vs what's missing before proceeding.
 
 SETUP PHASE (only do steps that are missing):
 1. If no Python 3.11+: help install miniconda
 2. If no pipx: pip install pipx && pipx ensurepath
-3. If jacked not installed: pipx install claude-jacked
-4. If no Qdrant credentials: walk me through cloud.qdrant.io setup
-5. If env vars missing: help add to shell profile (QDRANT_CLAUDE_SESSIONS_ENDPOINT, QDRANT_CLAUDE_SESSIONS_API_KEY, JACKED_USER_NAME)
-6. If hook/agents not installed: jacked install
+3. If jacked not installed: pipx install claude-jacked && jacked install
+4. If no Qdrant credentials anywhere: walk me through cloud.qdrant.io setup
+5. If env vars in Windows but not bash: add export lines to ~/.bashrc, then source it
+6. If env vars missing entirely: help add to shell profile
 7. If no indexed sessions: jacked backfill
 
 VERIFY: jacked status && jacked configure --show
@@ -61,9 +84,11 @@ Ask if this is personal use or team setup.
 If team: explain that everyone needs the same Qdrant cluster credentials.
 
 WINDOWS NOTES:
+- Claude Code uses Git Bash, which does NOT inherit Windows System Environment variables
+- If you set env vars in Windows Settings, you ALSO need them in ~/.bashrc for Git Bash
 - pipx installs jacked to: C:\Users\<user>\pipx\venvs\claude-jacked\Scripts\jacked.exe
-- If "jacked" isn't found, find it with: where jacked OR dir C:\Users\%USERNAME%\pipx\venvs\claude-jacked\Scripts\jacked.exe
-- In Git Bash, backslash paths get mangled. Use: cmd.exe /c "C:\full\path\to\jacked.exe <command>"
+- If "jacked" isn't found, find it with: where jacked OR ls /c/Users/$USER/pipx/venvs/claude-jacked/Scripts/
+- In Git Bash, backslash paths get mangled. Use forward slashes: /c/Users/...
 ```
 
 ---
@@ -97,7 +122,7 @@ The goal: never lose useful context, never repeat solved problems, catch issues
 
 ## Manual Install
 
-### Install the CLI
+### Step 1: Install the CLI
 
 **Use pipx** (recommended - installs globally, always on PATH):
 
@@ -109,7 +134,21 @@ Don't have pipx? `pip install pipx && pipx ensurepath`
 
 **Why not regular pip?** If you `pip install` into a conda env or virtualenv, the `jacked` command only works when that env is active. Claude Code hooks run in a fresh shell without your env activated → `jacked: command not found`. pipx avoids this by installing to an isolated global location that's always on PATH.
 
-### Set Up Qdrant Cloud
+### Step 2: Install Claude Code Integration
+
+```bash
+jacked install
+```
+
+This installs:
+- All agents to `~/.claude/agents/`
+- All commands to `~/.claude/commands/`
+- The `/jacked` skill to `~/.claude/skills/`
+- Auto-index hook (indexes sessions after every Claude response)
+
+Restart Claude Code after running this.
+
+### Step 3: Set Up Qdrant Cloud
 
 The session search features require Qdrant Cloud for vector storage and embedding:
 
@@ -122,29 +161,31 @@ export QDRANT_CLAUDE_SESSIONS_ENDPOINT="https://your-cluster.qdrant.io"
 export QDRANT_CLAUDE_SESSIONS_API_KEY="your-api-key"
 ```
 
-### Install Everything
+### Step 4: Index Your Sessions
 
 ```bash
-jacked install
+jacked backfill        # Index all existing sessions
+jacked status          # Verify it's working
+jacked search "something you worked on before"
 ```
 
-This installs:
-- All agents to `~/.claude/agents/`
-- All commands to `~/.claude/commands/`
-- The `/jacked` skill to `~/.claude/skills/`
-- Auto-index hook (indexes sessions after every Claude response)
+**Note:** If you only want the agents and commands (not the session search), you can manually copy just those files from the repo without setting up Qdrant. But the main `jacked` functionality requires it.
 
-Restart Claude Code after running this.
+---
 
-### Index Your Sessions
+## Uninstall
 
+**One-liner:**
 ```bash
-jacked backfill        # Index all existing sessions
-jacked status          # Verify it's working
-jacked search "something you worked on before"
+curl -sSL https://raw.githubusercontent.com/jackneil/claude-jacked/master/uninstall.sh | bash
 ```
 
-**Note:** If you only want the agents and commands (not the session search), you can manually copy just those files from the repo without setting up Qdrant. But the main `jacked` functionality requires it.
+**Or manual two-step:**
+```bash
+jacked uninstall && pipx uninstall claude-jacked
+```
+
+This removes hooks, skill, agents, and commands from Claude Code. Your Qdrant index is preserved if you reinstall later.
 
 ---
 
@@ -271,13 +312,16 @@ jacked search "query"              # Semantic search with multi-factor ranking
 jacked search "query" --mine       # Only your sessions
 jacked search "query" --user sarah # Only this teammate's sessions
 jacked search "query" --repo path  # Boost results from this repo
+jacked search "query" --type chunk # Search full transcript chunks only
 
-jacked list                        # List indexed sessions
-jacked list --repo myproject       # Filter by repo name
+jacked sessions                        # List indexed sessions
+jacked sessions --repo myproject       # Filter by repo name
 
-jacked retrieve <session_id>       # Get full transcript
-jacked retrieve <id1> <id2>        # Get multiple transcripts
-jacked retrieve <id> --summary     # Get summary only
+jacked retrieve <session_id>       # Smart mode: plan + summaries + labels
+jacked retrieve <id> --mode full   # Get full transcript (huge)
+jacked retrieve <id> --mode plan   # Just the plan file
+jacked retrieve <id> --mode agents # Just subagent summaries
+jacked retrieve <id> --mode labels # Just summary labels (tiny)
 
 jacked index /path/to/session.jsonl --repo /path  # Index specific session
 jacked backfill                    # Index all existing sessions
@@ -285,7 +329,11 @@ jacked backfill --force            # Re-index everything
 
 jacked status                      # Check Qdrant connectivity
 jacked delete <session_id>         # Remove session from index
+jacked cleardb                     # Delete all YOUR indexed data (requires confirmation)
 jacked install                     # Install hook + skill + agents + commands
+jacked install --sounds            # Also install sound notification hooks
+jacked uninstall                   # Remove hook + skill + agents + commands
+jacked uninstall --sounds          # Remove only sound hooks
 jacked configure                   # Show config help
 jacked configure --show            # Show current config values
 ```
@@ -316,6 +364,44 @@ jacked configure --show            # Show current config values
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Smart Retrieval (v0.2.6+)
+
+Sessions are indexed with multiple content types for efficient retrieval:
+
+| Content Type | What It Contains | Token Cost |
+|--------------|------------------|------------|
+| `plan` | Full implementation strategy from plan files | ~500-2K |
+| `subagent_summary` | Rich summaries from exploration/planning agents | ~200-500 each |
+| `summary_label` | Tiny chapter titles from auto-compaction | ~10-20 each |
+| `user_message` | First 5 user messages for intent matching | ~100-500 each |
+| `chunk` | Full transcript chunks (legacy) | ~2K each |
+
+**Retrieval Modes:**
+
+| Mode | What's Included | When to Use |
+|------|-----------------|-------------|
+| `smart` | Plan + agent summaries + labels + user msgs | Default - best balance (~5-10K tokens) |
+| `plan` | Just the plan file | Quick strategic overview |
+| `labels` | Just summary labels | Quick topic check (tiny) |
+| `agents` | All subagent summaries | Deep dive into exploration results |
+| `full` | Everything including transcript | Need full details (50-200K tokens - use sparingly!) |
+
+**Why smart mode?** Full transcripts can be 50-200K tokens, which blows up your context window. Smart mode returns the highest-value content (~5-10K tokens) so you get the key decisions and plans without the bloat.
+
+**Staleness warnings:** When loading old context, you'll see warnings based on age:
+- 7-30 days: "Code may have changed since this session"
+- 30-90 days: "Treat as starting point for WHERE to look, not WHAT to do"
+- 90+ days: "Historical reference only - verify everything"
+
+### Re-indexing After Upgrade
+
+If you upgraded from a version before v0.2.6, your existing sessions are indexed as full transcript chunks only. To get smart retrieval:
+
+```bash
+jacked cleardb   # Wipes YOUR data (not teammates), requires typing "DELETE MY DATA"
+jacked backfill  # Re-index with new content types
+```
+
 ---
 
 ## Configuration
@@ -365,6 +451,25 @@ The `jacked install` command adds this to `~/.claude/settings.json`:
 }
 ```
 
+### Sound Notifications
+
+Add audio feedback when Claude needs attention or completes a task:
+
+```bash
+jacked install --sounds
+```
+
+This adds hooks that play:
+- **Notification sound** when Claude requests user input
+- **Completion sound** when Claude finishes a task
+
+Works on Windows (PowerShell), macOS (afplay), Linux (paplay), and WSL. Falls back to terminal bell on unsupported systems.
+
+To remove only sound hooks (keep everything else):
+```bash
+jacked uninstall --sounds
+```
+
 ---
 
 ## Security Warning
@@ -380,6 +485,8 @@ Recommendations:
 - Keep your Qdrant API key secure
 - Consider self-hosting Qdrant for sensitive work
 
+**Data isolation:** The `cleardb` command only deletes data belonging to the current user (based on `JACKED_USER_NAME`). Teammates' data is unaffected.
+
 ---
 
 ## Troubleshooting

{claude_jacked-0.2.2 → claude_jacked-0.2.7}/README.md

@@ -2,29 +2,52 @@
 
 Supercharge your Claude Code workflow with cross-machine session search, review agents, and workflow commands.
 
-## Install (Copy This Into Claude Code)
+## Quick Install
+
+**One-liner (Linux/macOS/Git Bash):**
+```bash
+curl -sSL https://raw.githubusercontent.com/jackneil/claude-jacked/master/install.sh | bash
+```
+
+**Or manual two-step:**
+```bash
+pipx install claude-jacked && jacked install
+```
+
+Then set up Qdrant credentials (see [Qdrant Setup](#set-up-qdrant-cloud)) and run `jacked backfill`.
+
+---
+
+## Guided Install (Copy Into Claude Code)
+
+> 📋 [View on GitHub](https://github.com/jackneil/claude-jacked#guided-install-copy-into-claude-code) for copy button
 
 ```
 Install claude-jacked for me. First check what's already set up, then help me with anything missing:
 
 DIAGNOSTIC PHASE (run these first to see current state):
 - Detect my operating system
-- Check if pipx is installed: pipx --version
+- Check if pipx is installed: pipx --version (or: python -m pipx --version)
 - Check if jacked CLI is installed: jacked --version (or on Windows: where jacked)
-- Check if Qdrant credentials are set: echo $QDRANT_CLAUDE_SESSIONS_ENDPOINT (bash) or echo %QDRANT_CLAUDE_SESSIONS_ENDPOINT% (cmd)
-- Check current config: jacked configure --show (if jacked exists)
+- Check if Qdrant credentials are set in current shell: echo $QDRANT_CLAUDE_SESSIONS_ENDPOINT
 - Check if hook is installed: look in ~/.claude/settings.json for "jacked index"
-- Check indexed sessions: jacked status (if connected)
+- If jacked exists and env vars visible: jacked status && jacked configure --show
+
+WINDOWS EXTRA CHECK (Git Bash doesn't inherit Windows System Environment):
+- If env vars NOT visible in bash, check Windows System Environment:
+  powershell.exe -Command "[System.Environment]::GetEnvironmentVariable('QDRANT_CLAUDE_SESSIONS_ENDPOINT', 'Machine')"
+  powershell.exe -Command "[System.Environment]::GetEnvironmentVariable('QDRANT_CLAUDE_SESSIONS_ENDPOINT', 'User')"
+- If vars exist in Windows but not bash: they need to be added to ~/.bashrc
 
 REPORT what's already configured vs what's missing before proceeding.
 
 SETUP PHASE (only do steps that are missing):
 1. If no Python 3.11+: help install miniconda
 2. If no pipx: pip install pipx && pipx ensurepath
-3. If jacked not installed: pipx install claude-jacked
-4. If no Qdrant credentials: walk me through cloud.qdrant.io setup
-5. If env vars missing: help add to shell profile (QDRANT_CLAUDE_SESSIONS_ENDPOINT, QDRANT_CLAUDE_SESSIONS_API_KEY, JACKED_USER_NAME)
-6. If hook/agents not installed: jacked install
+3. If jacked not installed: pipx install claude-jacked && jacked install
+4. If no Qdrant credentials anywhere: walk me through cloud.qdrant.io setup
+5. If env vars in Windows but not bash: add export lines to ~/.bashrc, then source it
+6. If env vars missing entirely: help add to shell profile
 7. If no indexed sessions: jacked backfill
 
 VERIFY: jacked status && jacked configure --show
@@ -33,9 +56,11 @@ Ask if this is personal use or team setup.
 If team: explain that everyone needs the same Qdrant cluster credentials.
 
 WINDOWS NOTES:
+- Claude Code uses Git Bash, which does NOT inherit Windows System Environment variables
+- If you set env vars in Windows Settings, you ALSO need them in ~/.bashrc for Git Bash
 - pipx installs jacked to: C:\Users\<user>\pipx\venvs\claude-jacked\Scripts\jacked.exe
-- If "jacked" isn't found, find it with: where jacked OR dir C:\Users\%USERNAME%\pipx\venvs\claude-jacked\Scripts\jacked.exe
-- In Git Bash, backslash paths get mangled. Use: cmd.exe /c "C:\full\path\to\jacked.exe <command>"
+- If "jacked" isn't found, find it with: where jacked OR ls /c/Users/$USER/pipx/venvs/claude-jacked/Scripts/
+- In Git Bash, backslash paths get mangled. Use forward slashes: /c/Users/...
 ```
 
 ---
@@ -69,7 +94,7 @@ The goal: never lose useful context, never repeat solved problems, catch issues
 
 ## Manual Install
 
-### Install the CLI
+### Step 1: Install the CLI
 
 **Use pipx** (recommended - installs globally, always on PATH):
 
@@ -81,7 +106,21 @@ Don't have pipx? `pip install pipx && pipx ensurepath`
 
 **Why not regular pip?** If you `pip install` into a conda env or virtualenv, the `jacked` command only works when that env is active. Claude Code hooks run in a fresh shell without your env activated → `jacked: command not found`. pipx avoids this by installing to an isolated global location that's always on PATH.
 
-### Set Up Qdrant Cloud
+### Step 2: Install Claude Code Integration
+
+```bash
+jacked install
+```
+
+This installs:
+- All agents to `~/.claude/agents/`
+- All commands to `~/.claude/commands/`
+- The `/jacked` skill to `~/.claude/skills/`
+- Auto-index hook (indexes sessions after every Claude response)
+
+Restart Claude Code after running this.
+
+### Step 3: Set Up Qdrant Cloud
 
 The session search features require Qdrant Cloud for vector storage and embedding:
 
@@ -94,29 +133,31 @@ export QDRANT_CLAUDE_SESSIONS_ENDPOINT="https://your-cluster.qdrant.io"
 export QDRANT_CLAUDE_SESSIONS_API_KEY="your-api-key"
 ```
 
-### Install Everything
+### Step 4: Index Your Sessions
 
 ```bash
-jacked install
+jacked backfill        # Index all existing sessions
+jacked status          # Verify it's working
+jacked search "something you worked on before"
 ```
 
-This installs:
-- All agents to `~/.claude/agents/`
-- All commands to `~/.claude/commands/`
-- The `/jacked` skill to `~/.claude/skills/`
-- Auto-index hook (indexes sessions after every Claude response)
+**Note:** If you only want the agents and commands (not the session search), you can manually copy just those files from the repo without setting up Qdrant. But the main `jacked` functionality requires it.
 
-Restart Claude Code after running this.
+---
 
-### Index Your Sessions
+## Uninstall
 
+**One-liner:**
 ```bash
-jacked backfill        # Index all existing sessions
-jacked status          # Verify it's working
-jacked search "something you worked on before"
+curl -sSL https://raw.githubusercontent.com/jackneil/claude-jacked/master/uninstall.sh | bash
 ```
 
-**Note:** If you only want the agents and commands (not the session search), you can manually copy just those files from the repo without setting up Qdrant. But the main `jacked` functionality requires it.
+**Or manual two-step:**
+```bash
+jacked uninstall && pipx uninstall claude-jacked
+```
+
+This removes hooks, skill, agents, and commands from Claude Code. Your Qdrant index is preserved if you reinstall later.
 
 ---
 
@@ -243,13 +284,16 @@ jacked search "query"              # Semantic search with multi-factor ranking
 jacked search "query" --mine       # Only your sessions
 jacked search "query" --user sarah # Only this teammate's sessions
 jacked search "query" --repo path  # Boost results from this repo
+jacked search "query" --type chunk # Search full transcript chunks only
 
-jacked list                        # List indexed sessions
-jacked list --repo myproject       # Filter by repo name
+jacked sessions                        # List indexed sessions
+jacked sessions --repo myproject       # Filter by repo name
 
-jacked retrieve <session_id>       # Get full transcript
-jacked retrieve <id1> <id2>        # Get multiple transcripts
-jacked retrieve <id> --summary     # Get summary only
+jacked retrieve <session_id>       # Smart mode: plan + summaries + labels
+jacked retrieve <id> --mode full   # Get full transcript (huge)
+jacked retrieve <id> --mode plan   # Just the plan file
+jacked retrieve <id> --mode agents # Just subagent summaries
+jacked retrieve <id> --mode labels # Just summary labels (tiny)
 
 jacked index /path/to/session.jsonl --repo /path  # Index specific session
 jacked backfill                    # Index all existing sessions
@@ -257,7 +301,11 @@ jacked backfill --force            # Re-index everything
 
 jacked status                      # Check Qdrant connectivity
 jacked delete <session_id>         # Remove session from index
+jacked cleardb                     # Delete all YOUR indexed data (requires confirmation)
 jacked install                     # Install hook + skill + agents + commands
+jacked install --sounds            # Also install sound notification hooks
+jacked uninstall                   # Remove hook + skill + agents + commands
+jacked uninstall --sounds          # Remove only sound hooks
 jacked configure                   # Show config help
 jacked configure --show            # Show current config values
 ```
@@ -288,6 +336,44 @@ jacked configure --show            # Show current config values
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Smart Retrieval (v0.2.6+)
+
+Sessions are indexed with multiple content types for efficient retrieval:
+
+| Content Type | What It Contains | Token Cost |
+|--------------|------------------|------------|
+| `plan` | Full implementation strategy from plan files | ~500-2K |
+| `subagent_summary` | Rich summaries from exploration/planning agents | ~200-500 each |
+| `summary_label` | Tiny chapter titles from auto-compaction | ~10-20 each |
+| `user_message` | First 5 user messages for intent matching | ~100-500 each |
+| `chunk` | Full transcript chunks (legacy) | ~2K each |
+
+**Retrieval Modes:**
+
+| Mode | What's Included | When to Use |
+|------|-----------------|-------------|
+| `smart` | Plan + agent summaries + labels + user msgs | Default - best balance (~5-10K tokens) |
+| `plan` | Just the plan file | Quick strategic overview |
+| `labels` | Just summary labels | Quick topic check (tiny) |
+| `agents` | All subagent summaries | Deep dive into exploration results |
+| `full` | Everything including transcript | Need full details (50-200K tokens - use sparingly!) |
+
+**Why smart mode?** Full transcripts can be 50-200K tokens, which blows up your context window. Smart mode returns the highest-value content (~5-10K tokens) so you get the key decisions and plans without the bloat.
+
+**Staleness warnings:** When loading old context, you'll see warnings based on age:
+- 7-30 days: "Code may have changed since this session"
+- 30-90 days: "Treat as starting point for WHERE to look, not WHAT to do"
+- 90+ days: "Historical reference only - verify everything"
+
+### Re-indexing After Upgrade
+
+If you upgraded from a version before v0.2.6, your existing sessions are indexed as full transcript chunks only. To get smart retrieval:
+
+```bash
+jacked cleardb   # Wipes YOUR data (not teammates), requires typing "DELETE MY DATA"
+jacked backfill  # Re-index with new content types
+```
+
 ---
 
 ## Configuration
@@ -337,6 +423,25 @@ The `jacked install` command adds this to `~/.claude/settings.json`:
 }
 ```
 
+### Sound Notifications
+
+Add audio feedback when Claude needs attention or completes a task:
+
+```bash
+jacked install --sounds
+```
+
+This adds hooks that play:
+- **Notification sound** when Claude requests user input
+- **Completion sound** when Claude finishes a task
+
+Works on Windows (PowerShell), macOS (afplay), Linux (paplay), and WSL. Falls back to terminal bell on unsupported systems.
+
+To remove only sound hooks (keep everything else):
+```bash
+jacked uninstall --sounds
+```
+
 ---
 
 ## Security Warning
@@ -352,6 +457,8 @@ Recommendations:
 - Keep your Qdrant API key secure
 - Consider self-hosting Qdrant for sensitive work
 
+**Data isolation:** The `cleardb` command only deletes data belonging to the current user (based on `JACKED_USER_NAME`). Teammates' data is unaffected.
+
 ---
 
 ## Troubleshooting