# jedward23/tmux-orchestrator architecture

> Architecture diagram of the GitHub repository jedward23/tmux-orchestrator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jedward23/tmux-orchestrator
- Repository: https://github.com/jedward23/tmux-orchestrator

## Overview

##### Project type and purpose
- This is a CLI-based orchestration tool that runs multiple Claude AI agents inside tmux sessions.
- It provides autonomous agent scheduling, coordination, persistence, and Git backup for multi-agent workflows.

##### File structure
- Top-level scripts:
- send-claude-message.sh – sends messages to any Claude agent window
- schedule_with_note.sh – schedules future check-ins with notes
- tmux_utils.py – Python utilities for tmux session/window discovery
- tmux orchestration helper files (.claude/commands/*.md, CLAUDE.md)
- README.md, LEARNINGS.md – documentation and knowledge base
- Examples/ – sample screenshots of orchestrator, PMs, and engineers in action
- .pycache/ – compiled tmux_utils cache

##### Extract architecture insights from README
- Three-tier agent hierarchy:
1. Orchestrator agent (root coordinator)
2. Multiple Project Manager agents
3. Multiple Engineer agents under each PM
- Core technologies:
- tmux for session/window management and persistence
- Bash scripts for scheduling and messaging
- Python helper library for tmux introspection
- Git for automatic backups and versioning
- Autonomous features: self-triggered check-ins, cross-project coordination, parallelism

##### Detail capture
- That .claude/commands defines custom agent behaviors
- That CLAUDE.md and LEARNINGS.md are static knowledge sources consulted by agents
- Examples/ as a demonstration artifact, not part of runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and tmux
    UserCLI["User / CLI"]:::user
    UserCLI -->|"launch orchestrator"| tmuxServer["tmux Server"]:::tmux

    subgraph "Tmux Environment"
        direction TB
        tmuxServer
        subgraph "Orchestrator Session"
            direction TB
            Orchestrator["Orchestrator Agent (window 0)"]:::tmux
            Orchestrator -->|"spawns"| PM_Agents["Project Manager Agents"]:::tmux
            subgraph "Project Manager Agents"
                direction TB
                PM1["PM Agent 1"]:::tmux
                PM2["PM Agent 2"]:::tmux
            end
            PM_Agents -->|"spawn"| Engineer_Agents["Engineer Agents"]:::tmux
            subgraph "Engineer Agents"
                direction TB
                E1["Engineer Agent 1"]:::tmux
                E2["Engineer Agent 2"]:::tmux
            end
        end
    end

    %% Scripts and Python util
    schedule["schedule_with_note.sh"]:::script
    sendMsg["send-claude-message.sh"]:::script
    tmuxUtil["tmux_utils.py"]:::python

    schedule -->|"triggers"| sendMsg
    sendMsg -->|"uses"| tmuxServer
    sendMsg -->|"calls"| tmuxUtil

    %% Persistence and storage
    nextNote["next_check_note.txt"]:::storage
    GitRepo["Git Repository"]:::git
    Orchestrator -->|"monitors & commits"| GitRepo
    PM_Agents -->|"review & commit"| GitRepo
    Engineer_Agents -->|"code & commit"| GitRepo
    schedule -->|"writes note to"| nextNote

    %% Static docs and examples
    subgraph "Documentation & Artifacts"
        direction TB
        commandsDir[".claude/commands/"]:::docs
        pmBehavior["pm-oversight.md"]:::docs
        claudeRef["CLAUDE.md"]:::docs
        learnings["LEARNINGS.md"]:::docs
        examples["Examples/"]:::docs
    end

    Orchestrator -->|"consults behaviors"| commandsDir
    commandsDir --> pmBehavior
    Orchestrator -->|"reference"| claudeRef
    Orchestrator -->|"knowledge base"| learnings
    Orchestrator -->|"demos"| examples

    %% Click Events
    click schedule "https://github.com/jedward23/tmux-orchestrator/blob/main/schedule_with_note.sh"
    click sendMsg "https://github.com/jedward23/tmux-orchestrator/blob/main/send-claude-message.sh"
    click tmuxUtil "https://github.com/jedward23/tmux-orchestrator/blob/main/tmux_utils.py"
    click commandsDir "https://github.com/jedward23/tmux-orchestrator/tree/main/.claude/commands/"
    click pmBehavior "https://github.com/jedward23/tmux-orchestrator/blob/main/.claude/commands/pm-oversight.md"
    click claudeRef "https://github.com/jedward23/tmux-orchestrator/blob/main/CLAUDE.md"
    click learnings "https://github.com/jedward23/tmux-orchestrator/blob/main/LEARNINGS.md"
    click examples "https://github.com/jedward23/tmux-orchestrator/tree/main/Examples/"
    click nextNote "https://github.com/jedward23/tmux-orchestrator/blob/main/next_check_note.txt"

    %% Styles
    classDef tmux fill:#cce5ff,stroke:#004085,color:#004085
    classDef script fill:#d4edda,stroke:#155724,color:#155724
    classDef python fill:#fff3cd,stroke:#856404,color:#856404
    classDef git fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef docs fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef storage fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef user fill:#f5c6cb,stroke:#721c24,color:#721c24
```
