A collection of practical tools, hooks, and utilities for enhancing Claude Code and other CLI coding agents.

• 🎮 tmux-cli: Bridging Claude Code and Interactive CLIs — "playwright for the terminal"
• 🚀 Quick Start
• 🎮 tmux-cli Deep Dive
• 🚀 lmsh (Experimental) — natural language to shell commands
• 🔍 find-claude-session — search and resume Claude sessions
• 🔐 vault — encrypted .env backup & sync
• 🔍 env-safe — inspect .env safely without values
• 🛡️ Claude Code Safety Hooks — guardrails for bash, git, env, files
• 🤖 Using Claude Code with Open-weight Anthropic API-compatible LLM Providers
• 📚 Documentation
• 📋 Requirements
• 🛠️ Development
• 📄 License

Note: While the description below focuses on Claude Code, tmux-cli works with any CLI coding agent.

Consider these scenarios:

You're using Claude Code (CC) to build an interactive script. The script prompts for user input, but CC can't respond to prompts.

You want Claude Code to debug using pdb, stepping through code line by line.

You need your CLI code agent to launch another instance of the same OR different CLI code agent, AND interact with it, not as a hidden sub-agent, but as a visible session you can monitor (as shown in gif above).

tmux-cli enables these workflows by giving Claude Code programmatic control over terminal applications.

For those new to tmux, it's a terminal multiplexer that lets you create and manage multiple terminal sessions. The key benefit for our purposes is that tmux is scriptable and allows sending keystrokes to specific panes or sessions programmatically.

Important: You don't need to learn tmux-cli commands. Claude Code will handle all the interactions automatically. Just tell CC what you want to do, and it will use tmux-cli behind the scenes.

Think Playwright for terminals - Terminal automation for AI agents.

Works anywhere: Automatically handles both local tmux panes and remote sessions.

# Install from PyPI (recommended)
uv tool install claude-code-tools

# Or install the latest development version from GitHub
uv tool install git+https://github.com/pchalasani/claude-code-tools

This gives you:

• tmux-cli - The interactive CLI controller we just covered
• find-claude-session - Search and resume Claude Code sessions by keywords
• vault - Encrypted backup for your .env files
• env-safe - Safely inspect .env files without exposing values

1. Test Interactive Scripts - CC can run and interact with scripts that require user input, answering prompts automatically based on your instructions.

2. UI Development & Testing - CC can launch web servers and coordinate with browser automation tools to test your applications.

3. Interactive Debugging - CC can use debuggers (pdb, node inspect, gdb) to step through code, examine variables, and help you understand program flow.

4. Claude-to-Claude Communication - CC can launch another Claude Code instance to get specialized help or code reviews.

Claude Code knows how to use tmux-cli through its built-in help. You just describe what you want, and CC handles the technical details.

For complete command reference, see docs/tmux-cli-instructions.md.

To enable CC to use tmux-cli, add this snippet to your global ~/.claude/CLAUDE.md file:

# tmux-cli Command to interact with CLI applications

`tmux-cli` is a bash command that enables Claude Code to control CLI applications 
running in separate tmux panes - launch programs, send input, capture output, 
and manage interactive sessions. Run `tmux-cli --help` for detailed usage 
instructions.

Example uses:
- Interact with a script that waits for user input
- Launch another Claude Code instance to have it perform some analysis or review or 
  debugging etc
- Run a Python script with the Pdb debugger to step thru its execution, for 
  code-understanding and debugging
- Launch web apps and test them with browser automation MCP tools like Puppeteer

Incidentally, installing the Puppeteer MCP tool is easy:

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

For detailed instructions, see docs/tmux-cli-instructions.md.

Natural language shell - type what you want in plain English, get an editable command.

# Direct usage - translate, edit, execute, then enter interactive mode
$ lmsh "show me all python files modified today"
find . -name "*.py" -mtime 0  # <-- Edit before running

# Or interactive mode
$ lmsh
lmsh> show recent docker containers
docker ps -n 5  # <-- Edit before running

Features:

• Rust-based for instant startup (<1ms binary load time)
• Translates natural language to shell commands using Claude Code CLI
• Commands are editable before execution - full control
• Preserves your shell environment

Note: Requires Claude Code CLI (claude command) to be installed. The translation adds ~2-3s due to Claude Code CLI startup.

Installation:

# 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

See docs/lmsh.md for details.

Search and resume Claude Code sessions by keywords with an interactive UI.

Add this function to your shell config (.bashrc/.zshrc) for persistent directory changes:

fcs() {
    # Check if user is asking for help
    if [[ "$1" == "--help" ]] || [[ "$1" == "-h" ]]; then
        find-claude-session --help
        return
    fi
    # Run find-claude-session in shell mode and evaluate the output
    eval "$(find-claude-session --shell "$@" | sed '/^$/d')"
}

Or source the provided function:

source /path/to/claude-code-tools/scripts/fcs-function.sh

# Search in current project
fcs "keyword1,keyword2,keyword3"

# Search across all Claude projects  
fcs "keywords" --global
fcs "keywords" -g

• Interactive session selection with previews
• Cross-project search capabilities
• Automatic session resumption with claude -r
• Persistent directory changes when resuming cross-project sessions

Note: You can also use find-claude-session directly, but directory changes won't persist after exiting Claude Code.

For detailed documentation, see docs/find-claude-session.md.

Looks like this --

Centralized encrypted backup for .env files across all your projects using SOPS.

