GitHub - hynek-urban/tmux-llm: Get quick LLM insights in a tmux popup window.

2 min read Original article ↗

tmux-llm

A minimalist tmux plugin for getting quick responses to your terminal contents from an LLM assistant.

Works with any openai-compatible API. Requires bash and python3.

Created with the help of Sculptor.

Usage

  1. (Optionally) Select text in a tmux pane (copy mode).
  2. Press Ctrl+G (or your configured key binding).
  3. The LLM response will appear in a popup window.
  4. Press q to close the popup window.

demo

Installation

Using TPM (Tmux Plugin Manager)

Add these lines to your ~/.tmux.conf (ensure you replace the API key with your actual API key):

set -g @tmux-llm-api-key '<your-api-key>'
set -g @plugin 'hynek-urban/tmux-llm'

Then press prefix + I to install.

Alternatively, you can set the API key via the TMUX_LLM_API_KEY environment variable, which takes precedence over the tmux option (useful for keeping secrets out of config files).

Manual Installation

  1. Clone this repository:

    git clone https://github.com/hynek-urban/tmux-llm ~/.tmux/plugins/tmux-llm

  2. Add these lines to your ~/.tmux.conf:

    set -g @tmux-llm-api-key '<your-api-key>'
run-shell 'bash ~/.tmux/plugins/tmux-llm/plugin.tmux'

    (Ensure you replace the API key with your actual API key.)

    Alternatively, you can set the API key via the TMUX_LLM_API_KEY environment variable, which takes precedence over the tmux option (useful for keeping secrets out of config files).

  3. Reload your tmux config:

    tmux source-file ~/.tmux.conf

Configuration

You may customize the following options in ~/.tmux.conf:

# Customize key binding (default: Ctrl+G)
set -g @tmux-llm-key 'C-g'

# Set API endpoint (default: OpenAI)
set -g @tmux-llm-api-endpoint 'https://api.openai.com/v1/chat/completions'

# Set model (default: gpt-4.1-mini)
set -g @tmux-llm-model 'gpt-5.2'

# Customize popup dimensions (defaults: 90% width, 70% height)
set -g @tmux-llm-popup-width '80%'
set -g @tmux-llm-popup-height '60%'

Just make sure to place these option declarations before the main plugin invocation point.

Environment variable precedence: You can also set configuration via environment variables (TMUX_LLM_API_KEY, TMUX_LLM_API_ENDPOINT, TMUX_LLM_MODEL, TMUX_LLM_POPUP_WIDTH, TMUX_LLM_POPUP_HEIGHT). These take precedence over tmux options, which is especially useful for API keys (security) and temporary overrides.

What is actually sent to the LLM?

When you select text in tmux in copy-mode then the selected text is exactly what is sent to the LLM (aside from a generic system prompt).

When you don't select text explicitly, the current terminal height's worth of lines get sent by default.

Each invocation is isolated, there is no chat history.

If you need to provide additional commentary to the LLM, do that by typing it directly in your terminal.

demo with selection