# alvinunreal/tmuxai architecture

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

- Interactive diagram: https://gitdiagram.com/alvinunreal/tmuxai
- Repository: https://github.com/alvinunreal/tmuxai

## Overview

##### Project type and purpose
- TmuxAI is an open-source CLI tool (written in Go) that embeds an AI “pair programmer” inside your tmux session.
- It observes the content of tmux panes, maintains a chat history, sends context + user messages to an AI API, and (with permission) executes commands in a dedicated tmux pane.

##### High-level architecture derived from file structure and README
- Single Go binary (main.go)
- cli/cli.go: command-line parsing & subcommands
- config/: loading YAML or env-var configuration
- internal/: core orchestration & business logic
– manager.go: high-level workflow controller
– chat.go, chat_command.go, prompts.go: chat REPL & command parsing
– process_message.go / process_response.go: request/response pipeline
– confirm.go / countdown.go / squash.go: interactive features
– exec_pane.go / pane_details.go: per-pane metadata & execution rules
– ai_client.go: HTTP client to AI provider (OpenRouter/OpenAI/Anthropic)
- system/: abstraction over tmux operations
– tmux.go / tmux_send.go: send tmux commands & capture pane content
– cosmetics.go / formatter.go: ANSI styling & output formatting
- logger/logger.go: structured logging
- Supporting files
- config.example.yaml: sample configuration
- tasks/: example task files for CLI “-f” mode
- install.sh, goreleaser.yml, GitHub workflows, LICENSE, etc.

##### Main components
a. TmuxAI CLI Process (single Go application)
- Modules inside the process:
- CLI Parser
- Config Loader
- Manager (Workflow Orchestrator)
- Chat Engine & Prompt Builder
- AI Client (HTTP adapter)
- System Adapter (tmux integration)
- Executor (exec pane controller)
- Logger
b. External Dependencies
- tmux (Unix-based terminal multiplexer)
- AI Service Endpoint (OpenRouter/OpenAI/Anthropic/Ollama)
- User’s Shell & Panes (bash, zsh, fish)
c. Configuration Store
- config file (~/.config/tmuxai/config.yaml) or environment variables
d. User & I/O
- Chat Pane (stdin/stdout REPL-like)
- Exec Pane (command injection)
- Read-Only Panes (context capture)

##### Relationships and data flow
1. User invokes `tmuxai` → CLI Parser reads flags & loads Config
2. Manager initializes System Adapter → queries tmux for existing panes
3. Manager enters Observe/Prepare/Watch loop:
- System Adapter captures Pane Contents → returns structured text + metadata
- Chat Engine + Prompt Builder + previous history → constructs AI request
- AI Client sends HTTP request to AI Provider → receives response
- Manager parses response → may produce suggested shell command
- If command: Manager triggers Confirm → on approval, Executor sends command via System Adapter to Exec Pane
- Wait interval or shell markers → System Adapter captures new output → loop
4. All modules log to Logger

##### Architectural patterns & principles
- Layered modular design:
- CLI layer → Config layer → Business Logic (Manager/Chat) → System Integration → External Services
- Command pattern for chat commands (`/watch`, `/prepare`, `/squash`)
- Adapter pattern for tmux (system package) and AI API (internal/ai_client.go)
- Separation of concerns between capturing context, building prompts, sending AI requests, and executing commands

