Skip to content

CLAUDE.md

Latest commit

 

History

History
323 lines (230 loc) · 9.63 KB

CLAUDE.md

File metadata and controls

323 lines (230 loc) · 9.63 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ CRITICAL: SESSION MANAGEMENT RULES FOR CODING AGENTS

STOP. READ THIS. THIS IS NON-NEGOTIABLE.

You MUST NEVER manage, create, or destroy tmux SESSIONS.

This tool is ONLY for managing WINDOWS and PANES within existing sessions. If you see yourself doing any of the following:

  • Creating new tmux sessions
  • Destroying tmux sessions
  • Modifying session configuration
  • Renaming sessions
  • Managing session lifecycle in any way

YOU ARE DOING IT WRONG. STOP IMMEDIATELY.

The Rules (Read These):

  1. Windows and Panes Only: You can create/destroy/manage windows and panes. That's it. That's all you're allowed to do.
  2. Existing Sessions Only: Always operate within an existing tmux session. The tool automatically handles session detection.
  3. No Session Lifecycle: Never create or destroy entire sessions. Not once. Not ever. Not for any reason.
  4. Use Default Sessions: When outside tmux, the tool automatically uses the 'claude-dev' session. Don't override this unless explicitly instructed.

If you need a tmux session, assume it already exists. If it doesn't exist, fail gracefully and report the error to the user.

Overview

tmux-iterm-command is a command-line tool that bridges coding agents (Claude, Qwen, Gemini, Codex) with tmux. It enables coding agents to programmatically:

  • Create and manage tmux windows and panes within existing sessions (WINDOWS AND PANES ONLY)
  • Execute commands and capture output
  • Interact with terminal sessions in a structured way
  • Operate within existing tmux sessions (does not create/destroy entire sessions)

Project Architecture

Core Components

  1. CLI Entry Point (src/claude_tmux/cli.py)

    • Argument parsing using Click framework
    • Command routing and delegation
    • Main interface for external callers (coding agents)

  2. Tmux Abstraction Layer (src/claude_tmux/manager.py)

    • Uses libtmux library for tmux operations (no subprocess calls)
    • Session detection and management within existing sessions
    • Window and pane operations
    • Command execution and output capture

  3. Command Handlers (src/claude_tmux/commands.py)

    • Individual command modules for each CLI command
    • Each follows Click command pattern
    • Encapsulates command logic and option parsing

Data Flow

User (Claude Code Agent) → CLI Arguments → Command Router → Handler → Tmux Binary/iTerm2 API → Terminal Session

Development Setup

Initial Setup

# Install Python dependencies
pip install -e .

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install -e .

Running the Tool

# Show available commands
tmux-iterm-command --help

# Run a specific command with options
tmux-iterm-command create-window --name editor

# For development: run directly with Python
python -m src.tmux_iterm_command.cli <command> <args>

Running with uvx (Recommended for Claude Code)

# Show available commands
uvx git+https://github.com/joej/tmux-iterm-command --help

# Run a specific command with options
uvx git+https://github.com/joej/tmux-iterm-command create-window --name editor

Running Tests

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_tmux_manager.py

# Run with coverage
pytest --cov=src tests/

# Run specific test
pytest tests/test_tmux_manager.py::test_create_window

Common Commands

Available Commands

tmux-iterm-command --help  # Show all available commands

Core Commands:

  • capture-pane - Capture output from a pane
  • create-pane - Split a window to create a new pane
  • create-window - Create a new tmux window
  • detect - Detect environment capabilities
  • kill-pane - Kill a tmux pane
  • kill-window - Kill a tmux window
  • list-panes - List all panes in a window
  • list-sessions - List all tmux sessions
  • list-windows - List all windows in a session
  • send - Send a command to a pane
  • status - Show current tmux status
  • wait-idle - Wait for a pane to be idle

Placeholder Commands (require iTerm2 features):

  • notify - Send notification
  • set-badge - Set iTerm2 badge for a window
  • set-mark - Set iTerm2 mark for a pane
  • set-tab-color - Set iTerm2 tab color

Tmux Management

# Create a window in the current/default session
tmux-iterm-command create-window --name editor --command "vim myfile.txt"

# Create a pane by splitting a window
tmux-iterm-command create-pane --window 0 --vertical --command "tail -f logs/app.log"

# List active sessions
tmux-iterm-command list-sessions

# List windows in current session
tmux-iterm-command list-windows

# List panes in a window
tmux-iterm-command list-panes --window 0

uvx Command Examples

