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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-jacked
-Version: 0.2.3
+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,9 +30,25 @@ 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
 
-> 📋 [View on GitHub](https://github.com/jackneil/claude-jacked#install-copy-this-into-claude-code) for copy button
+**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:
@@ -56,12 +72,11 @@ 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
+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 hook/agents not installed: jacked install
-8. If no indexed sessions: jacked backfill
+7. If no indexed sessions: jacked backfill
 
 VERIFY: jacked status && jacked configure --show
 
@@ -107,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):
 
@@ -119,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:
 
@@ -132,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.
 
 ---
 
@@ -281,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
@@ -295,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
 ```
@@ -326,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
@@ -375,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
@@ -390,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.3 → claude_jacked-0.2.7}/README.md

@@ -2,9 +2,25 @@
 
 Supercharge your Claude Code workflow with cross-machine session search, review agents, and workflow commands.
 
-## Install (Copy This Into Claude Code)
+## Quick Install
 
-> 📋 [View on GitHub](https://github.com/jackneil/claude-jacked#install-copy-this-into-claude-code) for copy button
+**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:
@@ -28,12 +44,11 @@ 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
+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 hook/agents not installed: jacked install
-8. If no indexed sessions: jacked backfill
+7. If no indexed sessions: jacked backfill
 
 VERIFY: jacked status && jacked configure --show
 
@@ -79,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):
 
@@ -91,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:
 
@@ -104,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.
 
 ---
 
@@ -253,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
@@ -267,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
 ```
@@ -298,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
@@ -347,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
@@ -362,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