### Execute Command and Start Python REPL Examples

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Demonstrates sending a command without confirmation and starting a Python REPL in a specified Tmux window.

```python
# Execute a command in a window
orchestrator.send_command_to_window("project", 1, "npm run dev", confirm=False)

# Start Python REPL
orchestrator.send_command_to_window("python-session", 0, "python3")
```

--------------------------------

### Example: Starting 'Task Templates' Project

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

A concrete example demonstrating the project startup sequence for the 'Task Templates' project. It includes finding the project, creating a Tmux session, setting up windows, and initiating the Claude agent briefing.

```bash
# 1. Find project
ls -la ~/Coding/ | grep -i task
# Found: task-templates

# 2. Create session
tmux new-session -d -s task-templates -c "/Users/jasonedward/Coding/task-templates"

# 3. Set up windows
tmux rename-window -t task-templates:0 "Claude-Agent"
tmux new-window -t task-templates -n "Shell" -c "/Users/jasonedward/Coding/task-templates"
tmux new-window -t task-templates -n "Dev-Server" -c "/Users/jasonedward/Coding/task-templates"

# 4. Start Claude and brief
tmux send-keys -t task-templates:0 "claude" Enter
# ... (briefing as above)
```

--------------------------------

### Full Orchestrator Setup with Tmux

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/README.md

This snippet shows how to initiate the full orchestrator setup. It involves starting a new tmux session for the orchestrator and then instructing it to manage multiple projects with their respective tasks and check-in schedules.

```bash
# Start the orchestrator
tmux new-session -s orchestrator
claude

# Give it your projects
"You are the Orchestrator. Set up project managers for:
1. Frontend (React app) - Add dashboard charts
2. Backend (FastAPI) - Optimize database queries
Schedule yourself to check in every hour."
```

--------------------------------

### Install and Import TmuxOrchestrator

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Import the necessary classes from the tmux_utils library to get started with the orchestrator.

```python
from tmux_utils import TmuxOrchestrator, TmuxSession, TmuxWindow

orchestrator = TmuxOrchestrator()
```

--------------------------------

### Start Development Server Commands

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Commands to start the development server based on detected project type. These commands are executed in the 'Dev-Server' Tmux window and include package installation and server startup scripts for Node.js, Python (FastAPI/Django), and other frameworks.

```bash
# For Next.js/Node projects
tmux send-keys -t $PROJECT_NAME:2 "npm install && npm run dev" Enter

# For Python/FastAPI
tmux send-keys -t $PROJECT_NAME:2 "source venv/bin/activate && uvicorn app.main:app --reload" Enter

# For Django
tmux send-keys -t $PROJECT_NAME:2 "source venv/bin/activate && python manage.py runserver" Enter
```

--------------------------------

### Basic Project Setup with Tmux Orchestrator

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/README.md

This snippet demonstrates the steps to set up a single project using the tmux-orchestrator. It involves creating a project specification file, starting a tmux session, initializing the project manager, assigning the spec, and scheduling a check-in.

```bash
# 1. Create a project spec
cat > project_spec.md << 'EOF'
PROJECT: My Web App
GOAL: Add user authentication system
CONSTRAINTS:
- Use existing database schema
- Follow current code patterns  
- Commit every 30 minutes
- Write tests for new features

DELIVERABLES:
1. Login/logout endpoints
2. User session management
3. Protected route middleware
EOF

# 2. Start tmux session
tmux new-session -s my-project

# 3. Start project manager in window 0
claude

# 4. Give PM the spec and let it create an engineer
"You are a Project Manager. Read project_spec.md and create an engineer 
in window 1 to implement it. Schedule check-ins every 30 minutes."

# 5. Schedule orchestrator check-in
./schedule_with_note.sh 30 "Check PM progress on auth system"
```

--------------------------------

### Start a New Project Workflow

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

A comprehensive workflow to initialize a new project in tmux. It includes creating a session, setting up agent and dev server windows, starting the agent, and briefing it.

```bash
# 1. Create session
PROJECT="my-project"
tmux new-session -d -s $PROJECT -c "/path/to/$PROJECT"

# 2. Set up windows
tmux rename-window -t $PROJECT:0 "Claude-Agent"
tmux new-window -t $PROJECT -n "Dev-Server" -c "/path/to/$PROJECT"

# 3. Start Claude
tmux send-keys -t $PROJECT:0 "claude" Enter
sleep 5

# 4. Brief the agent
./send-claude-message.sh "$PROJECT:0" "You are responsible for the $PROJECT codebase. Please analyze it and start the dev server in window 1."

# 5. Schedule check-in
./schedule_with_note.sh 30 "Monitor $PROJECT progress" "$PROJECT:0"
```

--------------------------------

### Starting Claude and Initial Briefing

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

This pattern involves starting Claude with a manual command, waiting for it to initialize, and then using the script for the initial briefing. Ensure a sufficient `sleep` duration.

```bash
# Start Claude first
tmux send-keys -t project:0 "claude" Enter
sleep 5

# Then use the script for the briefing
/Users/jasonedward/Coding/Tmux\ orchestrator/send-claude-message.sh project:0 "You are responsible for the frontend codebase. Please start by analyzing the current project structure and identifying any immediate issues."
```

--------------------------------

### Project Specification Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/README.md

An example of a detailed project specification including project name, goal, constraints, deliverables, and success criteria. Use this format to clearly define tasks for agents.

