jbwinters/tmuxcontrollib

TmuxControlLib

A Python library for AI agents to control tmux sessions and terminal interfaces.

⚠️ Important Notice: This project is largely AI-generated code. Users should exercise caution and thoroughly review the code before using it in production environments. While functional, the codebase may contain inconsistencies, security vulnerabilities, or architectural issues typical of generated code. Use at your own risk and consider this experimental software.

Overview

TmuxControlLib provides tools for AI agents to interact with tmux sessions and terminal interfaces. The library is designed to enable powerful agent workflows, terminal automation, and coordination between AI agents and terminal environments.

The library consists of several modules:

1. tmux_control: A clean, Pythonic API for interacting with tmux sessions, windows, and panes
2. claude_control: A framework for managing and coordinating multiple Claude agents

Features

Tmux Control

• Session Management: Create, attach to, and manage tmux sessions
• Window Operations: Create and manipulate windows within sessions
• Pane Control: Split panes, send keystrokes, and capture pane content
• Content Reading: Read and interpret pane content, handle ANSI escape sequences
• Pattern Matching: Find, extract, and wait for specific patterns in pane output
• Command Execution: Send commands and wait for specific outputs
• Layout Management: Arrange panes in different layouts

Claude Agent Control

• Agent Management: Create, track, and coordinate multiple Claude agents
• State Persistence: Save and restore conversation state across sessions
• Agent Communication: Enable inter-agent messaging via pub/sub system
• Task Management: Organize agent work with priority queues
• Supervisor Architecture: Create monitoring agents to coordinate others
• Conversation Tracking: Maintain structured history of interactions

MCP Server

• Model Context Protocol: Provide Tmux control and search functionality to Claude via MCP
• Command Registration: Simple script to register the MCP server with Claude
• Comprehensive API: Access all tmuxcontrollib functionality as Claude tools
• Interactive Control: Allow Claude to create, manage, and interact with tmux sessions
• Advanced Search: Give Claude the ability to search, extract, and process text from terminals

Installation

Note: This package is not yet published to PyPI. Currently available installation methods:

# Install from source (current method)
pip install .

# Install with Poetry (for development)
poetry install

# Install from GitHub (when available)
pip install git+https://github.com/jbwinters/tmuxcontrollib.git

Docker Installation

You can also run the controllib MCP server using Docker:

# Build and run with Docker Compose
docker-compose up -d

# Register with Claude
claude mcp add controllib -- sh -c "docker attach controllib-mcp-server"

See for detailed instructions on Docker usage.

Usage

Tmux Control API

from controllib.tmux_control import TmuxController

# Create a new tmux controller
controller = TmuxController()

# Create a new session
session = controller.new_session("my-session")

# Create a new window
window = session.new_window("my-window")

# Split the window into panes
pane1 = window.split_pane(vertical=True)

# Send a command to the pane
pane1.send_command("echo 'Hello, World!'")

# Capture the pane output
output = pane1.capture_pane()
print(output)

# Wait for a specific pattern to appear
result = pane1.wait_for_text(r"Hello, (\w+)!")
print(result)

Claude Agent Control API

from controllib.claude_control import ClaudeController, ClaudeAgent

# Create a controller for managing Claude agents
controller = ClaudeController(session_name="agent_session", auto_save=True)

# Create agents with different roles
research_agent = controller.create_agent(
    name="researcher",
    window_name="research",
    init_prompt="You are a research assistant specialized in finding information.",
    role="researcher",
    metadata={"specialization": "information retrieval"}
)

coding_agent = controller.create_agent(
    name="coder",
    window_name="coding",
    init_prompt="You are a coding assistant specialized in Python programming.",
    role="coder",
    metadata={"specialization": "python"}
)

# Set up communication channels
research_agent.subscribe_to_topic("coding_questions")
coding_agent.subscribe_to_topic("research_questions")

# Send prompts and get responses
research_response = research_agent.send_prompt(
    "What are the main approaches to natural language processing?",
    topic="nlp_research"
)

# Add tasks to an agent's queue
coding_agent.add_task(
    {"prompt": "Write a function to parse JSON data"},
    priority=5
)

