TmuxAI: an AI assistant that reads your tmux panes instead of replacing your shell

The problem TmuxAI solves, and who it is actually for

Most command-line AI tools ask you to leave your terminal. You pipe output into them, paste errors into a chat window, or run a wrapper that owns the shell. TmuxAI takes the opposite position: it attaches to the tmux session you already have. The README describes it as an assistant that "observes and understands the content of your tmux panes, providing assistance without requiring you to change your workflow or interrupt your terminal sessions."

That framing sets the audience precisely. You need to be a tmux user already. The README states the project requires only tmux and is designed for Unix-based systems including Linux and macOS. If you have never used tmux, the project links its own getting-started and cheat-sheet pages, which is a hint that the prerequisite is real rather than nominal. Someone who runs a single terminal window and never splits panes will get little from this, because the value comes from the assistant seeing several panes at once: a build log in one, a failing test in another, a server tail in a third.

The second audience is people who want the assistant to act, not just advise. TmuxAI can execute commands on your behalf in a dedicated execution pane, and the README is explicit that this happens with your permission. That combination, read context plus propose and run commands, is what separates it from a plain chat client pointed at a terminal.

How the observe, communicate, act model maps onto tmux panes

The architecture is described in the README as three steps that mirror a colleague sitting beside you. TmuxAI observes by reading the visible content in all your panes. It communicates through a dedicated chat pane. It acts in a separate execution pane, with your permission.

The word visible is doing real work here. TmuxAI reads what is on screen in the panes, not your shell history, not your filesystem, not your environment variables. That is why the project calls the interface human-inspired: a person looking over your shoulder sees the same thing. The practical consequence is that context is bounded by your terminal scrollback and pane size, so the assistant is only as informed as what you have left on screen. It also means the assistant is not silently indexing your disk, which is a meaningful difference from tools that crawl a repository.

The execution pane matters as a design choice. Rather than injecting commands into the pane you are typing in, TmuxAI runs them somewhere else. Your working pane keeps its state, and you can watch a command run without losing the prompt you were at. The README does not spell out rollback behaviour for a command that goes wrong, so treat the execution pane as a place where you watch first and confirm second.

Installing TmuxAI and getting a first answer out of it

The quick install path is a shell script. The README notes it installs the binary to /usr/local/bin/tmuxai by default, and points at the script source if you want to read it first.

curl -fsSL https://get.tmuxai.dev | bash

If you would rather not pipe a remote script into a shell, the manual route is to download a pre-built binary from the GitHub releases page, then make it executable and move it onto your PATH.

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

There is also a development install from the main branch. The README warns that main carries the latest features and fixes but may be less stable than official releases.

go install github.com/alvinunreal/tmuxai@main

TmuxAI reads its configuration from ~/.config/tmuxai/config.yaml, and the README's post-installation steps start by creating that directory and file.

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

The minimal config names a provider, a model and an API key. The README lists openrouter, requesty, openai and azure as provider values, and its example uses anthropic/claude-haiku-4.5 as the model string.

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

Swap the provider and fill in the model and key your account actually supports. Then run the binary inside a tmux session.

tmuxai

What you should see is a chat pane appear alongside your existing panes; the README's layout section covers how the panes are arranged. If nothing starts, the first thing to check is whether you launched it inside tmux at all, since the whole model depends on an existing session.

Knowledge bases, skills and the budget controls that gate them

Two features extend what the assistant knows beyond the visible panes. Knowledge bases are collections you create and then load, and the README documents creating, using and auto-loading them. Skills are a second mechanism, with sections on enabling, creating, using, auto-match and budget controls. The presence of a budget-controls section is the interesting part: skills can be matched automatically, and automatic matching can consume tokens without you asking. If you enable auto-match, the budget controls are the thing that keeps an unattended session from spending quietly.