```markdown
PROJECT: E-commerce Checkout
GOAL: Implement multi-step checkout process

CONSTRAINTS:
- Use existing cart state management
- Follow current design system
- Maximum 3 API endpoints
- Commit after each step completion

DELIVERABLES:
1. Shipping address form with validation
2. Payment method selection (Stripe integration)
3. Order review and confirmation page
4. Success/failure handling

SUCCESS CRITERIA:
- All forms validate properly
- Payment processes without errors  
- Order data persists to database
- Emails send on completion
```

--------------------------------

### Get Window Info Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Retrieves and prints details about a specific tmux window, including its name, active status, layout, and recent content. It also demonstrates how to check for errors.

```python
info = orchestrator.get_window_info("project", 0)
print(f"Window name: {info['name']}")
print(f"Active: {info['active']}")
print(f"Layout: {info['layout']}")
print(f"Recent output:\n{info['content']}")

# Check for errors
if 'error' in info:
    print(f"Error retrieving info: {info['error']}")
else:
    print(f"Window has {info['panes']} panes")
```

--------------------------------

### Start Claude and Send Briefing

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Starts the 'claude' process in the Project Manager window and sends a detailed briefing outlining responsibilities and key principles. Includes necessary delays for commands to execute.

```bash
# Start Claude
tmux send-keys -t [session]:[PM-window] "claude" Enter
sleep 5

# Send PM-specific briefing
tmux send-keys -t [session]:[PM-window] "You are the Project Manager for this project. Your responsibilities:

1. **Quality Standards**: Maintain exceptionally high standards. No shortcuts, no compromises.
2. **Verification**: Test everything. Trust but verify all work.
3. **Team Coordination**: Manage communication between team members efficiently.
4. **Progress Tracking**: Monitor velocity, identify blockers, report to orchestrator.
5. **Risk Management**: Identify potential issues before they become problems.

Key Principles:
- Be meticulous about testing and verification
- Create test plans for every feature
- Ensure code follows best practices
- Track technical debt
- Communicate clearly and constructively

First, analyze the project and existing team members, then introduce yourself to the developer in window 0."
sleep 1
tmux send-keys -t [session]:[PM-window] Enter
```

--------------------------------

### Complex Multi-step Instructions Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/shell_scripts_reference.md

Provides detailed multi-step instructions for a scheduled task, persisting them in the note file. Use this for complex workflows or when detailed guidance is necessary.

```bash
./schedule_with_note.sh 120 "1. Review PR feedback from QA
2. Update documentation
3. Run final integration tests
4. Merge to main if all pass" "project-manager:0"
```

--------------------------------

### Monitor Tmux Windows with Python

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/START_HERE.md

Use the TmuxOrchestrator class from tmux_utils to get the status of all windows and create a monitoring snapshot. Requires the tmux_utils library to be installed.

```python
from tmux_utils import TmuxOrchestrator

orchestrator = TmuxOrchestrator()
status = orchestrator.get_all_windows_status()
snapshot = orchestrator.create_monitoring_snapshot()
print(snapshot)
```

--------------------------------

### Get All Windows Status Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Fetches the status of all tmux sessions and windows, parses the capture timestamp, and iterates through sessions and windows to print their names and check for errors or specific content.

```python
import json
from datetime import datetime

status = orchestrator.get_all_windows_status()

# Parse timestamp
capture_time = datetime.fromisoformat(status['timestamp'])
print(f"Status captured at: {capture_time}")

# Iterate all sessions and windows
for session in status['sessions']:
    print(f"\nSession: {session['name']}")
    for window in session['windows']:
        print(f"  Window {window['index']}: {window['name']}")
        
        # Check for errors in window content
        if "error" in window['info']:
            print(f"    ERROR: {window['info']['error']}")
        else:
            content_lines = window['info']['content'].split('\n')
            if "Error" in window['info']['content']:
                print(f"    ERROR DETECTED in output")
            print(f"    Layout: {window['info']['layout']}")
```

--------------------------------

### Short 5-Minute Follow-up Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/shell_scripts_reference.md

Schedules a quick 5-minute follow-up check. Ideal for verifying the completion of short-running tasks or immediate confirmations.

```bash
./schedule_with_note.sh 5 "Check if npm install finished"
```

--------------------------------

### Basic 30-Minute Check-in Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/shell_scripts_reference.md

Schedules a check-in in 30 minutes to the default tmux window with a specific note. This is a common use case for setting up immediate follow-up tasks.

```bash
./schedule_with_note.sh 30 "Review auth implementation, assign next task"
```

--------------------------------

### Initiate Pair Programming Session

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Starts a new tmux window for pair programming, allowing two developers to share an implementation and switch roles collaboratively.

```bash
# Two developers, one window
# They share implementation, switch roles
window_dev1=$(tmux new-window -t session -n "PairProg-Dev1")
# Dev2 joins and codes collaboratively through messages
```

--------------------------------

### Create Tmux Window with Specific Directory

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Create a new Tmux window and specify its starting directory. Use this to resolve 'Wrong Directory' issues.

```bash
# 2. When creating window, specify directory
tmux new-window -t session -n "name" -c "/correct/path"
```

--------------------------------

### Complete Session Monitoring Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Demonstrates how to retrieve all tmux sessions, iterate through their windows, and capture content to detect errors. Ensure TmuxOrchestrator is initialized and safety mode is considered for automation.

