From cead3ebde8f3aee0ef8677158d37f4d04c6629dc Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Mon, 8 Sep 2025 09:50:38 +0300
Subject: tmux: colored LLM status with provider + stats; add start heartbeat
 for LSP/CLI/TUI; theme support via HEXAI_TMUX_STATUS_THEME and
 HEXAI_TMUX_STATUS_FG/BG; docs: update tmux options and add Helix+tmux
 quickstart

---
 docs/configuration.md         | 12 ++++++--
 docs/helix-tmux-quickstart.md | 68 +++++++++++++++++++++++++++++++++++++++++++
 docs/usage.md                 | 18 ++++++++++++
 3 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 docs/helix-tmux-quickstart.md

(limited to 'docs')

diff --git a/docs/configuration.md b/docs/configuration.md
index 690a08f..95b65de 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -69,14 +69,20 @@ Tmux status line
   - `set -g status-right '#{@hexai_status} #[fg=colour8]| %H:%M'`
 
 - Status content is updated best‑effort at key moments:
-  - CLI: start (⏳ provider:model) and completion (✅ model duration)
-  - LSP: after logging aggregate LLM stats (LLM:model)
-  - TUI action runner: ready (model) and completion (✅ model)
+  - CLI: start (⏳ provider:model) and completion with compact stats (↑sent, ↓recv, rpm, reqs)
+  - LSP: initial heartbeat on client initialize, and periodic compact stats (provider, model, rpm, reqs, bytes)
+  - TUI action runner: ready (provider:model) and completion with compact stats
 
 - Toggle via environment:
   - Enable (default): unset or `HEXAI_TMUX_STATUS=1`
   - Disable: `HEXAI_TMUX_STATUS=0`
 
+- Theme and colors:
+  - Preset: `HEXAI_TMUX_STATUS_THEME=white-on-purple` (white fg on purple/magenta bg)
+  - Explicit: `HEXAI_TMUX_STATUS_FG=<color>`, `HEXAI_TMUX_STATUS_BG=<color>` (e.g., `white`, `magenta`, `colour5`)
+  - Colors use tmux’s `fg`/`bg` names; both methods wrap the entire `@hexai_status` segment.
+  - If truncated, increase width: `set -g status-right-length 120`
+
 Code action prompts
 
 - All prompts can be customized under `[prompts.code_action]` in `config.toml`. In addition to `rewrite_*`, `diagnostics_*`, `document_*`, and `go_test_*`, the following templates control the “Simplify and improve” action:
diff --git a/docs/helix-tmux-quickstart.md b/docs/helix-tmux-quickstart.md
new file mode 100644
index 0000000..caee3f8
--- /dev/null
+++ b/docs/helix-tmux-quickstart.md
@@ -0,0 +1,68 @@
+# Helix + tmux Quickstart
+
+This guide gets you from zero to editing with Hexai in Helix, with tmux showing live LLM status.
+
+## 1) Install
+
+- Install Mage (optional for build tasks): `go install github.com/magefile/mage@latest`
+- Install binaries directly:
+  - CLI: `go install codeberg.org/snonux/hexai/cmd/hexai@latest`
+  - LSP: `go install codeberg.org/snonux/hexai/cmd/hexai-lsp@latest`
+  - TUI: `go install codeberg.org/snonux/hexai/cmd/hexai-tmux-action@latest`
+
+Ensure `~/go/bin` is on your `PATH`.
+
+## 2) Configure Helix
+
+In `~/.config/helix/languages.toml`:
+
+```toml
+[[language]]
+name = "go"
+auto-format = true
+language-servers = ["gopls", "hexai"]
+
+[language-server.hexai]
+command = "hexai-lsp"
+```
+
+Optional keybindings in `~/.config/helix/config.toml` to run code actions on the selection:
+
+```toml
+[keys.select]
+"A-a" = ":pipe hexai-tmux-action"
+
+[keys.normal]
+"A-a" = ["select_line", ":pipe hexai-tmux-action"]
+```
+
+## 3) Configure tmux status
+
+Add this to `~/.tmux.conf` and reload with `tmux source-file ~/.tmux.conf`:
+
+```
+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
+```
+
+## 4) Use it
+
+- Start tmux, open Helix on a Go 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 ⏳
+  - Stats: ↑sent ↓recv rpm reqs
+
+## 5) Troubleshooting
+
+- No status? Verify: `tmux show -g -v @hexai_status` (should show text).
+- Truncated? Increase width: `set -g status-right-length 120`.
+- Disabled? Ensure `HEXAI_TMUX_STATUS` is not set to `0`.
+- Wrong model? Rebuild/update binaries and restart Helix/LSP.
+
diff --git a/docs/usage.md b/docs/usage.md
index 293b038..706be99 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -132,3 +132,21 @@ hexai-tmux-action --infile input.go --outfile output.go
 # Using shell redirection
 hexai-tmux-action < input.go > output.go
 ```
+
+### Helix keybinding example
+
+Bind a key to pipe the current selection through the action runner and replace it in-place. In `~/.config/helix/config.toml`:
+
+```toml
+[keys.select]
+# Alt-a runs the Hexai action menu on the selection
+"A-a" = ":pipe hexai-tmux-action"
+
+[keys.normal]
+# Optional: run on the current line if no selection
+"A-a" = ["select_line", ":pipe hexai-tmux-action"]
+```
+
+Tips:
+- Ensure Helix runs inside tmux to see the status updates.
+- You can also set a language-specific binding in `languages.toml` if preferred.
-- 
cgit v1.2.3