##### Details to capture
- The three tmux pane roles (Chat, Exec, Read-Only) and how System Adapter treats each
- The prompt lifecycle: capture → build prompt → send → receive → parse
- Confirmation and squashing workflows as sub-flows off the main loop
- Config override hierarchy (YAML → env vars → CLI flags → runtime `/config`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    User[("User")]:::external
    AIProvider[(AI Service Endpoint)]:::external
    ReadOnlyPanes[("Read-Only Panes")]:::external
    ChatPane[("Chat Pane")]:::external
    ExecPane[("Exec Pane")]:::external

    %% Main Process
    subgraph "TmuxAI Process"
        direction TB

        %% CLI Layer
        CLI["CLI Parser"]:::core
        click CLI "https://github.com/alvinunreal/tmuxai/blob/main/cli/cli.go"

        %% Configuration Layer
        ConfigLoader["Config Loader"]:::config
        click ConfigLoader "https://github.com/alvinunreal/tmuxai/blob/main/config/config.go"
        ConfigEnv["Env Vars"]:::config
        ConfigFile[(Config File)]:::config
        click ConfigFile "https://github.com/alvinunreal/tmuxai/blob/main/config.example.yaml"

        %% Business Logic Layer
        Manager["Manager (Orchestrator)"]:::core
        click Manager "https://github.com/alvinunreal/tmuxai/blob/main/internal/manager.go"
        ChatEngine["Chat Engine & Prompt Builder"]:::core
        click ChatEngine "https://github.com/alvinunreal/tmuxai/blob/main/internal/chat.go"
        click ChatEngine "https://github.com/alvinunreal/tmuxai/blob/main/internal/chat_command.go"
        click ChatEngine "https://github.com/alvinunreal/tmuxai/blob/main/internal/prompts.go"
        Pipeline["Request/Response Pipeline"]:::core
        click Pipeline "https://github.com/alvinunreal/tmuxai/blob/main/internal/process_message.go"
        click Pipeline "https://github.com/alvinunreal/tmuxai/blob/main/internal/process_response.go"
        Interactive["Interactive Features"]:::core
        click Interactive "https://github.com/alvinunreal/tmuxai/blob/main/internal/confirm.go"
        click Interactive "https://github.com/alvinunreal/tmuxai/blob/main/internal/countdown.go"
        click Interactive "https://github.com/alvinunreal/tmuxai/blob/main/internal/squash.go"
        PaneMeta["Pane Metadata & Exec Rules"]:::core
        click PaneMeta "https://github.com/alvinunreal/tmuxai/blob/main/internal/pane_details.go"

        %% Adapters
        AIC["AI Client"]:::adapter
        click AIC "https://github.com/alvinunreal/tmuxai/blob/main/internal/ai_client.go"
        SystemAdapter["System Adapter"]:::adapter
        click SystemAdapter "https://github.com/alvinunreal/tmuxai/blob/main/system/tmux.go"
        click SystemAdapter "https://github.com/alvinunreal/tmuxai/blob/main/system/tmux_send.go"
        click SystemAdapter "https://github.com/alvinunreal/tmuxai/blob/main/system/types.go"
        click SystemAdapter "https://github.com/alvinunreal/tmuxai/blob/main/system/utils.go"
        Executor["Executor"]:::adapter
        click Executor "https://github.com/alvinunreal/tmuxai/blob/main/internal/exec_pane.go"

        %% Logging
        Logger["Logger"]:::logger
        click Logger "https://github.com/alvinunreal/tmuxai/blob/main/logger/logger.go"

        %% Wiring
        CLI -->|"flags|args"| ConfigLoader
        ConfigEnv --> ConfigLoader
        ConfigFile --> ConfigLoader
        ConfigLoader -->|config| Manager
        CLI -->|args| Manager

        Manager -->|ObserveLoop| SystemAdapter
        SystemAdapter -->|PaneContents| Manager
        Manager -->|buildPrompt| ChatEngine
        ChatEngine -->|AIRequest| AIC
        AIC -->|"HTTP"| AIProvider
        AIProvider -->|AIResponse| AIC
        AIC -->|response| Pipeline
        Pipeline -->|parsedResponse| Manager
        Manager -->|ShellCommand| Executor
        Executor -->|sendCmd| SystemAdapter
        SystemAdapter -->|output| Manager

        Manager -->|log| Logger
        ConfigLoader -->|log| Logger
        CLI -->|log| Logger

    end

    %% User & Panes
    User -->|"invoke tmuxai"| CLI
    SystemAdapter --> ReadOnlyPanes
    SystemAdapter --> ChatPane
    Executor --> ExecPane

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0284C7,stroke-width:1px
    classDef adapter fill:#D5F5E3,stroke:#28A745,stroke-width:1px
    classDef config fill:#FFE5B4,stroke:#E67E22,stroke-width:1px
    classDef logger fill:#F2F2F2,stroke:#6C757D,stroke-width:1px
    classDef external fill:#F5E1FF,stroke:#6F42C1,stroke-width:1px,stroke-dasharray: 5 5
```
