maestro-tui

A dual-pane terminal multiplexer designed for AI-assisted development workflows.

Why maestro-tui?

Modern AI coding assistants like Claude Code are powerful, but juggling between your terminal and an AI session breaks your flow. maestro-tui solves this by putting your shell and Claude Code side-by-side in a unified interface.

One worktree, one tab. Each task gets its own git worktree and dedicated tab. Start a new feature? Type a prompt, and maestro-tui creates a fresh worktree with Claude Code ready to help. No more context switching. No more branch juggling. Just focused, parallel workstreams.

Key Features

• Dual-pane layout - Diff viewer on the left, Claude Code on the right. Always visible, always accessible.
• Worktree-per-tab - Each tab is a separate git worktree. Work on multiple features simultaneously without stashing or branch switching.
• Prompt-driven workflow - Describe what you want to build in the control panel. Maestro creates the worktree and tab automatically.
• Live diff viewer - See your uncommitted changes in real-time with syntax highlighting. File watcher automatically refreshes when files change.
• Theme picker - Choose from 5 built-in themes: Flexoki Dark, Dracula, Nord, Catppuccin Mocha, and Gruvbox Dark.
• Touch-friendly - Clickable tabs and quit button. Works great over SSH from an iPad.
• Vim-style keybindings - Alt-based shortcuts for all navigation: Alt+1-9 for tabs, Alt+h/l for panes, Alt+u/d for scrolling.

Installation

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/fikriauliya/maestro-tui/refs/heads/main/install.sh | bash

From crates.io

cargo install maestro-tui

Prerequisites

• Claude Code installed and configured
• Git

Build from source

git clone https://github.com/fikriauliya/maestro-tui.git
cd maestro-tui
cargo build --release

The binary will be at target/release/maestro-tui.

Usage

maestro-tui
# or use the short alias
mae

Tabs

• Tab 1 (Alt+1) - Control panel for creating new worktree tabs, with Claude terminal on the right
• Tab 2+ (Alt+2-9) - Worktree tabs with diff viewer on the left, Claude Code on the right

Keyboard Shortcuts

Mouse

• Click tabs to switch
• Click [X] to quit

Creating a New Task

1. Go to the control panel with Alt+1 or click Tab 1
2. Type a prompt describing your task
3. Press Enter

Maestro creates a new git worktree and tab with Claude Code ready to assist.

For Developers

Project Structure

src/
├── main.rs          # Entry point, event loop
├── app.rs           # Application state, commands, key handling
├── render.rs        # UI rendering with Ratatui
├── event_handler.rs # Keyboard and mouse event processing
├── terminal.rs      # PTY management, terminal emulation
├── terminal_pair.rs # Dual terminal pane management
├── diff_viewer.rs   # Git diff display with syntax highlighting
├── file_watcher.rs  # File system watcher for auto-refresh
├── theme.rs         # Color themes (Flexoki, Dracula, Nord, etc.)
├── input.rs         # Key-to-bytes conversion for terminal
├── pty.rs           # PTY abstraction with mock for testing
└── worktree.rs      # Git worktree management

Building

cargo build          # Debug build
cargo build --release  # Optimized release build

Testing

cargo test           # Run all tests
cargo test -- --nocapture  # With output

Code Quality

cargo fmt            # Format code
cargo clippy         # Lint
cargo check          # Type check without building

Architecture

• Ratatui for terminal UI rendering
• Alacritty Terminal for terminal emulation
• portable-pty for cross-platform PTY handling
• notify for file system watching (event-driven diff updates)
• 5 color themes - Flexoki Dark (default), Dracula, Nord, Catppuccin Mocha, Gruvbox Dark

The app runs a 60fps render loop. Each terminal pane has a background reader thread for PTY output. File changes are detected via inotify (Linux) / FSEvents (macOS) for efficient diff refreshing. State is shared via Arc<Mutex<T>>.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run cargo test and cargo clippy
5. Submit a pull request

Issue Tracking with Beads

This project uses Beads for issue tracking - an AI-native tool that stores issues directly in the repository (.beads/ directory).

Why Beads?

• AI-friendly - CLI-first design works seamlessly with AI coding agents like Claude Code
• Git-native - Issues sync with your commits, no external service required
• Works offline - Everything is local, syncs when you push

Quick Reference

# Find available work
bd ready

# View issue details
bd show <issue-id>

# Start working on an issue
bd update <issue-id> --status in_progress

# Complete an issue
bd close <issue-id>

# Create a new issue
bd create --title="Fix bug in diff viewer" --type=bug --priority=2

# Sync with git
bd sync

Installing Beads

curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

See the Beads documentation for more details.

License

MIT