AI-Powered, Non-Intrusive Terminal Assistant
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.
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:
This approach provides powerful AI assistance while respecting your existing workflow and maintaining the familiar terminal environment you're already comfortable with.
TmuxAI requires only tmux to be installed on your system. It's designed to work on Unix-based operating systems including Linux and macOS.
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.
You can also download pre-built binaries from the GitHub releases page.
After downloading, make the binary executable and move it to a directory in your PATH:
chmod +x ./tmuxai
sudo mv ./tmuxai /usr/local/bin/
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.
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.
Create the config path
mkdir -p ~/.config/tmuxai
vim ~/.config/tmuxai/config.yaml
Add a minimal config
models:
primary:
provider: openrouter # openrouter, requesty, 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.
Start TmuxAI
tmuxai
See Model Configuration for more details.
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:
Chat Pane: This is where you interact with the AI. It features a REPL-like interface with syntax highlighting, auto-completion, and readline shortcuts.
Exec Pane: TmuxAI selects (or creates) a pane where commands can be executed. You can also force a specific exec pane with --exec-pane.
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.
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:
User types a message in the Chat Pane.
TmuxAI captures context from all visible panes in your current tmux window (excluding the Chat Pane itself). This includes:
TmuxAI processes your request by sending user's message, the current pane context, and chat history to the AI.
The AI responds with information, which may include a suggested command to run.
If a command is suggested, TmuxAI will:
wait_interval (default: 5 seconds) (You can pause/resume the countdown with space or enter to stop the countdown)The conversation continues until your task is complete.
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:
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]»
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.
To enable Watch Mode, use the /watch command followed by a description of what you want TmuxAI to look for:
TmuxAI » /watch spot and suggest more efficient alternatives to my shell commands
When activated, TmuxAI will:
wait_interval configuration)Watch Mode could be valuable for scenarios such as:
Learning shell efficiency: Get suggestions for more concise commands as you work
TmuxAI » /watch spot and suggest more efficient alternatives to my shell commands
Detecting common errors: Receive warnings about potential issues or mistakes
TmuxAI » /watch flag commands that could expose sensitive data or weaken system security
Log Monitoring and Error Detection: Have TmuxAI monitor log files or terminal output for errors
TmuxAI » /watch monitor log output for errors, warnings, or critical issues and suggest fixes
As you work with TmuxAI, your conversation history grows, adding to the context provided to the AI model with each interaction. Different AI models have different context size limits and pricing structures based on token usage. To manage this, TmuxAI implements a simple context management feature called "squashing."
Squashing is TmuxAI's built-in mechanism for summarizing chat history to manage token usage.
When your context grows too large, TmuxAI condenses previous messages into a more compact summary.
You can check your current context utilization at any time using the /info command:
TmuxAI » /info
Context
────────
Messages 15
Context Size~ 82500 tokens
████████░░ 82.5%
Max Size 100000 tokens
This example shows that the context is at 82.5% capacity (82,500 tokens out of 100,000). When the context size reaches 80% of the configured maximum (max_context_size in your config), TmuxAI automatically triggers squashing.
If you'd like to manage your context before reaching the automatic threshold, you can trigger squashing manually with the /squash command:
TmuxAI » /squash
For longer or more complex prompts, you can open your current input in an external text editor. This is similar to how bash allows editing commands with Ctrl+X Ctrl+E.
Keyboard Shortcuts:
Ctrl+O - Open current prompt in external editor (works on all platforms)Alt+E - Alternative binding (may not work on macOS due to Option key behavior)When triggered, TmuxAI will:
$EDITOR (falls back to vim if not set) with the current prompt contentThis is useful for:
The Knowledge Base feature allows you to create pre-defined context files in markdown format that can be loaded into TmuxAI's conversation context. This is useful for sharing common patterns, workflows, or project-specific information with the AI across sessions.
Knowledge bases are text files stored in `~/.config
No open issues yet, or sync has not completed.