```python
orchestrator = TmuxOrchestrator()
orchestrator.safety_mode = False  # Disable confirmation for automation

# Get all sessions
sessions = orchestrator.get_tmux_sessions()

# Monitor a specific window
for session in sessions:
    for window in session.windows:
        content = orchestrator.capture_window_content(
            session.name, 
            window.window_index, 
            num_lines=100
        )
        if "error" in content.lower():
            print(f"ERROR in {session.name}:{window.window_index}")
```

--------------------------------

### Start a New Project Session

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/START_HERE.md

Create a new tmux session, rename the initial window, and add a new window for a development server. This is useful for setting up a new project environment.

```bash
# Create session and windows
tmux new-session -d -s project -c /path
tmux rename-window -t project:0 "Claude-Agent"
tmux new-window -t project -n "Dev-Server"

# Brief the agent
./send-claude-message.sh "project:0" "You are responsible for..."

# Schedule check-in
./schedule_with_note.sh 30 "Monitor progress" "project:0"
```

--------------------------------

### Start Claude Agent in Tmux Window

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Starts the 'claude' process within a specified tmux window and includes a delay for initialization.

```bash
tmux send-keys -t session:window "claude" Enter
sleep 5  # Wait for Claude to initialize
```

--------------------------------

### Orchestrator Agent Prompt Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Defines the role, responsibilities, team structure, available tools, and success criteria for an Orchestrator agent. This prompt guides the agent in managing development teams and ensuring project progress.

```plaintext
You are the Orchestrator for this development team.

Role:
- Maintain oversight of all projects and teams
- Identify blockers and risks early
- Make strategic decisions
- Share knowledge between teams
- Schedule your own check-ins

Team Structure:
- Frontend PM managing 2 developers
- Backend PM managing 2 developers
- Orchestrator (you) coordinating both

Your Responsibilities:
1. Every 30 minutes: Check status from both PMs
2. If any team blocked > 15 minutes: Intervene directly
3. If seeing repeated patterns: Share across teams
4. Schedule next check-in with specific focus area
5. Escalate to user if critical issue

Tools Available:
- send-claude-message.sh for sending messages
- schedule_with_note.sh for scheduling yourself
- tmux capture-pane for reading window content

Success Criteria:
- Both teams making steady progress
- No blockers lasting > 30 minutes
- Regular status updates (every 60 minutes)
- All commits are meaningful and regular
```

--------------------------------

### Common TmuxOrchestrator Operations

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Examples of common operations including getting session information, capturing window content, sending commands, and finding windows.

```python
# Get all sessions
sessions = orchestrator.get_tmux_sessions()
```

```python
# Get window content (last 50 lines)
content = orchestrator.capture_window_content("session", 0)
```

```python
# Send a command
orchestrator.send_command_to_window("session", 0, "ls -la", confirm=False)
```

```python
# Get detailed window info
info = orchestrator.get_window_info("session", 0)
```

```python
# Find windows by name
matches = orchestrator.find_window_by_name("Claude")
for session_name, window_index in matches:
    print(f"Found: {session_name}:{window_index}")
```

```python
# Get complete system status
status = orchestrator.get_all_windows_status()
```

```python
# Create readable monitoring report
snapshot = orchestrator.create_monitoring_snapshot()
print(snapshot)
```

--------------------------------

### List Tmux Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Lists all windows within a specified tmux session. Helpful for verifying your window setup.

```bash
# List windows
tmux list-windows -t project
```

--------------------------------

### Start Multi-Project Orchestration with Tmux

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/README.md

Use these bash commands to set up a tmux session for orchestrating multiple projects. This involves creating a main orchestrator session and separate windows for each project manager.

```bash
# Start orchestrator
tmux new-session -s orchestrator

# Create project managers for each project
tmux new-window -n frontend-pm
tmux new-window -n backend-pm  
tmux new-window -n mobile-pm

# Each PM manages their own engineers
# Orchestrator coordinates between PMs
```

--------------------------------

### Count Infrastructure Helper Function and Example Usage

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Calculates the total number of sessions, windows, and panes within the tmux environment. Demonstrates how to call this function and print the results.

```python
# Count total windows and panes
def count_infrastructure(status):
    total_sessions = len(status['sessions'])
    total_windows = sum(len(s['windows']) for s in status['sessions'])
    total_panes = sum(
        w['info'].get('panes', 0)
        for s in status['sessions']
        for w in s['windows']
    )
    return total_sessions, total_windows, total_panes

status = orchestrator.get_all_windows_status()
sessions, windows, panes = count_infrastructure(status)
print(f"Infrastructure: {sessions} sessions, {windows} windows, {panes} panes")
```

--------------------------------

### Get Project Path and Create PM Window

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Retrieves the current working directory from an existing window and creates a new tmux window for the Project Manager, setting its working directory.

```bash
# Get project path from existing window
PROJECT_PATH=$(tmux display-message -t [session]:0 -p '#{pane_current_path}')

# Create new window for PM
tmux new-window -t [session] -n "Project-Manager" -c "$PROJECT_PATH"
```

--------------------------------

### Create Tmux Session and Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/configuration_and_setup.md

Use these bash commands to create a new Tmux session, set its starting directory, rename the initial window, and add new windows for specific tasks like a development server.

