TmuxAI: an AI assistant that reads your tmux panes, not your clipboard

The problem TmuxAI targets: context that never leaves the terminal

Most AI coding tools ask you to move context to them. You copy a stack trace into a browser, paste a file into a chat window, or describe a directory layout from memory. TmuxAI inverts that. It lives inside your tmux sessions and reads the visible content of your panes, so the thing you are looking at is the thing it reasons about. The README frames this as a pair programmer that "sits beside you, watching your terminal environment exactly as you see it."

The intended user is narrow and specific: someone who runs tmux on Linux or macOS, keeps several panes open for logs, an editor and a shell, and wants help without breaking that arrangement. The project states it requires only tmux and targets Unix-based systems. That is a real constraint, not a formality. If you do not use a multiplexer, the core value proposition has nothing to attach to.

Three panes, three roles: how the observe and act loop is wired

The architecture is described through roles rather than modules. TmuxAI observes by reading visible pane content, communicates through a dedicated chat pane, and acts by executing commands in a separate execution pane, which the README says happens with your permission. That separation is the design decision worth noticing. The assistant does not take over your shell; it gets its own pane, so a generated command and your interactive session never share a prompt.

The repository layout supports the split: main.go and cli/ for the entry point and commands, internal/ for the bulk of the logic, config/ for configuration handling, system/ and skills/ for the higher-level behaviours documented in the README. The Go module pulls in viper for configuration, cobra for command-line parsing, and provider SDKs including the AWS SDK v2, Google's genai package and the GitHub Copilot SDK. That dependency list is the clearest evidence that provider support is broad rather than bolted on.

Everything above is inferred from the file tree and go.mod. The README does not publish an internal data-flow diagram, so treat the pane roles as the documented contract and nothing more.

Installing TmuxAI and starting your first session

The quick install is a shell script served from get.tmuxai.dev. The README notes it installs to /usr/local/bin/tmuxai by default and points at the script source if you want to read it first. Reading it first is the sensible move for anything piped into bash.

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

If you would rather not run a remote script, the README documents prebuilt binaries on the GitHub releases page. After downloading, make the file executable and move it somewhere on your PATH.

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

There is also a development install from the main branch, which the README warns may be less stable than official releases.

go install github.com/alvinunreal/tmuxai@main

Configuration lives at ~/.config/tmuxai/config.yaml. The README's minimal example names a provider, a model and an API key; the provider list it gives is openrouter, requesty, openai or azure.

models:
  primary:
    provider: openrouter
    model: anthropic/claude-haiku-4.5
    api_key: sk-your-api-key

Create the directory, write the file, then run tmuxai. The README's setup section shows exactly that sequence, and a config.example.yaml sits at the repository root if you want the fuller shape of the file before writing your own.

Watch mode, knowledge bases and skills: the parts that need a budget

Beyond plain chat, the README documents Observe, Prepare and Watch modes. Watch mode is the one with operational consequences: it lets the assistant track activity rather than wait for a prompt. The README lists example use cases but does not quantify token consumption, so the cost of leaving it on is something you estimate from your provider's pricing rather than from the project's documentation.

Knowledge bases and skills are the extension points. You can create a knowledge base, load it explicitly, or auto-load it; skills can be enabled, created, matched automatically, and governed by budget controls. The presence of budget controls is itself a signal: the maintainers expect skills to consume model calls and want a ceiling on that. Skills are tracked in skills-lock.json at the repository root, which suggests the skill set is versioned rather than purely ad hoc.

The README documents what these features do and how to turn them on. It does not publish benchmarks for how much context each one adds, so treat any expectation about latency or spend as yours to measure.

Where TmuxAI is the wrong tool

The clearest limitation is the platform. The README states the project works on Unix-based operating systems including Linux and macOS. Windows is not covered there, and the repository ships no Windows-specific installation path. If your daily environment is Windows, this is not a rough edge you can sand down; it is outside the documented scope.

The second limitation is the dependency on tmux itself. TmuxAI's observation model reads pane content, so its usefulness scales with how much of your work happens in panes. Run it outside tmux and the assistant loses the context that justifies its existence. That is not a bug, but it does mean the tool competes poorly against a plain chat interface for one-off questions.

The third is documentation depth in places. The README covers installation, configuration, modes, knowledge bases, skills, model switching and squashing, and it links to a tmux cheat sheet and a config generator. What it does not publish is a stable scripting interface or a rollback procedure for a command the assistant executes. The execution pane is described as acting with your permission, but the README does not document an undo. Verify that boundary yourself before letting it run anything destructive.

How it differs from Warp and from MCP-based terminal tooling

The comparison people reach for is Warp, which appears in the project's own topics and in the search terms around it. The difference is architectural rather than cosmetic. Warp is a terminal emulator: adopting it means adopting a new terminal application and bringing your sessions into it. TmuxAI is a binary that attaches to tmux, so your existing terminal, keybindings and pane layout stay where they are. You gain an assistant; you do not migrate your shell.

The other nearby category is MCP-based terminal tooling, represented in this repository by the modelcontextprotocol/go-sdk dependency. TmuxAI does expose MCP server tools, so it is not purely an alternative to that ecosystem. The distinction is direction of control. An MCP server typically exposes tools to an external model client; TmuxAI runs its own chat loop inside your session and reaches out to providers. If your team has standardised on an MCP client, check whether TmuxAI's MCP support fits that arrangement before assuming it replaces it.

Licence, maintenance and what an upgrade actually costs

TmuxAI is licensed under Apache-2.0, with the LICENSE file at the repository root and COPYING alongside it. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, which matters if you intend to embed this in internal tooling. It also carries notice and attribution obligations, so redistributing a modified binary means preserving the relevant notices. This is a description of the licence text, not legal advice; route anything unusual past your own counsel.

The last push to the repository was on 2026-09-08, and the most recent release is v2.3.2 from 2026-09-07. The release cadence visible in the repository shows v2.3.0 on 2026-06-30, v2.3.1 on 2026-07-06 and v2.3.2 on 2026-09-07. That is a steady minor-version rhythm rather than a burst.

Upgrade cost is low if you installed a release binary: replace the file. It is higher if you track main via go install, because the README itself warns that branch may be less stable. The configuration file is the part to watch across upgrades, since provider names and model identifiers in config.yaml are the values most likely to need editing when a provider changes its catalogue. The README does not document a migration path for config schema changes, so keep a copy of a working config.yaml before upgrading.

Editorial conclusion

Adopt TmuxAI if you already run tmux daily and want an assistant that sees the same panes you do, and if you are comfortable putting an API key in ~/.config/tmuxai/config.yaml. Skip it if you work outside tmux, or if you need a stable, documented interface for scripting, because the README does not publish one. Before committing, read install.sh rather than piping it to bash, and confirm which provider and model your account can actually call.

Frequently asked questions

Official sources

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