# Process the next task in the queue
coding_agent.process_task_queue()

# Broadcast a prompt to multiple agents
responses = controller.broadcast_prompt(
    "What are your specialized capabilities?",
    wait_for_all=True
)

# Save agent states for persistence
controller.save_all_agent_states()

Command Line Interface

ControlLib provides a powerful CLI for interacting with tmux sessions and Claude agents:

# Tmux Control Commands
controllib tmux list-sessions --detail       # List all tmux sessions with details
controllib tmux create my-session            # Create a new tmux session
controllib tmux send-keys my-session 0 0 "echo 'Hello!'" --enter   # Send keys to a pane
controllib tmux capture my-session 0 0 --history    # Capture pane content
controllib tmux monitor my-session 0 0       # Monitor a pane for changes
controllib tmux wait-for my-session 0 0 "Done" --timeout 5   # Wait for text to appear

# Claude Agent Commands
controllib claude create-session --claude-cmd "claude"   # Create a session for Claude agents
controllib claude create-agent agent_session --name "researcher" --window "research" --role "researcher"
controllib claude list-agents agent_session   # List all agents in the session
controllib claude send-prompt agent_session researcher "Find the latest research on LLMs" --wait
controllib claude broadcast agent_session "What are your capabilities?"   # Send to all agents
controllib claude kill-agent agent_session researcher   # Remove a specific agent

Text User Interface

ControlLib also provides a TUI (Text User Interface) for a more interactive experience:

# Launch the TUI
controllib tui

MCP Integration for Claude

ControlLib includes an MCP server that allows Claude to use tmux control and search functionality:

# Register the MCP server with Claude
register-mcp

# Register with custom options
register-mcp --name tmux-control --global --debug

# Run the MCP server directly (usually not needed)
controllib-mcp --debug

Once registered, Claude can use the MCP functionality:

# In a Claude conversation:

# List all tmux sessions
sessions = controllib.tmux.list_sessions()

# Create a new session
session = controllib.tmux.create_session(name="dev-session")

# Execute a command and capture output
controllib.tmux.send_command(
    session_name="dev-session", 
    window_index_or_name=0, 
    pane_index=0, 
    command="ls -la"
)
result = controllib.tmux.capture_pane(
    session_name="dev-session", 
    window_index_or_name=0, 
    pane_index=0
)

# Search for patterns in the output
matches = controllib.tmux.find_text(
    session_name="dev-session",
    window_index_or_name=0,
    pane_index=0,
    pattern=r"\.py$"
)

Using as an MCP Server for Nested Agents

The MCP server functionality enables powerful nested agent workflows where Claude can control and coordinate other AI agents through tmux sessions. This is particularly useful for:

Why Use Nested Agents?

1. Task Specialization: Different agents can be specialized for different tasks (research, coding, testing, etc.)
2. Parallel Processing: Multiple agents can work on different aspects of a problem simultaneously
3. Persistent Sessions: Agents maintain state across conversations in dedicated tmux sessions
4. Isolation: Each agent runs in its own environment, preventing conflicts
5. Monitoring: The controlling Claude instance can observe and coordinate all sub-agents

Nested Agent Workflow

# Claude (via MCP) creates a specialized research agent
controllib.tmux.create_session(name="research-agent")
controllib.tmux.send_command(
    session_name="research-agent",
    window_index_or_name=0,
    pane_index=0,
    command="claude --session research --role 'You are a research specialist'"
)

# Create a coding agent in parallel
controllib.tmux.create_session(name="coding-agent")
controllib.tmux.send_command(
    session_name="coding-agent",
    window_index_or_name=0,
    pane_index=0,
    command="claude --session coding --role 'You are a Python developer'"
)

# Assign tasks to each agent
# Send research task to research agent
controllib.tmux.send_keys(
    session_name="research-agent",
    window_index_or_name=0,
    pane_index=0,
    keys="Research the latest developments in transformer architectures"
)

# Send coding task to coding agent
controllib.tmux.send_keys(
    session_name="coding-agent",
    window_index_or_name=0,
    pane_index=0,
    keys="Implement a transformer attention mechanism in PyTorch"
)

