1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
# Hexai & Tmux Quickstart
This guide gets you from zero to editing with Hexai in Helix, with tmux showing live LLM status.
Hexai can surface live progress in tmux's status line via a user option. Add this to your `~/.tmux.conf`:
## Configure it
```
set -g status-right '#{@hexai_status} #[fg=colour8]| %H:%M'
```
- Note: `colour8` is typically “bright black” (a dim grey) in many themes.
If it’s low-contrast on your background, change it (e.g., `colour7` or `white`).
- CLI updates `@hexai_status` at start (⏳ provider:model) and on completion with compact stats (↑sent, ↓recv, rpm, reqs).
- LSP emits an initial heartbeat on client initialize and periodic compact stats (provider, model, rpm, reqs, bytes).
- The TUI action runner sets a ready heartbeat and a completion heartbeat with stats.
- Toggle with `HEXAI_TMUX_STATUS=0` to disable (enabled by default).
The status segment supports simple theming:
- Preset themes:
- `HEXAI_TMUX_STATUS_THEME=white-on-purple` (white fg on purple/magenta bg)
- `HEXAI_TMUX_STATUS_THEME=black-on-yellow` (black fg on yellow bg)
- Explicit colors: set any tmux color names or 256-color codes
- `HEXAI_TMUX_STATUS_FG=white`
- `HEXAI_TMUX_STATUS_BG=magenta` (or `colour5`, etc.)
- If the segment is truncated, widen it: `set -g status-right-length 120`
Add this to `~/config/tmux/tmux.conf` and restart tmux.
```
set -g status-right '#{@hexai_status} #[fg=colour8]| %H:%M'
set -g status-right-length 120
# Optional: theme the Hexai status segment
set-environment -g HEXAI_TMUX_STATUS_THEME white-on-purple # or black-on-yellow, white-on-blue
# Or explicit colors
# set-environment -g HEXAI_TMUX_STATUS_FG white
# set-environment -g HEXAI_TMUX_STATUS_BG magenta
# Optional: narrow / width-limited mode
# Only show Σ (global) when narrow; or cap total width when long
# set-environment -g HEXAI_TMUX_STATUS_NARROW 1
# set-environment -g HEXAI_TMUX_STATUS_MAXLEN 40
```
## Use it
- Start tmux, open Helix on a file.
- Try completions or inline prompts; or select code and press Alt-a for the action menu.
- Watch the right side of your tmux status for live LLM stats:
- Start heartbeat: provider:model ⏳
- Global stats (Σ@window): ↑sent ↓recv rpm reqs
- Per-model tail is elided in narrow mode or when exceeding `HEXAI_TMUX_STATUS_MAXLEN`.
## Global stats window
- Hexai aggregates stats across all binaries and shows a global Σ view over a sliding window.
- Configure the window in `~/.config/hexai/config.toml`:
```
[stats]
window_minutes = 60 # default 60; min 1, max 1440
```
- The tmux status shows the window as `Σ@1h` or `Σ@45m`.
## Popup editor for AI agent prompts
`hexai-tmux-edit` opens your `$EDITOR` in a tmux popup to compose longer prompts when working with AI CLI agents (Cursor, Amp, Aider, etc.).
OpenAI Codex CLI and Claude Code CLI both support editing in an external editor natively via `Ctrl+G`, so neither needs a built-in `hexai-tmux-edit` agent profile.
The editor opens as a tmux popup overlay, pre-filled with any existing prompt text from the agent's input. After saving and closing, the text is sent back:
*(Screenshots from the [original blog post](https://foo.zone/gemfeed/2026-02-02-tmux-popup-editor-for-cursor-agent-prompts.html) showing the concept with Cursor Agent.)*
Add this keybinding to `~/.tmux.conf`:
```
bind e run-shell -b "cd '#{pane_current_path}' && hexai-tmux-edit --pane '#{pane_id}'"
```
Then press `prefix + e` in any pane running an AI agent. Hexai auto-detects the agent, extracts any existing prompt text, and pre-fills the editor. After saving and closing, the edited text is sent back to the agent's pane.
See the [configuration guide](configuration.md) for customizing popup dimensions and agent patterns, or the [usage guide](usage.md) for the full workflow description.
**Input mode notes**: Each agent uses different clearing methods based on their input handling:
- **Cursor**: Uses simple backspace clearing (`End BSpace*200`)
- **Amp**: Uses Emacs/readline keybindings (`C-u`)
- **Aider**: Uses Emacs/readline keybindings (`C-u`)
The popup editor uses `$EDITOR` (or `$HEXAI_EDITOR`), so your normal vim/neovim setup is used for composing prompts.
**Note**: Agent detection and prompt extraction rely on regex patterns matched against each agent's terminal UI (box-drawing characters, prompt symbols, status text). When agents update their TUI layout, these patterns may need adjustment. You can override patterns per-agent in `[[tmux_edit.agents]]` config without code changes -- see the [configuration guide](configuration.md).
|