# uvx syntax: uvx git+https://github.com/joej/tmux-iterm-command <command> [options]

# Create a window with command
uvx git+https://github.com/joej/tmux-iterm-command create-window --name my-window --command "ls -la"

# Send command to existing pane
uvx git+https://github.com/joej/tmux-iterm-command send --window 0 --pane 0 "ps aux"

# Capture pane output
uvx git+https://github.com/joej/tmux-iterm-command capture-pane --window 0 --pane 0 --lines 50

# Kill a window
uvx git+https://github.com/joej/tmux-iterm-command kill-window --window 1

Command Execution

# Send a command to a specific pane (automatically adds Enter)
tmux-iterm-command send --window 0 --pane 0 "npm install"

# Send command without pressing Enter
tmux-iterm-command send --window 0 --pane 0 --no-enter "echo hello"

# Capture pane output
tmux-iterm-command capture-pane --window 0 --pane 0 --lines 100

# Wait for pane to be idle (no output for 2 seconds, timeout after 30s)
tmux-iterm-command wait-idle --window 0 --pane 0 --quiet-for 2 --timeout 30

Window/Pane Management

# Kill a window
tmux-iterm-command kill-window --window 1

# Kill a pane
tmux-iterm-command kill-pane --window 0 --pane 1

# Detect environment capabilities
tmux-iterm-command detect

# Show current status
tmux-iterm-command status

Key Architecture Patterns

Tmux libtmux Pattern

All tmux interactions use the libtmux library, which provides a Pythonic interface to tmux. This ensures:

  • Clean object-oriented API for tmux operations
  • Better integration with Python error handling
  • Consistent behavior across different environments
# Pattern: Use libtmux Server, Session, Window, and Pane objects
from libtmux import Server
server = Server()
session = server.sessions[0]  # Get first session
window = session.new_window(window_name="my_window")

Command Handler Interface

Each command handler follows this pattern:

# src/claude_tmux/commands.py
import click

@click.command()
@click.option('--window', 'window_index', type=int, required=True, help='Window index')
@click.option('--pane', 'pane_index', type=int, required=True, help='Pane index')
def my_command(window_index, pane_index):
    """Do something in tmux."""
    # Implementation
    pass

Note: Some commands like create-window only require --name and optional --command, while commands like send require both --window and --pane.

Error Handling

All commands return structured output:

  • Success: {"status": "success", ...}
  • Error: {"status": "error", "message": "...", "code": "..."}
  • Output goes to stdout as JSON; coding agents parse responses

Session Management Approach

The tool works within existing tmux sessions:

  1. Inside tmux: Uses the current session
  2. Outside tmux: Creates or attaches to a default session ('claude-dev')
  3. No session lifecycle: Does not create/destroy entire sessions, only manages windows/panes

⚠️ REMEMBER: The tool handles session detection automatically. You should NEVER manually manage sessions. Let the tool handle it. If you find yourself trying to create or destroy sessions, you're using this tool incorrectly.

Adding New Commands

  1. Add function to src/tmux_iterm_command/commands.py (all commands are in one file currently)
  2. Implement Click command with proper options
  3. Add to command registration in src/tmux_iterm_command/cli.py
  4. Write tests in tests/test_commands.py
  5. Test manually: tmux-iterm-command your-command --help

Testing Strategy

  • Unit tests for tmux wrapper functions (mock libtmux calls)
  • Integration tests for actual tmux operations (in isolated test sessions)
  • Use pytest fixtures for session/window/pane setup and teardown
  • Tests validate JSON output format for coding agent consumption

Debugging

Enable verbose logging

# All commands support --verbose flag
tmux-iterm-command create-window --name editor --verbose

# Or set environment variable
TMUX_ITERM_COMMAND_DEBUG=1 tmux-iterm-command create-window --name editor

Check tmux status

# Inspect sessions created by the tool
tmux list-sessions
tmux list-windows -t session-name
tmux list-panes -t session-name:window-index

# Attach to a session for inspection
tmux attach-session -t session-name

Common Issues

  • "Tmux not found": Ensure tmux is installed (brew install tmux)
  • Permission denied: Check tmux socket permissions in /tmp
  • Command hangs: Use appropriate timeout settings
  • Session detection: Tool works inside or outside tmux, using appropriate session

Dependencies

  • Python 3.8+
  • tmux (CLI binary for libtmux to interface with)
  • libtmux: Python library for tmux control
  • click: CLI framework

Core Python packages:

  • libtmux: Tmux control library
  • click: CLI framework
  • pytest: Testing framework

See requirements.txt for full list and versions.