DOCSEARCHbyAlgolia
Submit Docs

tmux-orchestrator

repository·main·Indexed 23 days ago

https://github.com/jedward23/tmux-orchestrator

A system for running autonomous AI agents (specifically Claude) 24/7 within tmux sessions. It utilizes a three-tier hierarchical architecture consisting of an Orchestrator, Project Managers, and Engineers to manage complex, multi-project workflows. The toolkit includes scripts for cross-agent communication (send-claude-message.sh) and autonomous check-in scheduling (schedule_with_note.sh).

Tokens
2.9K
Snippets
6
Records
14
Agent score
33%

What's inside tmux-orchestrator

  1. How the Tmux Orchestrator Architecture Works

    main

    The orchestrator uses a three-tier hierarchy to manage complexity and overcome context window limitations:

    1. Orchestrator: The top tier where you interact. It monitors and coordinates all active projects.
    2. Project Managers: Middle tier agents assigned to specific projects. They enforce specifications and assign tasks to engineers.
    3. Engineers: The bottom tier agents that perform the actual work (writing code, fixing bugs) within specific codebases.

    This separation allows for specialized expertise, parallel work across multiple teams, and better memory recall due to smaller, focused contexts.

  2. Manage multi-agent coordination using a Hub-and-Spoke model

    main
    As the number of agents increases, communication complexity grows exponentially ($n^2$). To mitigate this, use a Hub-and-Spoke model where the Project Manager (PM) acts as the central coordinator. Use structured communication templates to reduce overhead and ambiguity between agents.

  3. Manage agent lifecycles and logging

    main

    Distinguish between permanent and temporary agents to maintain system order. Implement proper logging before terminating any agent.

    Recommended Directory Structure:

    • agent_logs/permanent/ for long-running agents
    • agent_logs/temporary/ for short-lived task agents

  4. Use effective communication patterns for status reports

    main

    When managing agents or developers, avoid open-ended questions like "How's it going?". Instead, use specific, numbered questions to force clear, actionable responses. This reduces ambiguity and provides better oversight.

    Effective Pattern Example: "STOP. Give me status: 1) X fixed? YES/NO 2) Current error?"

  5. Implement a reminder system with schedule_with_note.sh

    main
    To ensure follow-up tasks are not missed, use the schedule_with_note.sh script. When scheduling reminders, avoid vague descriptions like "check progress". Instead, always include concrete next steps and specific action items.

  6. Quick Start: Basic Setup for a Single Project

    main

    To set up a single project with an autonomous agent, follow these steps:

    1. Create a project spec: Define your project goals, constraints, and deliverables in a markdown file (e.g., project_spec.md).
    2. Start a tmux session: Create a new session to host the project.
    3. Initialize the Project Manager: Start claude in the first window and provide it with the project specification, instructing it to create an engineer in a separate window.
    4. Schedule check-ins: Use the scheduling script to ensure the orchestrator or PM continues work autonomously.

    Example workflow:

    # 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"
    # 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"

  7. Quick Start: Full Orchestrator Setup

    main

    To manage multiple projects simultaneously, start the orchestrator in a dedicated tmux session and assign it multiple project managers with specific tasks.

    # 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."
    # 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."

  8. Git Safety Rules for Autonomous Agents

    main

    To prevent lost work and ensure stability, enforce the following Git workflow for all agents:

    1. Before starting a task: Create a new feature branch and ensure the working directory is clean.
      git checkout -b feature/[task-name]
git status
    2. During work: Commit progress every 30 minutes.
      git add -A
git commit -m "Progress: [what was accomplished]"
    3. Upon completion: Tag the stable version, merge into main, and clean up.
      git tag stable-[feature]-[date]
git checkout main
git merge feature/[task-name]
    # 1. Before Starting Any Task
git checkout -b feature/[task-name]
git status  # Ensure clean state

# 2. Every 30 Minutes
git add -A
git commit -m "Progress: [what was accomplished]"

# 3. When Task Completes
git tag stable-[feature]-[date]
git checkout main
git merge feature/[task-name]

  9. Best Practices for Writing Project Specifications

    main

    To prevent agent drift and unpredictable results, always start with a clear, written specification. An effective spec should include:

    • PROJECT: Name of the project.
    • GOAL: High-level objective.
    • CONSTRAINTS: Rules the agent must follow (e.g., existing patterns, commit frequency, API limits).
    • DELIVERABLES: Specific, measurable items to be produced.
    • SUCCESS CRITERIA: How the agent knows the task is complete (e.g., validation, error-free processing).

    Example Template:

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

  10. Activate Claude Plan Mode via Tmux

    main

    Claude features a 'plan mode' that forces a thoughtful approach before coding begins. To activate this mode within a tmux session, you must send the specific key sequence Shift+Tab+Tab.

    Critical Verification: You must verify that the text ⏸ plan mode on appears in the pane. If it does not appear, you may need to send additional S-Tab sequences until confirmed.

    Usage Pattern: Always verify activation before sending a planning request to ensure the model is in the correct state.

  11. Avoid common orchestration pitfalls

    main

    To maintain project velocity and quality, avoid these common mistakes:

    • Not Using Available Tools: Failing to leverage web search, documentation, or community resources.
    • Circular Problem Solving: Repeatedly attempting the same failed approach without stepping back.
    • Missing Context: Neglecting to check other tmux windows for error details or logs.
    • Poor Time Management: Not setting time limits on debugging attempts.
    • Incomplete Handoffs: Failing to document solutions for future agents.

  12. Troubleshooting Common Pitfalls

    main

    Use this table to resolve common issues encountered when running the orchestrator:

    PitfallConsequenceSolution
    Vague instructionsAgent drift, wasted computeWrite clear, specific specs
    No git commitsLost work, frustrated devsEnforce 30-minute commit rule
    Too many tasksContext overload, confusionOne task per agent at a time
    No specificationsUnpredictable resultsAlways start with written spec
    Missing checkpointsAgents stop workingSchedule regular check-ins