claude-code-tools 1.0.10__py3-none-any.whl

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/lmsh.md

@@ -0,0 +1,70 @@
+# lmsh
+
+A fast, minimal natural language shell interface that translates conversational commands into editable shell commands.
+
+## What it does
+
+Type natural language → Get an editable shell command → Review/modify → Execute
+
+Example:
+```bash
+$ lmsh
+> show me all python files modified today
+find . -name "*.py" -mtime 0  # <-- Editable command appears, press Enter to run
+```
+
+## Installation
+
+```bash
+# Install from crates.io (easiest, requires Rust)
+cargo install lmsh
+
+# Or build from source
+cd lmsh/
+cargo build --release
+cp target/release/lmsh ~/.cargo/bin/
+# Or: make lmsh-install
+```
+
+Note: Ensure `~/.cargo/bin` is in your PATH.
+
+## Usage
+
+```bash
+lmsh                           # Interactive mode (uses Claude/Haiku by default)
+lmsh "show me python files"    # Translate, edit, execute, then interactive mode
+lmsh --agent claude            # Explicitly use Claude (default)
+lmsh --agent codex             # Use Codex instead
+lmsh --version                 # Version info
+```
+
+## Features
+
+- **Editable commands** - Review and modify before execution
+- **Fast startup** - Optimized Rust binary (~1ms)
+- **Multiple AI agents** - Choose between Claude (default) or Codex for command translation
+- **Shell preservation** - Maintains your shell environment and aliases
+- **Clean output** - PTY-based execution with proper echo suppression (no garbled prompts or ANSI codes)
+
+## Agent Selection
+
+lmsh supports two AI agents for translating natural language to shell commands:
+
+### Claude (default)
+- **Model**: Haiku (fast and efficient)
+- **Command**: `claude -p "<prompt>" --model haiku`
+- **Requirement**: Claude Code CLI must be installed and configured
+- **Best for**: General shell command translation with fast response times
+
+### Codex
+- **Model**: GPT-5 (advanced reasoning)
+- **Command**: `codex exec "<prompt>"`
+- **Requirement**: Codex CLI must be installed and configured
+- **Best for**: Complex command construction requiring advanced reasoning
+
+## Requirements
+
+- At least one of the following CLI tools:
+  - **Claude Code CLI** (`claude` command) - for default Claude agent
+  - **Codex CLI** (`codex` command) - for Codex agent
+- The translation step adds ~2-3s latency due to AI model inference time

docs/reddit-post.md

@@ -0,0 +1,55 @@
+# Made a tool that lets Claude Code control terminal apps - thought some of you might find it useful
+
+Hey everyone! I've been using Claude Code a lot lately and kept running into the same frustration - it couldn't interact with CLI applications that need user input. So I built something to fix that.
+
+## What it does
+
+It's basically like Playwright/Puppeteer but for the terminal. Claude Code can now:
+- Run interactive scripts and respond to prompts
+- Use debuggers like pdb to step through code
+- Launch and control other CLI apps
+- Even spin up another Claude Code instance to have it work as a sub-agent -- 
+  and unlike the built-in sub-agents, you can clearly see what's going on.
+
+[GIF PLACEHOLDER - Shows tmux-cli in action]
+
+## How it works
+
+The magic happens through tmux (terminal multiplexer). I created a tool called `tmux-cli` that gives Claude Code the ability to:
+- Launch apps in separate tmux panes
+- Send keystrokes to them
+- Capture their output
+- Wait for them to idle
+
+You don't need to know tmux commands - Claude Code handles everything. Just tell it what you want and it figures out the tmux stuff.
+
+## Real use cases I've found helpful
+
+- **Debugging**: Claude can now use pdb to step through Python code, examine variables, and help me understand program flow
+- **Testing interactive scripts**: No more manually entering test inputs - Claude handles it
+- **Spawn other Claudes**: I can have Claude launch another Claude instance to work on
+  a task and interact with it. And unlike the built-in sub-agents, it's fully visible.
+
+## Getting it
+
+If you want to try it:
+
+```bash
+# Install from PyPI
+uv tool install claude-code-tools
+
+# Or get latest from GitHub
+uv tool install git+https://github.com/pchalasani/claude-code-tools
+```
+
+Then add a snippet to your `~/.claude/CLAUDE.md` to let Claude Code know about tmux-cli.
+
+The repo also includes some other tools like encrypted .env backup and a Claude session finder, but tmux-cli is the main thing I wanted to share.
+
+## Not trying to oversell
+
+This isn't revolutionary or anything - it's just a practical tool that solved a real problem I kept hitting. If you work with Claude Code and interactive CLIs, you might find it useful too.
+
+Happy to answer questions or hear if anyone has similar tools they've built!
+
+Repo: https://github.com/pchalasani/claude-code-tools

docs/tmux-cli-instructions.md

@@ -0,0 +1,186 @@
+# 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`)
+
+## Pane Identification
+
+Panes can be specified in two simple ways:
+- Just the pane number (e.g., `2`) - refers to pane 2 in the current window
+- Full format: `session:window.pane` (e.g., `myapp:1.2`) - for any pane in any session
+
+## ⚠️ 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=2  # 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 identifier (e.g., session:window.pane format like myapp:1.2)
+```
+
+### Send input to a pane
+```bash
+tmux-cli send "text" --pane=PANE_ID
+# Example: tmux-cli send "print('hello')" --pane=3
+
+# 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=2
+```
+
+### List all panes
+```bash
+tmux-cli list_panes
+# Returns: JSON with pane IDs, indices, and status
+```
+
+### Show current tmux status
+```bash
+tmux-cli status
+# Shows current location and all panes in current window
+# Example output:
+#   Current location: myapp:1.2
+#   Panes in current window:
+#    * myapp:1.0       zsh                  zsh
+#      myapp:1.1       python3              python3  
+#      myapp:1.2       vim                  main.py
+```
+
+### Kill a pane
+```bash
+tmux-cli kill --pane=PANE_ID
+# Example: tmux-cli kill --pane=2
+
+# 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
+# Example: tmux-cli interrupt --pane=2
+```
+
+### Send escape key
+```bash
+tmux-cli escape --pane=PANE_ID
+# Example: tmux-cli escape --pane=3
+# Useful for exiting Claude or vim-like applications
+```
+
+### Wait for pane to become idle
+```bash
+tmux-cli wait_idle --pane=PANE_ID
+# Example: tmux-cli wait_idle --pane=2
+# Waits until no output changes for 2 seconds (default)
+
+# Custom idle time and timeout:
+tmux-cli wait_idle --pane=2 --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 identifier - DO THIS FIRST!
+   ```
+
+2. Run your command in the shell:
+   ```bash
+   tmux-cli send "python script.py" --pane=2
+   ```
+
+3. Interact with the program:
+   ```bash
+   tmux-cli send "user input" --pane=2
+   tmux-cli capture --pane=2  # Check output
+   ```
+
+4. Clean up when done:
+   ```bash
+   tmux-cli kill --pane=2
+   ```
+
+## 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 identifier returned by `launch`
+- Use `capture` to check the current state before sending input
+- Use `status` to see all available panes and their current state
+- In local mode: Pane identifiers can be session:window.pane format (like `myapp:1.2`) or just 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=2
+
+# Wait for it to finish (no output for 3 seconds)
+tmux-cli wait_idle --pane=2 --idle-time=3.0
+
+# Now capture the result
+tmux-cli capture --pane=2
+```

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
+```

node_ui/action_config.js

@@ -0,0 +1,72 @@
+// Shared action metadata for Node alt UI.
+// If a rich UI config becomes importable, we can swap this module to proxy it.
+
+export const ACTION_GROUPS = {
+  nonlaunch: 'nonlaunch',
+  launch: 'launch',
+};
+
+// Ordered actions matching rich UI intent: first non-launch, then launch.
+export const ACTIONS = [
+  {
+    value: 'path',
+    label: 'Show session file path',
+    group: ACTION_GROUPS.nonlaunch,
+    requiresPath: false,
+    hint: null,
+  },
+  {
+    value: 'copy',
+    label: 'Copy session file',
+    group: ACTION_GROUPS.nonlaunch,
+    requiresPath: true,
+    hint: 'Enter destination file or directory path.',
+  },
+  {
+    value: 'export',
+    label: 'Export to text file (.txt)',
+    group: ACTION_GROUPS.nonlaunch,
+    requiresPath: true,
+    hint: 'Leave blank to use default exported-sessions/<date>-session-<id>.txt',
+  },
+  {
+    value: 'query',
+    label: 'Query this session...',
+    group: ACTION_GROUPS.nonlaunch,
+    requiresPath: false,
+    requiresQuery: true,
+    hint: 'Ask any question about this session',
+    defaultQuery: 'Summarize what was accomplished in this session',
+  },
+  {
+    value: 'resume_menu',
+    label: 'Resume/trim session...',
+    group: ACTION_GROUPS.launch,
+    requiresPath: false,
+    hint: null,
+  },
+];
+
+// Resume submenu options (shown when 'resume_menu' is selected)
+// Note: 'continue' is the internal action name for what users see as "Rollover"
+export const RESUME_SUBMENU = [
+  {value: 'resume', label: 'Resume as-is'},
+  {value: 'clone', label: 'Clone session and resume clone'},
+  {value: 'suppress_resume', label: 'Trim + resume...'},
+  {value: 'smart_trim_resume', label: 'Smart trim + resume...'},
+  {value: 'continue', label: 'Rollover: handoff work to fresh session...'},
+];
+
+// Trim-only submenu (for aichat trim command)
+export const TRIM_SUBMENU = [
+  {value: 'suppress_resume', label: 'Trim + resume...'},
+  {value: 'smart_trim_resume', label: 'Smart trim + resume...'},
+];
+
+export function filteredActions(isSidechain = false) {
+  if (isSidechain) {
+    return ACTIONS.filter((a) => a.group === ACTION_GROUPS.nonlaunch);
+  }
+  return ACTIONS;
+}
+