# Monitor progress and collect results
research_output = controllib.tmux.capture_pane(
    session_name="research-agent",
    window_index_or_name=0,
    pane_index=0
)

coding_output = controllib.tmux.capture_pane(
    session_name="coding-agent",
    window_index_or_name=0,
    pane_index=0
)

# Coordinate and synthesize results from both agents

Advanced Nested Patterns

• Supervisor Architecture: One Claude instance manages multiple specialized sub-agents
• Pipeline Processing: Results from one agent feed into the next in a processing pipeline
• Collaborative Development: Multiple coding agents work on different modules simultaneously
• Multi-modal Teams: Research agents, coding agents, testing agents, and documentation agents working together

This approach leverages the full power of tmux session management while providing Claude with the tools to orchestrate complex, multi-agent workflows.

Development Guide

Project Structure

controllib/
├── tmux_control/       # Tmux interaction module
│   ├── controller.py   # Main tmux controller
│   ├── session.py      # Tmux session manager
│   ├── window.py       # Window operations
│   ├── pane.py         # Pane interactions
│   └── patterns.py     # Pattern matching utilities
├── claude_control/     # Claude agent module
│   ├── controller.py   # Multi-agent controller
│   └── agent.py        # Individual agent class
├── utils/              # Utility functions and tools
│   └── cli.py          # CLI for utility functions
├── cli.py              # Command-line interface
└── tui.py              # Text user interface

Running Tests

# Run all tests
poetry run pytest tests/

# Test specific module
poetry run pytest tests/test_tmux_controller.py

Architecture Concepts

State Persistence Model

Claude agent state is serializable and can be saved to JSON files. States include:

• Conversation history with timestamps
• Agent role and metadata
• Subscribed topics
• Task queue and status

Agent Communication

The system uses a publish/subscribe model where:

1. Agents can subscribe to topics
2. Messages published to topics are delivered to all subscribers
3. Each agent processes messages based on its role

Task Management

Agents maintain priority queues for tasks:

1. Tasks can be added with different priorities
2. Higher priority tasks are processed first
3. Tasks include status tracking (pending, processing, completed)

Supervisor Architecture

The system supports a supervisor agent that:

1. Monitors other agents' status
2. Can assign tasks based on agent specialization
3. Aggregates results from multiple agents
4. Intervenes when agents need assistance

Distribution Guide

This package can be published to PyPI for easy distribution. Follow these steps to publish:

Publishing to PyPI

1. Ensure you have the necessary credentials

   # Copy the example pypirc file
   cp .pypirc.example ~/.pypirc
   
   # Edit with your actual PyPI token
   nano ~/.pypirc
   

2. Update your author information in pyproject.toml

   # Edit author info
   nano pyproject.toml
   

3. Build the distribution packages

   poetry build
   

4. Upload to Test PyPI first (recommended)

   poetry publish -r testpypi
   

5. Test the installation from Test PyPI

   pip install --index-url https://test.pypi.org/simple/ controllib
   

6. Upload to PyPI

   poetry publish
   

Version Management

To update the version number when making changes:

# Update version in pyproject.toml manually or use poetry
poetry version patch  # for bug fixes (0.1.0 -> 0.1.1)
poetry version minor  # for new features (0.1.0 -> 0.2.0)
poetry version major  # for breaking changes (0.1.0 -> 1.0.0)

Key Classes and Methods

ClaudeController

• create_agent(name, role, metadata): Create a new Claude agent
• broadcast_prompt(prompt, agents): Send prompt to multiple agents
• publish_message(topic, message): Send message to a topic
• save_all_agent_states(): Persist agent conversations
• load_agent_states(directory): Restore agent conversations
• create_supervisor_agent(): Create a monitoring agent

ClaudeAgent

• send_prompt(prompt, topic): Send prompt and track in history
• wait_for_response(): Wait for agent to finish responding
• add_task(task, priority): Add a task to the queue
• process_task_queue(): Process the next task
• subscribe_to_topic(topic): Listen for messages on a topic
• save_state(filepath): Save conversation and metadata
• load_state(filepath): Restore previous state

License

MIT