Skip to content
/

TmuxAI

tmuxai · alvinunreal/tmuxai · ★ 1.8k · last commit 2026-05-20

Primitive shape
No installable primitives
00

Summary

TmuxAI — Summary

TmuxAI is a Go-based terminal assistant that lives inside tmux sessions, reading the visible content of all tmux panes as context and helping users via a dedicated chat pane with a dedicated execution pane. Unlike other agents that read files or repositories, TmuxAI observes the terminal screen itself — "just as a colleague sitting next to you would observe your screen." It uses XML-tag-based tool calling (no structured tool API), supports multiple LLM models via a YAML config, includes Skills (markdown files auto-matched to context), a Knowledge Base system, MCP server tools, web search (Brave/SearXNG), and a Watch mode that proactively monitors terminal activity. The baseSystemPrompt explicitly instructs the model to be brief ("BREVITY IS CRITICAL") and to explain actions before calling tools.

Compared to seeds: no seed framework operates at the tmux screen level — all seeds work with file systems and code. TmuxAI is the only tool in the corpus whose context source is a live terminal display rather than files. The closest architectural analogy is agent-os (zero-primitive philosophy, adapt to workflow), but TmuxAI is a full execution agent.

01

Overview

TmuxAI — Overview

Origin

Created by Boring Dystopia Development (alvin@tmuxai.dev). Repository: alvinunreal/tmuxai. Apache 2.0 license. ~1833 GitHub stars. Active (last push: 2026-05-20).

Philosophy

From README:

"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."

Design philosophy:

  1. Non-intrusive: no shell wrappers, no terminal emulator changes, works with existing tmux setup
  2. Context from screen: reads visible pane content, not file system
  3. Human-inspired collaboration: observer → communicator → actor (with permission)
  4. BREVITY IS CRITICAL: embedded in the system prompt as an iron rule

Manifesto-style quotes (from prompts.go)

"IMPORTANT: BE CONCISE AND AVOID VERBOSITY. BREVITY IS CRITICAL. Minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy."

"Before calling each tool, first explain why you are calling it."

"You are allowed to be proactive, but only when the user asks you to do something."

Distribution

  • curl -fsSL https://get.tmuxai.dev | bash
  • Manual download from GitHub Releases
  • Binary: tmuxai
  • Requires: tmux (and nothing else)
02

Architecture

TmuxAI — Architecture

Distribution & Install

  • curl -fsSL https://get.tmuxai.dev | bash
  • Manual binary download from GitHub Releases
  • Binary: tmuxai

Required Runtime

  • tmux (required)
  • Go binary — no runtime dependencies beyond tmux

Directory Structure

alvinunreal/tmuxai/
├── internal/
│   ├── ai_client.go        # LLM provider abstraction
│   ├── prompts.go          # baseSystemPrompt + chatAssistantPrompt
│   ├── chat.go             # Chat session management
│   ├── exec_pane.go        # Execution pane management
│   ├── manager.go          # TmuxAI orchestrator
│   ├── pane_details.go     # Tmux pane content capture
│   ├── process_message.go  # Message processing
│   ├── process_response.go # Response processing + XML tool extraction
│   ├── skill_registry.go   # Skills loading and L1 context injection
│   ├── knowledge_base.go   # Knowledge base management
│   ├── squash.go           # Context squashing (compaction)
│   ├── web_fetch.go        # Web content fetching
│   ├── web_search.go       # Web search (Brave or SearXNG)
│   ├── risk_scorer.go      # Command risk assessment
│   └── mcp/                # MCP server tools integration
├── config/                 # Configuration handling
├── cli/                    # CLI commands
├── config.example.yaml     # Example configuration
└── main.go

Configuration (config.example.yaml)

# Multiple named models
models:
  fast:
    provider: "openrouter"
    model: "anthropic/claude-haiku-4.5"
    api_key: "..."
  smart:
    provider: "openrouter"
    model: "google/gemini-2.5-prod"
    api_key: "..."

max_context_size: 100000   # tokens; 80% triggers squashing
max_capture_lines: 200     # lines captured per pane read
wait_interval: 5           # seconds for observe/watch modes
yolo: false                # skip all confirmations

Tmux Layout

