How alvinunreal/tmuxai works
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)