Your intelligent pair programmer directly within your tmux sessions.
Screenshots |
Report Bug |
Request Feature
- About The Project
- Installation
- Post-Installation Setup
- TmuxAI Layout
- Observe Mode
- Prepare Mode
- Watch Mode
- Squashing
- Core Commands
- Command-Line Usage
- Configuration
- Contributing
- License
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:
- Observes: Reads the visible content in all your panes
- Communicates: Uses a dedicated chat pane for interaction
- 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.
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 | bashThis 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.
If you use Homebrew, you can install TmuxAI with:
brew install tmux
brew tap alvinunreal/tmuxai
brew install tmuxaiYou 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/After installing TmuxAI, you need to configure your API key to start using it:
-
Set the API Key
TmuxAI uses the OpenRouter endpoint by default. Set your API key by adding the following to your shell configuration (e.g.,~/.bashrc,~/.zshrc):export TMUXAI_OPENROUTER_API_KEY="your-api-key-here"
-
Start TmuxAI
tmuxai
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.
-
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 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:
- Current command with arguments
- Detected shell type
- User's operating system
- Current content of each pane
<
8000
li>
-
The AI responds with information, which may include a suggested command to run.
-
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)
- Execute the command in the designated Exec Pane if approved
- Wait for the
wait_interval(default: 5 seconds) (You can pause/resume the countdown withspaceorenterto stop the countdown) - Capture the new output from all panes
- Send the updated context back to the AI to continue helping you
-
The conversation continues until your task is complete.
TmuxAI processes your request by sending user's message, the current pane context, and chat history to the AI.
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:
- Detects your current shell in the execution pane (supports bash, zsh, and fish)
- Customizes your shell prompt to include special markers that TmuxAI can recognize
- Will track command execution history including exit codes, and per-command outputs
- Will detect command completion instead of using fixed wait time intervals
To activate Prepare Mode, simply use:
TmuxAI » /prepare
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 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:
- Start capturing the content of all panes in your current tmux window at regular intervals (
wait_intervalconfiguration) - Analyze content based on your specified watch goal and provide suggestions when appropriate
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~ 16500 tokens
████████░░ 82.5%
Max Size 20000 tokensThis example shows that the context is at 82.5% capacity (16,500 tokens out of 20,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| Command | Description |
|---|---|
/info |
Display system information, pane details, and context statistics |
/clear |
Clear chat history. |
/reset |
Clear chat history and reset all panes. |
/config |
View current configuration settings |
/config set <key> <value> |
Override configuration for current session |
/squash |
Manually trigger context summarization |
/prepare |
Initialize Prepared Mode for the Exec Pane |
/watch <description> |
Enable Watch Mode with specified goal |
/exit |
Exit TmuxAI |
You can start tmuxai with an initial message or task file from the command line:
-
Direct Message:
tmuxai your initial message
-
Task File:
tmuxai -f path/to/your_task.txt
The configuration can be managed through a YAML file, environment variables, or via runtime commands.
TmuxAI looks for its configuration file at ~/.config/tmuxai/config.yaml.
For a sample configuration file, see config.example.yaml.
All configuration options can also be set via environment variables, which take precedence over the config file. Use the prefix TMUXAI_ followed by the uppercase configuration key:
# Examples
export TMUXAI_DEBUG=true
export TMUXAI_MAX_CAPTURE_LINES=300
export TMUXAI_OPENROUTER_API_KEY="your-api-key-here"
export TMUXAI_OPENROUTER_MODEL="..."You can override some configuration values for your current TmuxAI session using the /config command:
# View current configuration
TmuxAI » /config
# Override a configuration value for this session
TmuxAI » /config set max_capture_lines 300
TmuxAI » /config set openrouter.model gpt-4o-miniThese changes will persist only for the current session and won't modify your config file.
OpenRouter is OpenAI API-compatible, so you can direct TmuxAI at OpenAI or any other OpenAI API-compatible endpoint by customizing the base_url.
For OpenAI:
openrouter:
api_key: sk-proj-XXX
model: o4-mini-2025-04-16
base_url: https://api.openai.com/v1For Anthropic’s Claude:
openrouter:
api_key: sk-proj-XXX
model: claude-3-7-sonnet-20250219
base_url: https://api.anthropic.com/v1For local Ollama:
openrouter:
api_key: api-key
model: gemma3:1b
base_url: http://localhost:11434/v1Prompts are currently tuned for Gemini 2.5 by default; behavior with other models may vary.
If you have a suggestion that would make this better, please fork the repo and create a pull request.
You can also simply open an issue.
Don't forget to give the project a star!
Distributed under the Apache License. See Apache License for more information.