```bash
# Create session
PROJECT_NAME="my-project"
PROJECT_PATH="/path/to/project"	mux new-session -d -s $PROJECT_NAME -c "$PROJECT_PATH"

# Rename first window	mux rename-window -t $PROJECT_NAME:0 "Claude-MyProject"

# Create additional windows	mux new-window -t $PROJECT_NAME -n "Dev-Server" -c "$PROJECT_PATH"
```

--------------------------------

### Brief Claude Agent in Tmux

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Sends an initial briefing message to the Claude agent within its designated Tmux window. This includes starting the agent and providing instructions for its tasks, such as analyzing the project and starting the development server.

```bash
# Send briefing message to Claude agent
tmux send-keys -t $PROJECT_NAME:0 "claude" Enter
sleep 5  # Wait for Claude to start

# Send the briefing
tmux send-keys -t $PROJECT_NAME:0 "You are responsible for the $PROJECT_NAME codebase. Your duties include:
1. Getting the application running
2. Checking GitHub issues for priorities  
3. Working on highest priority tasks
4. Keeping the orchestrator informed of progress

First, analyze the project to understand:
- What type of project this is (check package.json, requirements.txt, etc.)
- How to start the development server
- What the main purpose of the application is

Then start the dev server in window 2 (Dev-Server) and begin working on priority issues."
sleep 1
tmux send-keys -t $PROJECT_NAME:0 Enter
```

--------------------------------

### Integration with Scheduling Loop

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Provides an example of a continuous monitoring loop that creates snapshots of the tmux environment at regular intervals for analysis. Requires a `check_for_errors` function to be defined elsewhere.

```python
# Create a monitoring loop
import time

while True:
    snapshot = orchestrator.create_monitoring_snapshot()
    # Analyze snapshot for errors or status changes
    if check_for_errors(snapshot):
        # Trigger alerts or intervention
        pass
    time.sleep(60)
```

--------------------------------

### Longer Check-in for Different Project Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/shell_scripts_reference.md

Schedules a 1-hour check-in to a specified tmux window for a different project. Use this when tasks span across multiple projects or require longer lead times.

```bash
./schedule_with_note.sh 60 "Full system check, verify all tests pass" "glacier-backend:0"
```

--------------------------------

### Find Windows with Partial Name Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Demonstrates finding all Tmux windows that contain a specific substring in their name, case-insensitively. Useful for locating specific processes or sessions.

```python
# Find all windows with "Claude" in the name
matches = orchestrator.find_window_by_name("Claude")
for session_name, window_index in matches:
    print(f"Found: {session_name}:{window_index}")

# Find specific backend windows
backend_windows = orchestrator.find_window_by_name("backend")
```

--------------------------------

### Create New Tmux Window for Agent

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Use this command to create a new tmux window for an agent, specifying the session, window name, and starting directory.

```bash
tmux new-window -t session -n "Claude-AgentName" -c "/path/to/project"
```

--------------------------------

### Developer/Engineer Agent Briefing Template

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/configuration_and_setup.md

A sample briefing for an agent responsible for coding tasks. It outlines duties, initial analysis steps, and the process for starting the development server.

```text
You are responsible for the [PROJECT_NAME] codebase. Your duties include:
1. Getting the application running
2. Checking GitHub issues for priorities  
3. Working on highest priority tasks
4. Keeping the project manager informed of progress

First, analyze the project to understand:
- What type of project this is (check package.json, requirements.txt, etc.)
- How to start the development server
- What the main purpose of the application is

Then start the dev server in window 2 and begin working on priority issues.
```

--------------------------------

### Agent Communication Sequence: PM to Developer

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/operational_patterns.md

This script demonstrates a sequence for agent communication. It starts by assigning a task from a Project Manager (PM) to a developer, then monitors the developer's progress for errors or commits.

```bash
#!/bin/bash

SESSION="project"
DEVELOPER="0"
PM="1"

# 1. PM assigns task to developer
./send-claude-message.sh "$SESSION:$DEVELOPER" "TASK: Implement user authentication
Success criteria:
- POST /auth/login endpoint
- POST /auth/logout endpoint
- JWT token validation"

# Wait for developer to start
sleep 5

# 2. Monitor developer progress
for i in {1..12}; do
    sleep 300  # 5 minutes
    
    # Check developer output
    CONTENT=$(tmux capture-pane -t "$SESSION:$DEVELOPER" -p | tail -30)
    
    if echo "$CONTENT" | grep -q "error\|Error\|ERROR"; then
        echo "Developer encountered error, notifying PM"
        ./send-claude-message.sh "$SESSION:$PM" "Developer in window $DEVELOPER encountered error"
        break
    fi
    
    if echo "$CONTENT" | grep -q "commit\|COMMIT"; then
        echo "Developer made progress"
    fi
done
```

--------------------------------

### Self-Scheduling Loop Example

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/README.md

This bash script demonstrates an agent performing work and then scheduling its next check-in. The `exit` command is used to end the current session, allowing it to resume later.

```bash
# Agent performs work, then schedules next check
./schedule_with_note.sh 30 "Continue implementation" "session:0"
exit  # Exit current session, will resume later
```

--------------------------------

### Task Workflow Diagram

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Illustrates the step-by-step process for task management, from creation by a Project Manager to review, iteration, and final completion by a developer. This visual guide outlines the expected flow of work.

```markdown
1. PM Creates Task
   ↓
2. Developer Receives Assignment
   ↓
3. Developer Creates Feature Branch
   ↓
4. Developer Implements (commits every 30 min)
   ↓
5. Developer Reports Completion
   ↓
6. PM Reviews Code and Tests
   ↓
7. PM Approves and Merges OR Requests Changes
   ↓
8. If Changes Requested: Developer Iterates (back to step 4)
   ↓
9. Task Marked Complete
```

--------------------------------

### Get All Tmux Sessions and Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Retrieves a list of all active tmux sessions and their associated windows. Useful for monitoring and understanding the current tmux environment.

```python
orchestrator = TmuxOrchestrator()
sessions = orchestrator.get_tmux_sessions()

for session in sessions:
    print(f"Session: {session.name}")
    for window in session.windows:
        print(f"  Window {window.window_index}: {window.window_name}")
```

--------------------------------

### Perform Mandatory Startup Check for Orchestrators

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

This script must be run every time an orchestrator starts or restarts. It checks the current tmux location and tests the scheduling script with the current window. Fix the script if scheduling fails before proceeding.

```bash
# 1. Check your current tmux location
echo "Current pane: $TMUX_PANE"
CURRENT_WINDOW=$(tmux display-message -p "#{session_name}:#{window_index}")
echo "Current window: $CURRENT_WINDOW"

# 2. Test the scheduling script with your current window
./schedule_with_note.sh 1 "Test schedule for $CURRENT_WINDOW" "$CURRENT_WINDOW"

# 3. If scheduling fails, you MUST fix the script before proceeding
```

--------------------------------

### PM Introduction Protocol

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Captures the last 30 lines of the developer's window and sends an introductory message from the Project Manager. Ensures the PM's introduction is contextually relevant.

```bash
# Check developer window
tmux capture-pane -t [session]:0 -p | tail -30

# Introduce themselves
tmux send-keys -t [session]:0 "Hello! I'm the new Project Manager for this project. I'll be helping coordinate our work and ensure we maintain high quality standards. Could you give me a brief status update on what you're currently working on?"
sleep 1
tmux send-keys -t [session]:0 Enter
```

--------------------------------

### Verify Orchestrator Startup Checklist

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/configuration_and_setup.md

Run these commands to ensure the tmux environment is correctly set up and essential scripts are executable before operating as an orchestrator.

```bash
# 1. Check current tmux location
echo "Current pane: $TMUX_PANE"
CURRENT_WINDOW=$(tmux display-message -p "#{session_name}:#{window_index}")
echo "Current window: $CURRENT_WINDOW"

# 2. Test the scheduling script
./schedule_with_note.sh 1 "Test schedule" "$CURRENT_WINDOW"

# 3. Verify send-claude-message.sh is executable
ls -la send-claude-message.sh

# 4. Test message sending
./send-claude-message.sh "$CURRENT_WINDOW" "Test message"
```

--------------------------------

### Verify Agent Startup

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Captures the last 20 lines of the current tmux pane to verify the agent's startup process. A delay is included before capture.

```bash
sleep 5
tmux capture-pane -t session:window -p | tail -20
```

--------------------------------

### Get All Tmux Windows Status

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Generates a comprehensive snapshot of all Tmux sessions and windows, including their status, metadata, and recent output. Use this to get a complete overview of your Tmux environment.

```python
def get_all_windows_status(self) -> Dict:
    # Generates a comprehensive snapshot of all sessions and windows with their current status, metadata, and recent output.
```

--------------------------------

### Set Up Multi-Project Orchestration with Tmux

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/configuration_and_setup.md

Use these tmux commands to create a new session for the orchestrator and then create separate windows for each project's project manager (PM).

```bash
# Start orchestrator
tmux new-session -s orchestrator

# Create project windows
tmux new-window -t orchestrator -n "frontend-pm"
tmux new-window -t orchestrator -n "backend-pm"
tmux new-window -t orchestrator -n "mobile-pm"

# Brief each PM (happens in Claude)
# Each PM manages their own engineers
# Orchestrator coordinates between PMs
```

--------------------------------

### Tmux Window Creation and Command Execution Workflow

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

A comprehensive workflow for creating a new tmux window, navigating to a specific directory, activating a virtual environment, running a command, and verifying its startup.

```bash
# 1. Create window with correct directory
tmux new-window -t session -n "descriptive-name" -c "/path/to/project"

# 2. Verify you're in the right place
tmux send-keys -t session:descriptive-name "pwd" Enter
sleep 1
tmux capture-pane -t session:descriptive-name -p | tail -3

# 3. Activate virtual environment if needed
tmux send-keys -t session:descriptive-name "source venv/bin/activate" Enter

# 4. Run your command
tmux send-keys -t session:descriptive-name "your-command" Enter

# 5. Verify it started correctly
sleep 3
tmux capture-pane -t session:descriptive-name -p | tail -20
```

--------------------------------

### Filter Tmux Windows by Name

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Example of filtering a list of `TmuxWindow` objects to find those containing a specific name substring.

```python
# Filter windows by name
windows = orchestrator.get_tmux_sessions()
claude_windows = [
    w for session in windows
    for w in session.windows
    if "Claude" in w.window_name
]
```

--------------------------------

### Python Tmux Orchestrator API

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/START_HERE.md