TmuxAI also lists MCP server tools and web search and fetch as capabilities, and the dependency list in go.mod shows the pieces behind them: github.com/modelcontextprotocol/go-sdk for MCP, and github.com/JohannesKaufmann/html-to-markdown/v2 plus github.com/mackee/go-readability for turning fetched pages into something a model can read. The same file shows provider SDKs for AWS Bedrock (aws-sdk-go-v2/service/bedrockruntime), Google GenAI (google.golang.org/genai) and GitHub Copilot (github/copilot-sdk/go), which is broader than the four provider names in the README's minimal config. The README's model configuration section covers setting up multiple models and switching between them, so the provider list in the example is a starting point rather than the full set.

Squashing, multiline input and a status-line customization option round out the interface. Squashing is documented as both a concept and a manual action; the README does not explain what gets discarded, so read that section before relying on it to compress a long session.

Where TmuxAI is the wrong tool

The hardest constraint is the platform. TmuxAI requires tmux, and the README scopes support to Unix-based systems including Linux and macOS. Windows is not listed. If your team develops on Windows without WSL, this project is not a candidate, and no amount of provider configuration changes that.

The second constraint is cost and connectivity. The minimal config requires an api_key for a hosted provider, so every session depends on a third-party service being reachable and your account being in good standing. There is no documented offline mode. Anyone working in an air-gapped environment, or unwilling to send terminal contents to a provider, should stop here. Reading your panes means sending your panes.

The third is context fidelity. Because TmuxAI reads visible pane content, a long error that has scrolled off screen is invisible to it. A tool that indexes the repository instead will know about a file you never opened; TmuxAI will not, unless you put it on screen or into a knowledge base. If your debugging style is to jump between files rather than keep everything visible, the observation model works against you.

Finally, the permission model is a single point of judgement. The README says commands run in the execution pane with your permission, which is the right default, but it also means a tired operator approving a destructive command is the failure mode. The README does not document an undo or rollback mechanism for executed commands.

TmuxAI versus a plain terminal AI client

The obvious alternative is a general CLI AI client that you run in a pane and paste into. The difference is context acquisition. A paste-based client knows only what you gave it in the current message. TmuxAI reads the visible content of all your panes on its own, so a question like "why did that build fail" can be answered from the build pane without you copying anything.

That convenience has a mirror image. A paste-based client sends exactly what you chose and nothing else, which is easier to reason about if you care about what leaves your machine. TmuxAI's model is broader by default. The knowledge base and skills features let you narrow or widen that further, but the baseline behaviour is that the assistant sees your screen.

The second difference is execution. A chat client returns text you copy and run yourself. TmuxAI has an execution pane and can run commands for you after permission. That is faster for repetitive work and riskier for anything irreversible. If you want advice only, the execution pane is a feature you can simply not use, and the observe-and-answer behaviour still stands on its own. For the tmux versus tmuxai question specifically: tmux is the multiplexer that gives you panes and sessions, and TmuxAI is an assistant that depends on it. They are not substitutes, and TmuxAI cannot run without tmux underneath.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-08. Releases are frequent enough to suggest ongoing work: v2.3.0 on 2026-06-30, v2.3.1 on 2026-07-06 and v2.3.2 on 2026-09-07. That is three tagged releases in roughly ten weeks, with the most recent landing one day before the last push.

Upgrade cost is low on the surface. The quick install script and the manual binary replacement both overwrite a single executable at /usr/local/bin/tmuxai, and the README documents installing from main for people who want unreleased changes. The real upgrade risk sits in configuration. The project uses Viper for config loading, and the README documents environment variables, session-specific configuration and status-line customization on top of the base config.yaml. When a release changes a config key, a long-lived config file is where you will feel it. There is no documented migration command, so keep your config.yaml somewhere you can diff it.

The licence is Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices, which matters if you redistribute a modified binary inside a company. It does not remove the provider question: your API keys and the terms of whichever provider you configure are separate from the project's licence. Nothing here is legal advice; read the LICENSE file and your provider's terms together.

Editorial conclusion

Adopt TmuxAI if you already live in tmux on Linux or macOS and want an assistant that reads your existing panes rather than a new shell wrapper. Skip it if you work on Windows without tmux, or if you cannot supply a provider API key. Before trusting it, open ~/.config/tmuxai/config.yaml and confirm which provider, model and api_key it will use, then test the execution pane on a throwaway directory.

Frequently asked questions

Official sources

1. alvinunreal/tmuxai on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases