claude-code-tools 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

claude_code_tools/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Tools - Collection of utilities for Claude Code."""
 
-__version__ = "0.1.9"
+__version__ = "0.1.11"

claude_code_tools/tmux_cli_controller.py

@@ -11,7 +11,74 @@ from typing import Optional, List, Dict, Tuple, Callable, Union
 import json
 import os
 import hashlib
-from pathlib import Path
+import importlib.resources
+
+
+def _load_help_text():
+    """Load help text from the package's docs directory."""
+    try:
+        # For development, try to load from the actual file system first
+        import pathlib
+        module_dir = pathlib.Path(__file__).parent
+        # Try looking in the parent directory (repo root) for docs
+        docs_file = module_dir.parent / 'docs' / 'tmux-cli-instructions.md'
+        if docs_file.exists():
+            return docs_file.read_text(encoding='utf-8')
+        
+        # For installed packages, use importlib.resources
+        if hasattr(importlib.resources, 'files'):
+            # Python 3.9+ style
+            import importlib.resources as resources
+            
+            # Try different possible locations for the docs
+            # 1. Try docs as a subdirectory within the package
+            try:
+                help_file = resources.files('claude_code_tools') / 'docs' / 'tmux-cli-instructions.md'
+                if help_file.is_file():
+                    return help_file.read_text(encoding='utf-8')
+            except:
+                pass
+            
+            # 2. Try accessing parent package to find docs at root level
+            try:
+                # This assumes docs/ is packaged at the same level as claude_code_tools/
+                package_root = resources.files('claude_code_tools').parent
+                help_file = package_root / 'docs' / 'tmux-cli-instructions.md'
+                if help_file.is_file():
+                    return help_file.read_text(encoding='utf-8')
+            except:
+                pass
+        
+        # Try pkg_resources as another fallback
+        try:
+            import pkg_resources
+            # Try different paths
+            for path in ['docs/tmux-cli-instructions.md', '../docs/tmux-cli-instructions.md']:
+                try:
+                    return pkg_resources.resource_string(
+                        'claude_code_tools', path
+                    ).decode('utf-8')
+                except:
+                    continue
+        except:
+            pass
+            
+    except Exception as e:
+        pass
+    
+    # If all else fails, return a basic help message
+    return """# tmux-cli Instructions
+
+Error: Could not load full documentation.
+
+Basic usage:
+- tmux-cli launch "command" - Launch a CLI application
+- tmux-cli send "text" --pane=PANE_ID - Send input to a pane
+- tmux-cli capture --pane=PANE_ID - Capture output from a pane
+- tmux-cli kill --pane=PANE_ID - Kill a pane
+- tmux-cli help - Display full help
+
+For full documentation, see docs/tmux-cli-instructions.md in the package repository."""
 
 
 class TmuxCLIController:
@@ -657,10 +724,6 @@ class CLI:
     
     def help(self):
         """Display tmux-cli usage instructions."""
-        # Find the instructions file relative to this module
-        module_dir = Path(__file__).parent.parent
-        instructions_file = module_dir / "docs" / "tmux-cli-instructions.md"
-        
         # Add mode-specific header
         mode_info = f"\n{'='*60}\n"
         if self.mode == 'local':
@@ -670,12 +733,7 @@ class CLI:
         mode_info += f"{'='*60}\n"
         
         print(mode_info)
-        
-        if instructions_file.exists():
-            print(instructions_file.read_text())
-        else:
-            print("Error: tmux-cli-instructions.md not found")
-            print(f"Expected location: {instructions_file}")
+        print(_load_help_text())
         
         if self.mode == 'remote':
             print("\n" + "="*60)