Use these Python methods to interact with Tmux sessions programmatically. Ensure the `tmux_utils` library is installed.

```python
from tmux_utils import TmuxOrchestrator

orchestrator = TmuxOrchestrator()

# Get sessions
sessions = orchestrator.get_tmux_sessions()

# Get window content
content = orchestrator.capture_window_content("session", 0)

# Send command
orchestrator.send_command_to_window("session", 0, "ls")

# Get status
status = orchestrator.get_all_windows_status()

# Get report
snapshot = orchestrator.create_monitoring_snapshot()
```

--------------------------------

### Git Branching and Status Check

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/README.md

Create a new feature branch and check the Git status to ensure a clean working environment before starting a task.

```bash
git checkout -b feature/[task-name]
git status  # Ensure clean state
```

--------------------------------

### Print and Save Tmux Monitoring Snapshot

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Demonstrates how to generate a monitoring snapshot of the Tmux environment and either print it to the console or save it to a file for later analysis.

```python
snapshot = orchestrator.create_monitoring_snapshot()
print(snapshot)

# Or save for analysis
with open("monitoring_report.txt", "w") as f:
    f.write(snapshot)
```

--------------------------------

### Set Up Standard Tmux Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Configures standard windows within a Tmux session for different development tasks. This includes renaming the initial window for the Claude agent, and creating new windows for a general shell and the development server, each with its specified working directory.

```bash
# Window 0: Claude Agent
tmux rename-window -t $PROJECT_NAME:0 "Claude-Agent"

# Window 1: Shell
tmux new-window -t $PROJECT_NAME -n "Shell" -c "$PROJECT_PATH"

# Window 2: Dev Server (will start app here)
tmux new-window -t $PROJECT_NAME -n "Dev-Server" -c "$PROJECT_PATH"
```

--------------------------------

### Enforce Git Discipline

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/START_HERE.md

A workflow for creating feature branches, committing work, and repeating the process. This pattern is intended to be followed regularly, for example, every 30 minutes.

```bash
git checkout -b feature/task-name
# ... do work ...
git add -A && git commit -m "Progress: description"
# Repeat every 30 minutes
```

--------------------------------

### Sending Commands to Multiple Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Shows how to find windows by name and send a command to each of them, with an option to disable confirmation.

```python
# Execute same command across all Claude windows
claude_windows = orchestrator.find_window_by_name("claude")
for session_name, window_index in claude_windows:
    orchestrator.send_command_to_window(
        session_name, 
        window_index, 
        "echo 'Status check'", 
        confirm=False
    )
```

--------------------------------

### Project Manager: Request Test File from Developer

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Asks a developer agent to provide the test file for a specific module, ensuring test coverage.

```bash
./send-claude-message.sh developer:0 "Show me the test file for the auth module"
```

--------------------------------

### Schedule Agent Check-in

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/README.md

This snippet demonstrates how agents can schedule their own check-ins with a specified interval and a note. This is useful for maintaining progress and communication within the project.

```bash
./schedule_with_note.sh 30 "Continue dashboard implementation"
```

--------------------------------

### Create and Access TmuxWindow Object

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Instantiate a `TmuxWindow` object and access its attributes. Ensure `tmux_utils` is imported.

```python
from tmux_utils import TmuxWindow

# Create a window descriptor
window = TmuxWindow(
    session_name="frontend",
    window_index=0,
    window_name="Claude-Agent",
    active=True
)

# Access fields
print(f"Session: {window.session_name}")
print(f"Window: {window.window_name} (index {window.window_index})")
if window.active:
    print("This window is currently active")
```

--------------------------------

### List Project Directories

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Use this command to list all directories in a specified path and filter for potential project folders. It helps in identifying project names by listing directories and filtering out hidden files.

```bash
# List all directories in ~/Coding to find projects
ls -la ~/Coding/ | grep "^d" | awk '{print $NF}' | grep -v "^\."

# If project name is ambiguous, list matches
ls -la ~/Coding/ | grep -i "task"  # for "task templates"
```

--------------------------------

### Providing Assistance via Script

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Use the script to send helpful information or guidance to agents, such as error details or instructions for resolving issues.

```bash
# Share error information
/Users/jasonedward/Coding/Tmux\ orchestrator/send-claude-message.sh session:0 "I see in your server window that port 3000 is already in use. Try port 3001 instead."

# Guide stuck agents
/Users/jasonedward/Coding/Tmux\ orchestrator/send-claude-message.sh session:0 "The error you're seeing is because the virtual environment isn't activated. Run 'source venv/bin/activate' first."
```

--------------------------------

### Python API for Tmux Orchestrator

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/README.md

Use this Python API to manage tmux sessions, capture window content, send commands, and generate status reports. Ensure the `tmux_utils` library is installed.

```python
from tmux_utils import TmuxOrchestrator

orchestrator = TmuxOrchestrator()

# Get all sessions
sessions = orchestrator.get_tmux_sessions()

# Capture window content
content = orchestrator.capture_window_content("session", 0)

# Send command
orchestrator.send_command_to_window("session", 0, "ls", confirm=False)

# Get status snapshot
status = orchestrator.get_all_windows_status()

# Create readable report
snapshot = orchestrator.create_monitoring_snapshot()
```

--------------------------------

### Analyze Project and Determine Type

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Commands to locate a project directory and identify its type (Node.js or Python) by checking for specific project files. Navigate to the project directory after locating it.

```bash
# Find project
ls -la ~/Coding/ | grep -i "[project-name]"
```

```bash
# Analyze project type
cd ~/Coding/[project-name]
test -f package.json && echo "Node.js project"
test -f requirements.txt && echo "Python project"
```

--------------------------------

### Combined Message and Scheduling Script

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/shell_scripts_reference.md

This pattern demonstrates sending an immediate message using one script and scheduling a follow-up check using another. Useful for time-sensitive updates and subsequent verification.

```bash
# Send immediate message
./send-claude-message.sh project:0 "Starting implementation now"
```

```bash
# Schedule check for later
./schedule_with_note.sh 30 "Check if implementation is complete"
```

--------------------------------

### Get Detailed Tmux Window Information

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Retrieves metadata for a specific tmux window, including its name, active status, pane count, layout, and recent output. Useful for detailed inspection of a window's state.

```python
info = orchestrator.get_window_info("project", 0)
print(f"Window: {info['name']}")
print(f"Active: {info['active']}")
print(f"Panes: {info['panes']}")
print(f"Recent output:\n{info['content']}")
```

--------------------------------

### Create Monitoring Snapshot

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Generates a plain text snapshot of the current tmux environment, including session and window details with recent output. This is useful for human reading and automated analysis. The output format includes timestamps, session status, and window activity.

```python
snapshot = orchestrator.create_monitoring_snapshot()

# The output looks like:
# Tmux Monitoring Snapshot - 2025-06-23T14:30:45.123456
# ==================================================
#
# Session: orchestrator (ATTACHED)
# ------------------------------
#   Window 0: Claude-Orchestrator (ACTIVE)
#     Recent output:
#     | Ready to coordinate projects
#     | Checking status on backend team...
#
#   Window 1: Status-Monitor
#     Recent output:
#     | [14:30] Frontend: 2 tasks complete
#     | [14:30] Backend: working on auth

# Store for Claude analysis
with open("monitoring_report.txt", "w") as f:
    f.write(snapshot)

# Analyze for issues
if "ERROR" in snapshot or "error" in snapshot.lower():
    print("Issues detected in monitoring snapshot!")
    # Extract problem windows
    lines = snapshot.split('\n')
    for i, line in enumerate(lines):
        if "error" in line.lower():
            print(f"  {line}")
```

--------------------------------

### Script Execution and Permissions

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Ensure scripts are executable by using `chmod +x`. This is necessary when encountering 'Permission denied' errors.

```bash
chmod +x script.sh
```

--------------------------------

### Use Default Window for Scheduling

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/configuration_and_setup.md

When scheduling, if a specific target window is problematic, use this command to default to the first available window.

```bash
./schedule_with_note.sh 30 "note"
```

--------------------------------

### Create and Configure Tmux Session

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Use this to create a new detached tmux session with a specific name and working directory. It's the first step in setting up a project environment.

```bash
# Create session
tmux new-session -d -s project -c /path/to/project
```

--------------------------------

### Tmux Session and Window Management

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/quick_reference.md

Commands for creating new tmux sessions and windows, useful when encountering 'Session not found' or 'Window index out of range' errors.

```bash
tmux new-session
```

```bash
tmux new-window
```

--------------------------------

### Bash Parameter Expansion for Message Handling

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/shell_scripts_reference.md

Demonstrates the use of `shift` and `$*` in bash to correctly capture messages containing spaces and special characters as a single argument.

```bash
WINDOW="$1"
shift  # Removes first argument
MESSAGE="$*"  # Captures all remaining args as single string
```

--------------------------------

### Specify Directory When Creating Tmux Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md

Use the -c flag with `tmux new-window` to ensure new windows are created in the correct directory. Alternatively, `cd` into the desired directory immediately after window creation.

```bash
# Always use -c flag when creating windows
tmux new-window -t session -n "window-name" -c "/correct/path"

# Or immediately cd after creating
tmux new-window -t session -n "window-name"
tmux send-keys -t session:window-name "cd /correct/path" Enter
```

--------------------------------

### Schedule Agent Wake-up with Context

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/START_HERE.md

Schedules an agent to wake up after a specified time with provided context and a target session/window.

```bash
./schedule_with_note.sh 30 "Continue work" "session:0"
# Agent wakes up in 30 minutes with context
```

--------------------------------

### Document Agent Handoff with Git

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Shows the last 10 Git log entries and detailed statistics for the HEAD commit to document changes made by the agent during its task.

```bash
git log --oneline | head -10  # Show recent commits
git show --stat HEAD          # Show what changed
```

--------------------------------

### create_monitoring_snapshot

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Generates a human-readable text report of all tmux sessions and windows, including recent output, suitable for analysis and monitoring.

```APIDOC
## create_monitoring_snapshot

### Description
Creates a human-readable text snapshot of all sessions and windows designed for Claude analysis and monitoring. Includes recent output from each window for context.

### Method Signature
```python
def create_monitoring_snapshot(self) -> str:
```

### Parameters
None

### Returns
- **str** - Formatted text report suitable for display or analysis.

### Example
```python
snapshot = orchestrator.create_monitoring_snapshot()
print(snapshot)

# Or save for analysis
with open("monitoring_report.txt", "w") as f:
    f.write(snapshot)