TmuxAI creates a layout with:

  • Chat pane (left): AI conversation interface
  • Exec pane (right): where commands execute (user's terminal)

Tool Calling Model

TmuxAI uses XML tags in LLM responses rather than structured tool calling:

  • <ExecCommand> — run a shell command in exec pane
  • <TmuxSendKeys> — send keystrokes to a tmux pane
  • <PasteMultilineContent> — paste multiline text (for vim, etc.)
  • <WaitingForUserResponse> — flag that input is needed
  • <RequestAccomplished> — flag that task is complete
  • <ExecPaneSeemsBusy> — flag to wait for exec pane

LLM Providers

Supports OpenRouter (recommended) and any OpenAI-compatible endpoint as base_url. Effectively provider-agnostic via OpenRouter or direct API.

03

Components

TmuxAI — Components

Operation Modes

Mode Trigger Description
Default tmuxai <prompt> Single request in tmux window
Observe mode --observe Reads pane content and provides context-aware help
Prepare mode --prepare Enhanced command tracking with custom shell prompts
Watch mode --watch "goal" Proactively monitors and offers improvements based on goal

Skills System

Skills are markdown files automatically matched to context:

Feature Description
Skill files Markdown files with description: YAML front-matter
Auto-match Skills with matching context are automatically included
L1 Block Matched skills injected into system prompt
Budget controls Skills can be configured with token budget limits
Location User-configured skill directory

Knowledge Base

Feature Description
Knowledge bases Named sets of context documents
Auto-loading Knowledge bases auto-loaded based on current working directory
Use @knowledge-base-name syntax in chat
Creation User-created markdown/text files organized in directories

MCP Server Tools

TmuxAI can connect to external MCP servers via the internal/mcp/ package. Tools from connected servers are injected into the system prompt and callable via XML tags.

Squashing (Context Compaction)

When context reaches 80% of max_context_size, TmuxAI "squashes" the conversation — summarizes older messages to free up context while preserving key information.

Risk Scorer

internal/risk_scorer.go — assesses the risk level of proposed commands before execution. High-risk commands may require extra confirmation.

Web Integration

  • Web search: Brave Search API or SearXNG
  • Web fetch: URL content retrieval for read operations
05

Prompts

TmuxAI — Prompts

Verbatim Excerpt 1: Base System Prompt (from internal/prompts.go)

func (m *Manager) baseSystemPrompt() string {
    basePrompt := `You are TmuxAI assistant. You are AI agent and live inside user's Tmux's window and can see all panes in that window.
Think of TmuxAI as a pair programmer that sits beside user, watching users terminal window exactly as user see it.
TmuxAI's design philosophy mirrors the way humans collaborate at the terminal. Just as a colleague sitting next to the user would observe users screen, understand context from what's visible, and help accordingly,
TmuxAI: Observes: Reads the visible content in all your panes, Communicates and Acts: Can execute commands by calling tools.
You and user both are able to control and interact with tmux ai exec pane.

You have perfect understanding of human common sense.
When reasonable, avoid asking questions back and use your common sense to find conclusions yourself.
Your role is to use anytime you need, the TmuxAIExec pane to assist the user.
You are expert in all kinds of shell scripting, shell usage difference between bash, zsh, fish, powershell, cmd, batch, etc and different OS-es.
You always strive for simple, elegant, clean and effective solutions.

IMPORTANT: BE CONCISE AND AVOID VERBOSITY. BREVITY IS CRITICAL. Minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand.

Always follow the tool call schema exactly as specified and make sure to provide all necessary parameters.
Before calling each tool, first explain why you are calling it.

DO NOT WRITE MORE TEXT AFTER THE TOOL CALLS IN A RESPONSE.`

Prompting technique: Role/persona establishment (the agent IS a pair programmer sitting beside the user), ALL-CAPS brevity mandate ("BREVITY IS CRITICAL"), self-explanation requirement before tool calls ("first explain why you are calling it"), and hard stop rule ("DO NOT WRITE MORE TEXT AFTER THE TOOL CALLS").

Verbatim Excerpt 2: XML Tool Definitions (from chatAssistantPrompt)

builder.WriteString(`
Your primary function is to assist users by interpreting their requests and executing appropriate actions.
You have access to the following XML tags to control the tmux pane:

<TmuxSendKeys>: Use this to send keystrokes to the tmux pane. Supported keys include standard characters, function keys (F1-F12), navigation keys (Up,Down,Left,Right,BSpace,BTab,DC,End,Enter,Escape,Home,IC,NPage,PageDown,PgDn,PPage,PageUp,PgUp,Space,Tab), and modifier keys (C-, M-).
<ExecCommand>: Use this to execute shell commands in the tmux pane.
<PasteMultilineContent>: Use this to send multiline content into the tmux pane. Main use for this is when it's vim open and you need to type multiline text, etc.
<WaitingForUserResponse>: Use this boolean tag (value 1) when you have a question, need input or clarification from the user.
<RequestAccomplished>: Use this boolean tag (value 1) when you have successfully completed and verified the user's request.
`)

Prompting technique: XML-tag tool catalog with usage guidance and constraints. Each tag has a specific scope restriction (e.g., PasteMultilineContent's "it's forbidden to use this to execute commands in a shell"). Boolean flag tags (<WaitingForUserResponse value="1">) for state signaling rather than text-based completion detection.

09

Uniqueness

TmuxAI — Uniqueness & Positioning

Differs from Seeds

TmuxAI is unique in the entire corpus — no seed framework operates at the tmux screen level. All seeds work with file systems, specifications, or code repositories as context. TmuxAI's context IS the visible terminal content, making it applicable to any terminal program (SSH sessions, database CLIs, network equipment shells, vim, etc.) without those programs needing to be aware of TmuxAI. The closest seed analogy is agent-os (adapt to workflow, zero-intrusion philosophy), but agent-os has no execution capability. The XML-tag tool calling approach (vs. structured function calling) is also unique — it enables keystroke-level terminal control (TmuxSendKeys) that no structured API supports. The Watch mode (proactive monitoring and suggestions based on terminal activity) has no parallel in any seed.

Positioning

The "AI pair programmer that watches your screen" — not a coding agent, but a terminal assistant. It helps with any terminal workflow (database ops, SSH management, log analysis, deployment monitoring) not just coding. This makes it the broadest-scope tool in the batch by use case.

Key Differentiators

  1. Screen-as-context: reads visible tmux pane content, not file system — unique in corpus
  2. XML-tag tool calling: keystroke-level control (TmuxSendKeys) that structured APIs don't support
  3. Watch mode: proactive monitoring and suggestions based on ongoing terminal activity
  4. Universal terminal compatibility: works with SSH, database CLIs, network device shells, vim — anything that appears in a terminal
  5. Risk scorer: automated risk assessment before command display
  6. Status line integration: tmux status line shows context usage and model state
  7. Go binary: single binary, minimal install, tmux is the only dependency

Observable Failure Modes

  • Screen capture limitations: only sees what's visible (200 lines); off-screen output is lost
  • Context freshness: pane content is re-read; if the model acts on stale context, errors occur
  • XML extraction reliability: depends on model reliably producing valid XML tags; may fail with weaker models
  • Watch mode noise: proactive monitoring can be overly eager or miss important events depending on wait_interval
  • Prepare mode setup: requires shell configuration changes that some users may resist
04

Workflow

TmuxAI — Workflow

Standard Request Workflow

tmuxai "find large files and cleanup some space"
  → capture visible content of all tmux panes
  → build system prompt (base + skills L1 block + XML tool docs)
  → send to LLM
  → parse XML tags from response
  → show command to user: "Do you want to execute this command? [Y]es/No/Edit:"
  → on approval: send to exec pane via TmuxSendKeys/ExecCommand
  → capture new pane state
  → LLM continues if needed
  → <RequestAccomplished> or <WaitingForUserResponse> signals end

Watch Mode Workflow

tmuxai --watch "monitor this deployment and alert on errors"
  → poll exec pane every wait_interval seconds
  → analyze visible content against goal
  → proactively offer commands or explanations when relevant
  → user can accept, modify, or ignore suggestions

Phases & Artifacts

Phase Action Artifact
Context capture Read visible tmux pane content Pane snapshot (text)
Skill matching Match skills to context L1 block injected to system prompt
LLM inference Build prompt + call model Response with XML tags
XML parsing Extract tool calls from response Action list
Approval gate Show command to user with [Y]es/No/Edit Approved action
Execution Send to exec pane Terminal output in exec pane
Compaction If >80% context: squash Compressed context

Approval Gates

  1. Per-command approval: every <ExecCommand> or <TmuxSendKeys> shows [Y]es/No/Edit: prompt
  2. yolo: true in config skips all confirmations
  3. Risk scorer may add additional confirmation for high-risk commands
06

Memory Context

TmuxAI — Memory & Context

Primary Context Source: Tmux Screen

Unlike all other frameworks, TmuxAI's primary context is the visible content of tmux panes (up to max_capture_lines: 200 lines per pane). This is read fresh on each interaction.

Context Building

  1. Visible pane content: captured via tmux API
  2. Skills L1 block: matched skills injected after base system prompt
  3. Knowledge base: relevant knowledge base documents
  4. MCP tool definitions: from connected servers
  5. Conversation history: in-process message list

Context Compaction (Squashing)

When context reaches 80% of max_context_size:

  • internal/squash.go summarizes older messages
  • Key facts preserved; verbose exchanges compressed
  • User can trigger manual squash: tmuxai squash

Knowledge Bases

  • Named document sets created by the user
  • Auto-loaded based on current working directory
  • Referenced as @knowledge-base-name in chat
  • Persistent across sessions

Skills Context

  • Skills files auto-matched to visible terminal context
  • L1 Block: all matched skills injected at prompt construction time
  • Skills are NOT injected if they don't match current context (token efficiency)

Session-Level Memory

In-process conversation history. No cross-session persistence of the conversation itself (pane content is re-read fresh). Knowledge bases and config persist.

07

Orchestration

TmuxAI — Orchestration

Multi-Agent: No

Single agent. No subagent spawning.

Orchestration Pattern: Sequential + Event-Driven (Watch mode)

  • Default: sequential (one request → one response loop)
  • Watch mode: event-driven (polls terminal and triggers based on activity)

Execution Mode

  • Default: one-shot per invocation
  • Watch mode: continuous polling (event-driven)
  • Observe mode: one-shot context-aware assist

Isolation Mechanism

None — commands execute directly in the exec pane (user's live tmux environment). The tmux exec pane is both the execution target and the observation surface.

Multi-Model

Yes — named model configurations in config.yaml. Users can define multiple models (e.g., fast and smart) and switch between them. The default model is specified via default_model config key.

XML-Tag Tool Calling

TmuxAI uses XML tags rather than the LLM provider's structured function calling interface. This makes it model-agnostic (works with any model that can produce XML) and enables rich keystroke control (TmuxSendKeys) that structured APIs don't support.

Prompt Chaining

Yes — each turn captures the current pane state, builds a new context, and the conversation history chains through turns.

Risk Scoring

internal/risk_scorer.go scores command risk before display. High-risk commands may show additional warnings or require more explicit user confirmation.

08

Ui Cli Surface

TmuxAI — UI & CLI Surface

Dedicated CLI Binary

  • Binary name: tmuxai
  • Language: Go (self-contained binary)
  • Not a thin wrapper: full agent runtime with LLM client, tmux integration, skills, knowledge base, MCP, web search
  • Install: curl -fsSL https://get.tmuxai.dev | bash

Tmux-Native UI

TmuxAI is not a separate TUI — it IS a tmux tool. It creates and manages two tmux panes:

  • Chat pane: where the user types and AI responses appear
  • Exec pane: where proposed commands are executed (after approval)

The layout is native tmux, configured via tmux.exec_split_args (default: ["-d", "-h"] for horizontal split).

Prepare Mode (Enhanced Terminal Tracking)

With --prepare: installs custom shell prompt functions that provide:

  • Exact command completion detection
  • Exit code awareness
  • More accurate terminal activity tracking for Watch mode

CLI Modes

Mode Trigger Description
Default tmuxai "prompt" Single request with pane context
Observe --observe Context-aware passive assistance
Prepare --prepare Enhanced shell tracking
Watch --watch "goal" Continuous proactive monitoring

Status Line Customization

The tmux status line can show TmuxAI context via configurable status_line with placeholders: {app}, {context}, {context_used}, {context_max}, {model}, {state}, {state_badge}, {model_changed}.

Web Search Support

  • Brave Search API
  • SearXNG (self-hosted)
  • Configured via brave_api_key or searxng_url in config

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.