claude_code_tools/tmux_remote_controller.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Remote Tmux Controller - Stub implementation
+This is a minimal stub to prevent import errors when tmux-cli is used outside tmux.
+"""
+
+import subprocess
+from typing import Optional, List, Dict
+
+
+class RemoteTmuxController:
+    """Stub implementation of RemoteTmuxController to prevent import errors."""
+    
+    def __init__(self, session_name: str = "remote-cli-session"):
+        """Initialize with session name."""
+        self.session_name = session_name
+        print(f"Warning: RemoteTmuxController is not fully implemented.")
+        print(f"Remote mode functionality is currently unavailable.")
+        print(f"Please use tmux-cli from inside a tmux session for full functionality.")
+    
+    def list_panes(self) -> List[Dict[str, str]]:
+        """Return empty list."""
+        return []
+    
+    def launch_cli(self, command: str, name: Optional[str] = None) -> Optional[str]:
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def send_keys(self, text: str, pane_id: Optional[str] = None, enter: bool = True,
+                  delay_enter: bool = True):
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def capture_pane(self, pane_id: Optional[str] = None, lines: Optional[int] = None) -> str:
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def wait_for_idle(self, pane_id: Optional[str] = None, idle_time: float = 2.0,
+                     check_interval: float = 0.5, timeout: Optional[int] = None) -> bool:
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def send_interrupt(self, pane_id: Optional[str] = None):
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def send_escape(self, pane_id: Optional[str] = None):
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def kill_window(self, window_id: Optional[str] = None):
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def attach_session(self):
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def cleanup_session(self):
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def list_windows(self) -> List[Dict[str, str]]:
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")
+    
+    def _resolve_pane_id(self, pane: Optional[str]) -> Optional[str]:
+        """Not implemented."""
+        raise NotImplementedError("Remote mode is not available. Please use tmux-cli from inside tmux.")

{claude_code_tools-0.1.9.dist-info → claude_code_tools-0.1.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 0.1.9
+Version: 0.1.11
 Summary: Collection of tools for working with Claude Code
 Requires-Python: >=3.11
 Requires-Dist: click>=8.0.0

claude_code_tools-0.1.11.dist-info/RECORD

@@ -0,0 +1,13 @@
+claude_code_tools/__init__.py,sha256=N-T6rVgTsM1TgWAxNFB1nkUl44M9mxO3LWXGat-oZhM,90
+claude_code_tools/dotenv_vault.py,sha256=KPI9NDFu5HE6FfhQUYw6RhdR-miN0ScJHsBg0OVG61k,9617
+claude_code_tools/find_claude_session.py,sha256=k7K-lwHY2aEWEgUw92T_NT3ds6cGql9eq1CKQikig68,21295
+claude_code_tools/tmux_cli_controller.py,sha256=0PqWBhITw74TtOKAfiUJMyHEFVOlLp4sEYmSlDHyznc,27482
+claude_code_tools/tmux_remote_controller.py,sha256=uK9lJKrNz7_NeV1_V3BM-q0r6sRVmYfOR8H3zo5hfH8,3220
+docs/claude-code-tmux-tutorials.md,sha256=S-9U3a1AaPEBPo3oKpWuyOfKK7yPFOIu21P_LDfGUJk,7558
+docs/find-claude-session.md,sha256=fACbQP0Bj5jqIpNWk0lGDOQQaji-K9Va3gUv2RA47VQ,4284
+docs/tmux-cli-instructions.md,sha256=lQqKTI-uhH-EdU9P4To4GC10WJjj3VllAW4cxd8jfj8,4167
+docs/vault-documentation.md,sha256=5XzNpHyhGU38JU2hKEWEL1gdPq3rC2zBg8yotK4eNF4,3600
+claude_code_tools-0.1.11.dist-info/METADATA,sha256=bOjivMZ6Ozi5fOQMhmVsK0J9B21cvHtE9UDxF9Md1Mo,9767
+claude_code_tools-0.1.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+claude_code_tools-0.1.11.dist-info/entry_points.txt,sha256=yUTZlZ2jteoUZ9bGPvZKI9tjmohPDhRk1fovu5pZACM,181
+claude_code_tools-0.1.11.dist-info/RECORD,,

docs/claude-code-tmux-tutorials.md

@@ -0,0 +1,105 @@
+# Advanced tmux + Claude Code Integration Resources
+
+Based on comprehensive research across multiple platforms, here's a curated collection of resources specifically addressing advanced tmux techniques and integration strategies with Claude Code. The findings reveal a sophisticated ecosystem with tools, workflows, and configuration strategies that go well beyond basic usage.
+
+## Essential Written Resources
+
+### Official Documentation and Team Insights
+
+**Claude Code Best Practices - Anthropic** (2024-2025)  
+https://www.anthropic.com/engineering/claude-code-best-practices  
+The official best practices document explicitly covers tmux integration for managing multiple Claude Code sessions. Key insights include workflow patterns for composing Claude Code into broader workflows with tmux for window and session management.
+
+**Latent Space Podcast - Claude Code Team Interview** (2024)  
+https://www.latent.space/p/claude-code  
+Direct insights from Boris Cherny and Cat Wu (Claude Code creators) discussing how "a lot of people use code with tmux to manage a bunch of windows and sessions happening in parallel." They emphasize the Unix utility philosophy and intentional design decisions around tmux compatibility.
+
+### Advanced Technical Tutorials
+
+**"Vibe Coding Anytime, Anywhere with tmux, Tailscale, and Claude Code"** by Nuttakit Kundum (July 2025)  
+https://nuttakitkundum.medium.com/vibe-coding-anytime-anywhere-with-tmux-tailscale-and-claude-code-fda01f3c5cd2  
+Demonstrates sophisticated session persistence workflows, showing how to maintain Claude Code sessions across devices using tmux. Covers mobile development with Galaxy Fold, SSH workflows, and tmux pane management for remote coding.
+
+**"LLM Codegen go Brrr – Parallelization with Git Worktrees and Tmux"** - DEV Community (2024)  
+https://dev.to/skeptrune/llm-codegen-go-brrr-parallelization-with-git-worktrees-and-tmux-2gop  
+Comprehensive guide on advanced parallelization techniques using Git worktrees and tmux to manage multiple Claude Code instances simultaneously. Includes pain points, manual workflows, and proposed automation solutions.
+
+**"How to automate development journaling with Claude Code"** by Takuya/Devas (June 2025)  
+https://www.devas.life/how-to-automate-development-journaling-with-claude-code/  
+In-depth integration guide combining Claude Code with tmux and neovim, including MCP integration and automated workflows. Shows building a RAG system with sophisticated tmux configurations.
+
+### Japanese Advanced Resources (Zenn Platform)
+
+The Japanese developer community has produced particularly sophisticated tmux + Claude Code resources:
+
+**"Claude Codeを並列組織化してClaude Code 'Company'にするtmuxコマンド集"** by Kazuph  
+https://zenn.dev/kazuph/articles/beb87d102bd4f5  
+Advanced tmux command collection for organizing multiple Claude Code instances into a "company" structure with boss-worker relationships using tmux panes. Includes orchestration commands and multi-agent coordination patterns.
+
+**"Claude Code Maxで実現する完全自動並列開発システム"** by Studio Prairie  
+https://zenn.dev/studio_prairie/articles/90f5fc48a6dea7  
+Demonstrates a fully automated parallel development system using Claude Code Max with tmux orchestration, showing advanced workflow automation techniques.
+
+## Video Resources
+
+While video content is limited, these stand out for advanced techniques:
+
+**"Claude Code / OpenCode + T-Mux + Worktrees: This SELF-SPAWNING AI Coder TEAM is INSANITY!"**  
+https://www.youtube.com/watch?v=bWKHPelgNgs  
+11-minute demonstration of combining Claude Code with tmux and Git Worktrees to create a self-spawning AI coder team. Covers task claiming systems, agent-spawn workflow automation, and monitoring multiple AI agents in tmux sessions.
+
+**"【AI組織実現‼️Claude Code Organization】現役エンジニアが「5人のAIが勝手に開発する会社」の作り方を解説！"**  
+https://www.youtube.com/watch?v=Qxus36eijkM  
+Japanese tutorial demonstrating advanced AI organization with hierarchical agent structures (President → Manager → Worker) using tmux session management and mouse operation configuration.
+
+## Production-Ready Tools and GitHub Projects
+
+### Claude Squad - Complete Multi-Agent Management
+https://github.com/smtg-ai/claude-squad  
+The most mature solution for managing multiple Claude Code agents. Uses tmux for isolated terminal sessions with git worktrees for separate codebases. Features include TUI interface, auto-accept mode for background tasks, and support for multiple AI agents (Claude Code, Aider, Codex).
+
+### tmux-mcp - Model Context Protocol Server
+https://github.com/nickgnd/tmux-mcp  
+Enables Claude Desktop to interact programmatically with tmux sessions. Features include listing/searching tmux sessions, viewing and navigating windows/panes, executing commands, and creating new sessions. Essential for deep tmux integration.
+
+### Advanced Configuration Scripts
+
+**Task Master Agent Spawner**  
+https://gist.github.com/worksfornow/df0cb6c4f6fd4966cd17133bc711fd20  
+Sophisticated Claude Code slash command for parallel task delegation. Creates multiple worktrees and launches Claude agents in tmux sessions with automated status tracking and branch management.
+
+## Key Integration Patterns and Workflows
+
+### Multi-Agent Parallelization Pattern
+- Use git worktrees + tmux sessions for parallel agent execution
+- Each agent gets an isolated directory and tmux session
+- Example command: `tmux new-session -d -s "agent-<task_id>" -c "worktrees/<feature_name>" claude`
+
+### Terminal Orchestration Pattern
+Brian P. Hogan's recommendation: "Use tmux. Have a pane with Claude Code and use tmux with a big scrollback buffer. Then have another pane where you run Git commands and other shell commands."
+
+### Session Persistence Pattern
+- Implement persistent tmux sessions for Claude Code context preservation
+- Tools like "claunch" provide project-specific session management
+- Critical for maintaining context across disconnections
+
+### MCP Integration Pattern
+- Use Model Context Protocol servers for programmatic tmux control
+- tmux-mcp server enables Claude Desktop to read and control tmux sessions
+- Allows AI assistants to observe and interact with terminal sessions
+
+## Advanced Techniques Summary
+
+The resources reveal several sophisticated techniques:
+
+1. **Hierarchical Agent Organization**: Using tmux panes to create boss-worker relationships between multiple Claude Code instances
+2. **Automated Worktree Management**: Scripts that automatically create git worktrees and spawn Claude Code instances in dedicated tmux sessions
+3. **Session Orchestration**: Tools for managing dozens of parallel Claude Code sessions with monitoring and merging capabilities
+4. **Mobile Development Workflows**: Using tmux for persistent remote Claude Code sessions accessible from mobile devices
+5. **Custom Slash Commands**: Creating project-specific delegation commands that leverage tmux for task distribution
+
+## Notable Gaps
+
+The research reveals that while basic tmux + Claude Code integration is well-documented, there's still room for more comprehensive English-language video tutorials covering complex tmux layout management, detailed multiplexing features, and live coding sessions with sophisticated setups.
+
+These resources represent the cutting edge of tmux + Claude Code integration, focusing on advanced techniques that leverage tmux's multiplexing capabilities to enhance Claude Code workflows significantly beyond basic usage.

docs/find-claude-session.md

@@ -0,0 +1,149 @@
+# find-claude-session Documentation
+
+## Overview
+
+`find-claude-session` is a command-line utility that searches through Claude Code session files to find sessions containing specific keywords. It provides an interactive UI for session selection and automatic resumption.
+
+## Features
+
+- **Interactive UI**: Rich terminal interface showing session previews
+- **Global Search**: Search across all Claude projects with `-g/--global` flag
+- **Smart Selection**: Automatically resume sessions with `claude -r`
+- **Cross-project Navigation**: Switch to different project directories when needed
+- **Shell Integration**: Persistent directory changes with the `fcs` wrapper function
+
+## Usage
+
+### Basic Command
+```bash
+find-claude-session "keyword1,keyword2,keyword3"
+```
+- Accepts comma-separated keywords as a single argument
+- Searches for sessions containing ALL keywords (AND operation)
+- Case-insensitive matching
+
+### Global Search
+```bash
+find-claude-session "keywords" --global
+find-claude-session "keywords" -g
+```
+
+### Shell Function (Recommended)
+```bash
+# Add to .bashrc/.zshrc
+fcs() { eval "$(find-claude-session --shell "$@" | sed '/^$/d')"; }
+
+# Usage
+fcs "keywords"         # Local search
+fcs "keywords" -g      # Global search
+```
+
+## How It Works
+
+1. **Directory Mapping**:
+   - Current directory: `/Users/username/projects/myapp`
+   - Maps to: `~/.claude/projects/-Users-username-projects-myapp/`
+   - Rule: Replace all `/` with `-` in the path
+
+2. **Search Process**:
+   - Reads JSONL files line by line (memory efficient)
+   - Checks if ALL keywords exist in the session
+   - Sorts by modification time (newest first)
+   - Displays top 10 matches in interactive UI
+
+3. **Session Selection**:
+   - Shows session ID, project name, date, and preview
+   - Enter a number (1-10) to select
+   - Automatically runs `claude -r SESSION_ID`
+   - For cross-project sessions, changes directory first
+
+## Installation
+
+### Via uv tool
+```bash
+uv tool install git+https://github.com/username/claude-code-tools
+```
+
+### For Development
+```bash
+git clone https://github.com/username/claude-code-tools
+cd claude-code-tools
+make install  # Installs in editable mode
+```
+
+## Technical Details
+
+### File Format
+Claude Code stores sessions as JSONL files:
+- Each line is a separate JSON object
+- Contains messages, timestamps, and metadata
+- Located in `~/.claude/projects/PROJECT_PATH/`
+
+### Dependencies
+- Python 3.11+
+- click (CLI framework)
+- rich (optional, for interactive UI)
+
+### Performance
+- Memory efficient: streams files line by line
+- Early exit when all keywords found
+- Parallel search in global mode
+- Progress indicator for large searches
+
+## Advanced Features
+
+### Progress Indicators
+- Shows search progress in global mode
+- Displays number of projects searched
+- Real-time match counter
+
+### Fallback Mode
+If `rich` library is not available:
+- Falls back to simple text interface
+- Still fully functional
+- Plain numbered list for selection
+
+### Cross-project Sessions
+When selecting a session from a different project:
+1. Prompts to change directory
+2. Changes to project directory
+3. Resumes the session
+4. With `fcs` wrapper, directory change persists
+
+## Examples
+
+```bash
+# Find sessions about a specific error
+fcs "TypeError,undefined,function"
+
+# Find sessions about a feature across all projects
+fcs "authentication,JWT,middleware" -g
+
+# Find sessions with specific library discussions
+fcs "langroid,MCP,sampling"
+
+# Direct usage without shell function
+find-claude-session "docker,compose" --global
+```
+
+## Tips and Tricks
+
+1. **Keyword Selection**: Use specific, unique terms for better results
+2. **Multiple Keywords**: More keywords = more precise matches
+3. **Global Search**: Use `-g` when you can't remember which project
+4. **Shell Function**: Always use `fcs` for better workflow
+5. **Recent Sessions**: Results are sorted by modification time
+
+## Troubleshooting
+
+### No Claude directory found
+- Ensure you're in a directory with Claude Code history
+- Check if `~/.claude/projects/` exists
+
+### No matches found
+- Try fewer or more general keywords
+- Use global search (`-g`) to search all projects
+
+### Directory changes don't persist
+- Make sure you're using the `fcs` shell function
+- Check that the function is properly sourced in your shell config

docs/tmux-cli-instructions.md

@@ -0,0 +1,164 @@
+# tmux-cli Instructions
+
+A command-line tool for controlling CLI applications running in tmux panes/windows.
+Automatically detects whether you're inside or outside tmux and uses the appropriate mode.
+
+## Auto-Detection
+- **Inside tmux (Local Mode)**: Manages panes in your current tmux window
+- **Outside tmux (Remote Mode)**: Creates and manages a separate tmux session with windows
+
+## Prerequisites
+- tmux must be installed
+- The `tmux-cli` command must be available (installed via `uv tool install`)
+
+## ⚠️ IMPORTANT: Always Launch a Shell First!
+
+**Always launch zsh first** to prevent losing output when commands fail:
+```bash
+tmux-cli launch "zsh"  # Do this FIRST
+tmux-cli send "your-command" --pane=%48  # Then run commands
+```
+
+If you launch a command directly and it errors, the pane closes immediately and you lose all output!
+
+## Core Commands
+
+### Launch a CLI application
+```bash
+tmux-cli launch "command"
+# Example: tmux-cli launch "python3"
+# Returns: pane ID (e.g., %48)
+```
+
+### Send input to a pane
+```bash
+tmux-cli send "text" --pane=PANE_ID
+# Example: tmux-cli send "print('hello')" --pane=%48
+
+# By default, there's a 1-second delay between text and Enter.
+# This ensures compatibility with various CLI applications.
+
+# To send without Enter:
+tmux-cli send "text" --pane=PANE_ID --enter=False
+
+# To send immediately without delay:
+tmux-cli send "text" --pane=PANE_ID --delay-enter=False
+
+# To use a custom delay (in seconds):
+tmux-cli send "text" --pane=PANE_ID --delay-enter=0.5
+```
+
+### Capture output from a pane
+```bash
+tmux-cli capture --pane=PANE_ID
+# Example: tmux-cli capture --pane=%48
+```
+
+### List all panes
+```bash
+tmux-cli list_panes
+# Returns: JSON with pane IDs, indices, and status
+```
+
+### Kill a pane
+```bash
+tmux-cli kill --pane=PANE_ID
+# Example: tmux-cli kill --pane=%48
+
+# SAFETY: You cannot kill your own pane - this will give an error
+# to prevent accidentally terminating your session
+```
+
+### Send interrupt (Ctrl+C)
+```bash
+tmux-cli interrupt --pane=PANE_ID
+```
+
+### Send escape key
+```bash
+tmux-cli escape --pane=PANE_ID
+# Useful for exiting Claude or vim-like applications
+```
+
+### Wait for pane to become idle
+```bash
+tmux-cli wait_idle --pane=PANE_ID
+# Waits until no output changes for 2 seconds (default)
+
+# Custom idle time and timeout:
+tmux-cli wait_idle --pane=PANE_ID --idle-time=3.0 --timeout=60
+```
+
+### Get help
+```bash
+tmux-cli help
+# Displays this documentation
+```
+
+## Typical Workflow
+
+1. **ALWAYS launch a shell first** (prefer zsh) - this prevents losing output on errors:
+   ```bash
+   tmux-cli launch "zsh"  # Returns pane ID - DO THIS FIRST!
+   ```
+
+2. Run your command in the shell:
+   ```bash
+   tmux-cli send "python script.py" --pane=%48
+   ```
+
+3. Interact with the program:
+   ```bash
+   tmux-cli send "user input" --pane=%48
+   tmux-cli capture --pane=%48  # Check output
+   ```
+
+4. Clean up when done:
+   ```bash
+   tmux-cli kill --pane=%48
+   ```
+
+## Remote Mode Specific Commands
+
+These commands are only available when running outside tmux:
+
+### Attach to session
+```bash
+tmux-cli attach
+# Opens the managed tmux session to view live
+```
+
+### Clean up session
+```bash
+tmux-cli cleanup
+# Kills the entire managed session and all its windows
+```
+
+### List windows
+```bash
+tmux-cli list_windows
+# Shows all windows in the managed session
+```
+
+## Tips
+- Always save the pane/window ID returned by `launch`
+- Use `capture` to check the current state before sending input
+- In local mode: Pane IDs can be like `%48` or pane indices like `1`, `2`
+- In remote mode: Window IDs can be indices like `0`, `1` or full form like `session:0.0`
+- If you launch a command directly (not via shell), the pane/window closes when
+  the command exits
+- **IMPORTANT**: The tool prevents you from killing your own pane/window to avoid
+  accidentally terminating your session
+
+## Avoiding Polling
+Instead of repeatedly checking with `capture`, use `wait_idle`:
+```bash
+# Send command to a CLI application
+tmux-cli send "analyze this code" --pane=%48
+
+# Wait for it to finish (no output for 3 seconds)
+tmux-cli wait_idle --pane=%48 --idle-time=3.0
+
+# Now capture the result
+tmux-cli capture --pane=%48
+```

docs/vault-documentation.md

@@ -0,0 +1,161 @@
+# Vault - Encrypted .env Backup Manager
+
+## Overview
+
+The `vault` tool provides centralized, encrypted backup for `.env` files across
+all your projects. It uses SOPS (Secrets OPerationS) with GPG encryption to
+securely store your environment variables in a central location at
+`~/Git/dotenvs/`.
+
+## How It Works
+
+1. **Central Storage**: All encrypted backups are stored in `~/Git/dotenvs/`
+2. **Project-based**: Each project's `.env` file is backed up with the project
+   directory name (e.g., `myproject.env.encrypt`)
+3. **GPG Encryption**: Uses your GPG key to encrypt/decrypt files
+4. **Smart Sync**: Automatically detects which version is newer and syncs
+   appropriately
+5. **Safety First**: Always creates timestamped backups before overwriting
+
+## Requirements
+
+- GPG key configured on your system
+- SOPS installed (`brew install sops` on macOS)
+
+## Commands
+
+### vault sync
+
+Smart synchronization that automatically detects the sync direction:
+- If only local `.env` exists → encrypts to vault
+- If only vault backup exists → decrypts to local
+- If local is newer → encrypts to vault (with confirmation)
+- If vault is newer → decrypts to local (with confirmation)
+
+```bash
+vault sync           # Auto-detect direction
+vault sync --push    # Force encrypt (local → vault)
+vault sync --pull    # Force decrypt (vault → local)
+```
+
+### vault encrypt
+
+Explicitly encrypt your local `.env` file to the centralized vault:
+
+```bash
+vault encrypt
+```
+
+Features:
+- Creates timestamped backup if encrypted file already exists
+- Requires confirmation before overwriting existing backups
+
+### vault decrypt
+
+Explicitly decrypt from the centralized vault to local `.env`:
+
+```bash
+vault decrypt
+```
+
+Features:
+- Creates timestamped backup of current `.env` before overwriting
+- Warns if local `.env` is newer than backup
+- Requires confirmation in case of conflicts
+
+### vault list
+
+List all encrypted backups in the central vault:
+
+```bash
+vault list
+```
+
+Shows all `.env.encrypt` files in `~/Git/dotenvs/` with their sizes.
+
+### vault status
+
+Show detailed status for the current project:
+
+```bash
+vault status
+```
+
+Displays:
+- Whether local `.env` exists
+- Whether backup exists
+- Which version is newer (with timestamps)
+- Sync status (in sync, local newer, backup newer, etc.)
+
+## Workflow Examples
+
+### Initial Setup
+
+```bash
+cd myproject
+# Create your .env file with secrets
+vault encrypt  # Backup to central vault
+```
+
+### Cloning a Project
+
+```bash
+git clone https://github.com/user/project
+cd project
+vault decrypt  # Restore .env from central vault
+```
+
+### Regular Development
+
+```bash
+# After modifying .env
+vault sync  # Automatically encrypts to vault
+
+# On a different machine
+vault sync  # Automatically decrypts newer version
+```
+
+### Conflict Resolution
+
+When both local and vault versions exist but differ:
+
+```bash
+vault status  # Check which is newer
+vault sync --push  # Force local → vault
+vault sync --pull  # Force vault → local
+```
+
+## Security Notes
+
+- Files are encrypted using your GPG key
+- Only you can decrypt the files (with your private key)
+- The central vault (`~/Git/dotenvs/`) should be included in your backups
+- Consider version controlling the encrypted files for additional safety
+
+## Troubleshooting
+
+### "No GPG key found"
+
+Generate a GPG key:
+```bash
+gpg --gen-key
+```
+
+### "SOPS not found"
+
+Install SOPS:
+```bash
+# macOS
+brew install sops
+
+# Linux
+# Download from https://github.com/mozilla/sops/releases
+```
+
+### Permission Issues
+
+Ensure you have write access to `~/Git/dotenvs/`:
+```bash
+mkdir -p ~/Git/dotenvs
+chmod 700 ~/Git/dotenvs
+```

claude_code_tools-0.1.9.dist-info/RECORD

@@ -1,8 +0,0 @@
-claude_code_tools/__init__.py,sha256=A9bCZil9tXYE103gMBo_m91Z8AHthQFBebD-oJ51A_E,89
-claude_code_tools/dotenv_vault.py,sha256=KPI9NDFu5HE6FfhQUYw6RhdR-miN0ScJHsBg0OVG61k,9617
-claude_code_tools/find_claude_session.py,sha256=k7K-lwHY2aEWEgUw92T_NT3ds6cGql9eq1CKQikig68,21295
-claude_code_tools/tmux_cli_controller.py,sha256=lemoz1UljbXMHQRdP3475K8MEqBS67TiiVqoEJ-dadc,25272
-claude_code_tools-0.1.9.dist-info/METADATA,sha256=Q9US7C7xOaXcL-mUAqlTD0UvCxor66OOhQz46WlNZP0,9766
-claude_code_tools-0.1.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-claude_code_tools-0.1.9.dist-info/entry_points.txt,sha256=yUTZlZ2jteoUZ9bGPvZKI9tjmohPDhRk1fovu5pZACM,181
-claude_code_tools-0.1.9.dist-info/RECORD,,