```

### Output Format Example
```
Tmux Monitoring Snapshot - 2025-06-23T14:30:45.123456
==================================================

Session: orchestrator (ATTACHED)
------------------------------
  Window 0: Claude-Orchestrator (ACTIVE)
    Recent output:
    | Last 10 lines of output...
    | ...

  Window 1: Status-Monitor
    Recent output:
    | ... 
```
```

--------------------------------

### Project Manager: Brief Developer on Task

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/agent_architecture.md

Assigns a specific task to a developer agent, including details on the required pattern and endpoints.

```bash
./send-claude-message.sh developer:0 "TASK: Implement user authentication endpoints following OAuth2 pattern"
```

--------------------------------

### Create Tmux Monitoring Snapshot

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Generates a human-readable text snapshot of all Tmux sessions and windows, including recent output from each window. This snapshot is designed for analysis and monitoring.

```python
def create_monitoring_snapshot(self) -> str:
    # Creates a human-readable text snapshot of all sessions and windows designed for Claude analysis and monitoring.
```

--------------------------------

### get_all_windows_status

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/tmux_utils_api.md

Generates a comprehensive snapshot of all tmux sessions and windows, including their status, metadata, and recent output.

```APIDOC
## get_all_windows_status

### Description
Generates a comprehensive snapshot of all sessions and windows with their current status, metadata, and recent output.

### Method Signature
```python
def get_all_windows_status(self) -> Dict:
```

### Parameters
None

### Returns
- **Dict** - A dictionary containing the status of all sessions and windows. Structure:
```json
{
  "timestamp": "2025-06-23T14:30:45.123456",
  "sessions": [
    {
      "name": "session-name",
      "attached": bool,
      "windows": [
        {
          "index": int,
          "name": str,
          "active": bool,
          "info": {...}  # from get_window_info
        },
        ...
      ]
    },
    ...
  ]
}
```

### Example
```python
status = orchestrator.get_all_windows_status()
print(f"Captured at: {status['timestamp']}")

for session in status['sessions']:
    print(f"Session {session['name']}: {'attached' if session['attached'] else 'detached'}")
    for window in session['windows']:
        active = " [ACTIVE]" if window['active'] else ""
        print(f"  Window {window['index']}: {window['name']}{active}")
```
```

--------------------------------

### Handle List Results for Window Matches

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

List return types, such as those from `find_window_by_name`, may be empty if no matches are found. Iterate through the list to process found windows.

```python
matches = orchestrator.find_window_by_name("NonExistent")

if not matches:
    print("No matching windows found")
else:
    for session_name, window_index in matches:
        print(f"Found: {session_name}:{window_index}")
```

--------------------------------

### Find Window by Name

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Returns a list of tuples, where each tuple contains the session name and window index for matching windows. Use this to locate specific tmux windows.

```python
matches = orchestrator.find_window_by_name("Claude")
for session_name, window_index in matches:
    print(f"Found Claude window: {session_name}:{window_index}")

# Use matches to send messages
for session_name, window_index in matches:
    content = orchestrator.capture_window_content(session_name, window_index)
    if "blocked" in content.lower():
        print(f"Intervention needed in {session_name}:{window_index}")
```

--------------------------------

### System Architecture Overview

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/START_HERE.md

This diagram illustrates the high-level architecture of the tmux-orchestrator system, showing how agents are managed across multiple tmux sessions and how project managers coordinate developer agents.

```text
Your Orchestrator (Claude in tmux)
    ↓ Monitors & coordinates
    ├─ Project Manager 1 → Developer 1, Developer 2
    └─ Project Manager 2 → Developer 3, Developer 4
```

--------------------------------

### List Tmux Sessions and Windows

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/data_types.md

Retrieves all tmux sessions and iterates through them to print session details and their associated windows. Requires `TmuxOrchestrator` to be initialized.

```python
from tmux_utils import TmuxOrchestrator

orchestrator = TmuxOrchestrator()
sessions = orchestrator.get_tmux_sessions()

for session in sessions:
    print(f"Session: {session.name}")
    print(f"Attached: {'Yes' if session.attached else 'No (detached)'}")
    print(f"Windows: {len(session.windows)}")
    
    for window in session.windows:
        active_marker = " *" if window.active else ""
        print(f"  [{window.window_index}] {window.window_name}{active_marker}")
```

--------------------------------

### Verify Claude Plan Mode Activation with tmux

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/LEARNINGS.md

This command captures the current pane's content in tmux and searches for the confirmation string 'plan mode on'. Use this to ensure plan mode was successfully activated.

```bash
tmux capture-pane | grep "plan mode on"
```

--------------------------------

### Execute and Verify Command in Tmux

Source: https://github.com/jedward23/tmux-orchestrator/blob/main/_autodocs/operational_patterns.md

Send a command to a tmux window, wait for its execution, and then capture and check the output for common error indicators. This pattern is useful for ensuring commands complete successfully before proceeding.

```bash
#!/bin/bash

# 1. Send command
tmux send-keys -t $SESSION:$WINDOW "your-command" Enter

# 2. Wait for execution
sleep 2

# 3. Verify result
RESULT=$(tmux capture-pane -t $SESSION:$WINDOW -p | tail -5)

# 4. Check for errors
if echo "$RESULT" | grep -i "error\|failed\|not found"; then
    echo "Command failed!"
else
    echo "Command succeeded"
fi
```