vault sync      # Smart sync (auto-detect direction)
vault encrypt   # Backup .env to ~/Git/dotenvs/
vault decrypt   # Restore .env from centralized vault
vault list      # Show all project backups
vault status    # Check sync status for current project

• Stores all encrypted .env files in ~/Git/dotenvs/
• Automatic sync direction detection
• GPG encryption via SOPS
• Timestamped backups for safety

For detailed documentation, see docs/vault-documentation.md.

Safely inspect .env files without exposing sensitive values. Designed for Claude Code and other automated tools that need to work with environment files without accidentally leaking secrets.

env-safe list                    # List all environment variable keys
env-safe list --status           # Show keys with defined/empty status  
env-safe check API_KEY           # Check if a specific key exists
env-safe count                   # Count total, defined, and empty variables
env-safe validate                # Validate .env file syntax
env-safe --help                  # See all options

• No Value Exposure - Never displays actual environment values
• Safe Inspection - Check which keys exist without security risks
• Syntax Validation - Verify .env file format is correct
• Status Checking - See which variables are defined vs empty
• Claude Code Integration - Works with protection hooks to provide safe alternative

Claude Code is completely blocked from directly accessing .env files - no reading, writing, or editing allowed. This prevents both accidental exposure of API keys and unintended modifications. The env-safe command provides the only approved way for Claude Code to inspect environment configuration safely, while any modifications must be done manually outside of Claude Code.

This repository includes a comprehensive set of safety hooks that enhance Claude Code's behavior and prevent dangerous operations.

• File Deletion Protection - Blocks rm commands, enforces TRASH directory pattern
• Git Safety - Advanced git add protection with:
  • Hard blocks: git add ., git add ../, git add *, git add -A/--all
  • Speed bumps: Shows files before staging directories (e.g., git add src/)
  • Commit speed bump: Warns on first attempt, allows on second
  • Prevents unsafe checkouts and accidental data loss
• Environment Security - Blocks all .env file operations (read/write/edit), suggests env-safe command for safe inspection
• Context Management - Blocks reading files >500 lines to prevent context bloat
• Command Enhancement - Enforces ripgrep (rg) over grep for better performance

1. Copy the hooks configuration from hooks/settings.sample.json

2. Add the hooks to your global Claude settings at ~/.claude/settings.json:

   • If the file doesn't exist, create it
   • Copy the "hooks" section from settings.sample.json
   • Replace /path/to/claude-code-tools with your actual path to this repository

   Example ~/.claude/settings.json:

   {
     "hooks": {
       // ... hooks configuration from settings.sample.json ...
     }
   }

• bash_hook.py - Comprehensive bash command safety checks
• env_file_protection_hook.py - Blocks all .env file operations
• file_size_conditional_hook.py - Prevents reading huge files
• grep_block_hook.py - Enforces ripgrep usage
• notification_hook.sh - Sends ntfy.sh notifications
• pretask/posttask_subtask_flag.py - Manages sub-agent state

For complete documentation, see hooks/README.md.

You can use Claude Code with alternative LLMs served via Anthropic-compatible APIs, e.g. Kimi-k2, GLM4.5 (from zai), Deepseek-v3.1. Add these functions to your shell config (.bashrc/.zshrc):

kimi() {
    (
        export ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
        export ANTHROPIC_AUTH_TOKEN=$KIMI_API_KEY
        claude "$@"
    )
}

zai() {
    (
        export ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
        export ANTHROPIC_AUTH_TOKEN=$Z_API_KEY
        claude "$@"
    )
}

dseek() {
    (
        export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
        export ANTHROPIC_AUTH_TOKEN=${DEEPSEEK_API_KEY}
        export ANTHROPIC_MODEL=deepseek-chat
        export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat        
        claude "$@"
    )
}

After adding these functions:

• Set your API keys: export KIMI_API_KEY=your-kimi-key, export Z_API_KEY=your-z-key, export DEEPSEEK_API_KEY=your-deepseek-key
• Run kimi to use Claude Code with the Kimi K2 LLM
• Run zai to use Claude Code with the GLM-4.5 model
• Run dseek to use Claude Code with the DeepSeek model

The functions use subshells to ensure the environment variables don't affect your main shell session, so you could be running multiple instances of Claude Code, each using a different LLM.

• tmux-cli detailed instructions - Comprehensive guide for using tmux-cli
• Claude Code tmux tutorials - Additional tutorials and examples
• Vault documentation - Complete guide for the .env backup system
• Hook configuration - Setting up Claude Code hooks

• Python 3.11+
• uv (for installation)
• tmux (for tmux-cli functionality)
• SOPS (for vault functionality)

1. Clone the repository:

   git clone https://github.com/username/claude-code-tools
   cd claude-code-tools

2. Create and activate a virtual environment with uv:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install in development mode:

   make install      # Install tools in editable mode
   make dev-install  # Install with dev dependencies (includes commitizen)

• The tools are installed in editable mode, so changes take effect immediately
• Test your changes by running the commands directly
• Follow the existing code style and conventions

The project uses commitizen for version management:

make patch  # Bump patch version (0.0.X)
make minor  # Bump minor version (0.X.0)  
make major  # Bump major version (X.0.0)

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit your changes (commitizen will format the commit message)
6. Push to your fork
7. Open a Pull Request

Run make help to see all available commands:

• make install - Install in editable mode for development
• make dev-install - Install with development dependencies
• make release - Bump patch version and install globally
• make patch/minor/major - Version bump commands

MIT