TmuxAI

Your intelligent pair programmer directly within your tmux sessions.








Screenshots |
Report Bug |
Request Feature


Tmux Cheat Sheet |
Tmux Getting Started |
Tmux Config Generator

Table of Contents

• About The Project
  • Human-Inspired Interface
• Installation
  • Quick Install
  • Homebrew
  • Manual Download
  • Install from Main
• Post-Installation Setup
• TmuxAI Layout
• Observe Mode
• Prepare Mode
• Watch Mode
  • Activating Watch Mode
  • Example Use Cases
• Knowledge Base
  • Creating Knowledge Bases
  • Using Knowledge Bases
  • Auto-Loading Knowledge Bases
• Model Configuration
  • Setting Up Multiple Models
  • Switching Between Models
• Squashing
  • What is Squashing?
  • Manual Squashing
• Core Commands
• Command-Line Usage
• Configuration
  • Environment Variables
  • Session-Specific Configuration
• Contributing
• License

About The Project

!Product Demo (https://tmuxai.dev/demo.png)

TmuxAI is an intelligent terminal assistant that lives inside your tmux sessions. Unlike other CLI AI tools, TmuxAI observes and understands the content of your tmux panes, providing assistance without requiring you to change your workflow or interrupt your terminal sessions.

Think of TmuxAI as a pair programmer that sits beside you, watching your terminal environment exactly as you see it. It can understand what you're working on across multiple panes, help solve problems and execute commands on your behalf in a dedicated execution pane.

Human-Inspired Interface

TmuxAI's design philosophy mirrors the way humans collaborate at the terminal. Just as a colleague sitting next to you would observe your screen, understand context from what's visible, and help accordingly, TmuxAI:

1. Observes: Reads the visible content in all your panes
2. Communicates: Uses a dedicated chat pane for interaction
3. Acts: Can execute commands in a separate execution pane (with your permission)

This approach provides powerful AI assistance while respecting your existing workflow and maintaining the familiar terminal environment you're already comfortable with.

Installation

TmuxAI requires only tmux to be installed on your system. It's designed to work on Unix-based operating systems including Linux and macOS.

Quick Install

The fastest way to install TmuxAI is using the installation script:

# install tmux if not already installed
curl -fsSL https://get.tmuxai.dev | bash

This installs TmuxAI to /usr/local/bin/tmuxai by default. If you need to install to a different location or want to see what the script does before running it, you can view the source at get.tmuxai.dev (https://get.tmuxai.dev).

Manual Download

You can also download pre-built binaries from the GitHub releases page (https://github.com/alvinunreal/tmuxai/releases).

After downloading, make the binary executable and move it to a directory in your PATH:

chmod +x ./tmuxai
sudo mv ./tmuxai /usr/local/bin/

Install from Main

To install the latest development version directly from the main branch:

go install github.com/alvinunreal/tmuxai@main

Note: The main branch contains the latest features and fixes but may be less stable than official releases.

Post-Installation Setup

TmuxAI reads its configuration from ~/.config/tmuxai/config.yaml. To get running, create the file with a model entry that points at the provider you use.

1. Create the config path

   mkdir -p ~/.config/tmuxai
   vim ~/.config/tmuxai/config.yaml
   

2. Add a minimal config

   models:
     primary:
       provider: openrouter  # openrouter, openai or azure
       model: anthropic/claude-haiku-4.5
       api_key: sk-your-api-key
   

   Swap the provider name and fill in the model/API key required by your account.

3. Start TmuxAI

   tmuxai
   

See Model Configuration for more details.

TmuxAI Layout

!Panes (https://tmuxai.dev/shots/panes.png?lastmode=1)

TmuxAI is designed to operate within a single tmux window, with one instance of TmuxAI running per window and organizes your workspace using the following pane structure:

1. Chat Pane: This is where you interact with the AI. It features a REPL-like interface with syntax highlighting, auto-completion, and readline shortcuts.

2. Exec Pane: TmuxAI selects (or creates) a pane where commands can be executed.

3. Read-Only Panes: All other panes in the current window serve as additional context. TmuxAI can read their content but does not interact with them.

Observe Mode

!Observe Mode (https://tmuxai.dev/shots/demo-observe.png) TmuxAI sent the first ping command and is waiting for the countdown to check for the next step

TmuxAI operates by default in "observe mode". Here's how the interaction flow works:

1. User types a message in the Chat Pane.

2. TmuxAI captures context from all visible panes in your current tmux window (excluding the Chat Pane itself). This includes:

   • Current command with arguments
   • Detected shell type
   • User's operating system
   • Current content of each pane

3. TmuxAI processes your request by sending user's message, the current pane context, and chat history to the AI.

4. The AI responds with information, which may include a suggested command to run.

5. If a command is suggested, TmuxAI will:

   • Check if the command matches whitelist or blacklist patterns
   • Ask for your confirmation (unless the command is whitelisted). The confirmation prompt includes a risk indicator (✓ safe, ? unknown, ! danger) for guidance only - always review commands carefully as the risk scoring is not exhaustive and should not be relied upon for security decisions
   • Execute the command in the designated Exec Pane if approved
   • Wait for the wait_interval (default: 5 seconds) (You can pause/resume the countdown with space or enter to stop the countdown)
   • Capture the new output from all panes
   • Send the updated context back to the AI to continue helping you

6. The conversation continues until your task is complete.

!Observe Mode Flowchart (https://tmuxai.dev/shots/observe-mode.png)

Prepare Mode

!Prepare Mode (https://tmuxai.dev/shots/demo-prepare.png?lastmode=1) TmuxAI customized the pane prompt and sent the first ping command. Instead of the countdown, it's waiting for command completion

Prepare mode is an optional feature that enhances TmuxAI's ability to work with your terminal by customizing your shell prompt and tracking command execution with better precision. This enhancement eliminates the need for arbitrary wait intervals and provides the AI with more detailed information about your commands and their results.

When you enable Prepare Mode, TmuxAI will:

1. Detects your current shell in the execution pane (supports bash, zsh, and fish)
2. Customizes your shell prompt to include special markers that TmuxAI can recognize
3. Will track command execution history including exit codes, and per-command outputs
4. Will detect command completion instead of using fixed wait time intervals

To activate Prepare Mode, simply use:

TmuxAI » /prepare

By default, TmuxAI will attempt to detect the shell running in the execution pane. If you need to specify the shell manually, you can provide it as an argument:

TmuxAI » /prepare bash

Prepared Fish Example:

$ function fish_prompt; set -l s $status; printf '%s@%s:%s[%s][%d]» ' $USER (hostname -s) (prompt_pwd) (date +"%H:%M") $s; end
username@hostname:~/r/tmuxai[21:05][0]»

Watch Mode

!Watch Mode (https://tmuxai.dev/shots/demo-watch.png) TmuxAI watching user shell commands and better alternatives

Watch Mode transforms TmuxAI into a proactive assistant that continuously monitors your terminal activity and provides suggestions based on what you're doing.