diff options
| -rw-r--r-- | gemfeed/2026-07-09-unleashing-hexai.gmi | 381 | ||||
| -rw-r--r-- | gemfeed/atom.xml | 779 | ||||
| -rw-r--r-- | gemfeed/index.gmi | 1 | ||||
| -rw-r--r-- | index.gmi | 3 | ||||
| -rw-r--r-- | uptime-stats.gmi | 42 |
5 files changed, 376 insertions, 830 deletions
diff --git a/gemfeed/2026-07-09-unleashing-hexai.gmi b/gemfeed/2026-07-09-unleashing-hexai.gmi deleted file mode 100644 index 84ead137..00000000 --- a/gemfeed/2026-07-09-unleashing-hexai.gmi +++ /dev/null @@ -1,381 +0,0 @@ -# Unleashing Hexai: AI companion for Helix and the terminal in general - -> Published at 2026-07-08T17:10:52+03:00 - -I have been using Helix as my main editor for a while now. It is fast, modal, and stays out of the way. The one thing I missed was a bit of LLM help without leaving the editor or opening a browser tab. So I built Hexai. - -Hexai is an AI add-on for Helix. It speaks LSP, so it also works with other editors in theory, but I only test it with Helix. It gives me inline completions, in-editor chat, code actions, a terminal CLI, a tmux popup action runner, and a small task manager for agent work. It is written in Go, lives on Codeberg, and is configured through plain TOML files. - -Hexai has been an undercover pet project of mine since around mid-last year. As I write this it is at version `0.42.1`, so it has been quietly growing for a good while before this first proper write-up. - -=> https://codeberg.org/snonux/hexai Hexai source code -=> https://helix-editor.com Helix editor - -=> ./unleashing-hexai/01-logo.png Hexai logo - -## Table of Contents - -* ⇢ Unleashing Hexai: AI companion for Helix and the terminal in general -* ⇢ ⇢ What it is -* ⇢ ⇢ Installing it -* ⇢ ⇢ Configuring providers -* ⇢ ⇢ Wiring it into Helix -* ⇢ ⇢ Inline chat and prompts -* ⇢ ⇢ Code actions via the tmux popup -* ⇢ ⇢ The CLI -* ⇢ ⇢ Managing agent tasks with ask -* ⇢ ⇢ Running multiple providers side by side -* ⇢ ⇢ What to watch out for -* ⇢ ⇢ It will keep changing -* ⇢ ⇢ Other related posts: - -## What it is - -Hexai is really a bundle of small tools that share the same configuration: - -* `hexai-lsp-server` — the LSP server that Helix talks to. -* `hexai` — a standalone CLI for quick LLM questions from the terminal or scripts. -* `hexai-tmux-action` — a Bubble Tea TUI that pops up inside tmux and runs code actions on the current selection. -* `ask` — a tiny task management CLI for agent-managed project work. - -Everything uses the same `config.toml`, the same provider pool, and the same prompt overrides. I can switch models in one place and the LSP, CLI, and popup all follow along. - -These are opinionated tools. They reflect how I work — Helix inside tmux, a terminal CLI, a thin Taskwarrior wrapper — not a generic plugin system. If your workflow matches mine, they get out of the way; if it doesn't, you will probably want to tweak the config or fork it. - -## Installing it - -The easiest way is to install the binaries with `go install`. Each binary is a separate `cmd/` package: - -```sh -go install codeberg.org/snonux/hexai/cmd/hexai@latest -go install codeberg.org/snonux/hexai/cmd/hexai-lsp-server@latest -go install codeberg.org/snonux/hexai/cmd/hexai-tmux-action@latest -go install codeberg.org/snonux/hexai/cmd/ask@latest -``` - -If you prefer to build from a checkout, Hexai uses Mage: - -```sh -go install github.com/magefile/mage@latest -mage build -mage install -``` - -That drops `hexai`, `hexai-lsp-server`, `hexai-tmux-action`, and `ask` into your `GOPATH/bin`. - -## Configuring providers - -Hexai looks for a global config at `~/.config/hexai/config.toml` and a per-project override at `.hexaiconfig.toml` in the git root. Environment variables prefixed with `HEXAI_` win over both files. - -The default provider is Ollama Cloud with `kimi-k2.6` (it might be different by the time you read this!). To use a local Ollama server instead, override the base URL: - -```toml -[provider] -name = "ollama" - -[ollama] -model = "qwen3-coder:30b-a3b-q4_K_M" -base_url = "http://localhost:11434" -``` - -Because that points at `localhost`, nothing leaves your machine — prompt, code, and reply all stay local. That is the main reason I keep a local Ollama around. - -For OpenAI, the config is similar: - -```toml -[provider] -name = "openai" - -[openai] -model = "gpt-4o-mini" -``` - -Hexai reads the API key from `HEXAI_OPENAI_API_KEY` first, then falls back to `OPENAI_API_KEY`. The same pattern works for OpenRouter, Anthropic, and You.com. - -## Wiring it into Helix - -Tell Helix about the Hexai LSP server in `~/.config/helix/languages.toml`. Here is my Go setup: - -```toml -[[language]] -name = "go" -auto-format = true -formatter = { command = "goimports" } -language-servers = [ "gopls", "hexai" ] - -[language-server.hexai] -command = "hexai-lsp-server" -``` - -You can add `hexai` after `gopls` or any other LSP. It does not replace them; it just adds completions, code actions, and chat on top. - -Once the LSP is wired in, Hexai also offers inline auto-completions as you type. By default it fires after a short idle debounce (`completion_debounce_ms`, 800 ms) when you hit one of the trigger characters (`.` `:` `/` `_` space), and it waits for every configured backend before showing results (`completion_wait_all`). All of it is tunable in `config.toml`, and you can turn completions off for a session without restarting — see the slash commands below. - -For the popup action runner, bind a key in `~/.config/helix/config.toml`: - -```toml -[keys.select] -"A-a" = ":pipe hexai-tmux-action" - -[keys.normal] -"A-a" = ["select_line", ":pipe hexai-tmux-action"] -``` - -I use Alt-a. Select some code, hit Alt-a, and the popup appears. - -## Inline chat and prompts - -The LSP adds two lightweight ways to talk to the model without leaving the editor: - -* End a line with `?>`, `!>`, `:>`, or `;>` to ask a question. Hexai removes only the trailing `>`, keeps the question, and inserts a `> ` quoted reply below the line. -* Type `>!do something>` inline to ask for a quick edit, or `>>!do something>` to replace the whole line with the completion. - -Chat example — a question ending in `?>`: - -```text -What is a Go slice?> -``` - -After the LSP responds you get something like: - -```text -What is a Go slice? - -> A slice is a dynamically-sized view into an array. It stores a pointer to -> the backing array plus length and capacity. -``` - -Inline example — `>>!` replaces the whole line with the completion: - -```go ->>!document this function> -``` - -```go -// Foo returns the square of n. -func Foo(n int) int { return n * n } -``` - -Context is included automatically. For follow-ups, Hexai keeps the last few Q/A pairs above the cursor in mind, so you can ask related questions without repeating yourself. - -There are a few slash commands you can type at the end of a chat line: `/reload>` re-reads `config.toml` without restarting the LSP, `/disable>` pauses auto-completions for the session, and `/enable>` turns them back on. - -In the editor buffer it ends up looking like this — the question stays, the reply is quoted below, and a follow-up picks up the same context: - -```text -What is a Go slice? - -> A slice is a dynamically-sized view into an array. It stores a pointer to -> the backing array plus length and capacity. - -And how do I append to one? - -> Use the built-in append: s = append(s, x). It grows the backing array -> when capacity is exhausted, returning a new slice. -``` - -## Code actions via the tmux popup - -`hexai-tmux-action` is my favorite part. Inside a tmux session, select code in Helix and press the bound key. A tmux popup opens with this menu: - -``` -r Rewrite selection -i Simplify and improve -c Document code -t Generate Go unit test(s) -f Fix typos and improve grammar and clarity -p Custom prompt (opens your editor) -s Skip -``` - -Pick one, the popup closes, and the rewritten code is piped back into Helix. For rewrite actions, I usually add a small instruction in a strict marker like `;extract this into a helper;` inside the selection. The runner finds the first instruction and uses it. - -A mandatory detail: the popup is a real tmux popup, so Helix must be running inside a tmux session for this to work — there is no fallback to a separate window. Start it with: - -```sh -tmux new -s hx -hx some-file.go -``` - -Then select code and hit Alt-a. No special `tmux.conf` is required for the popup itself; the only hard requirement is that Helix lives inside tmux (and tmux 3.2 or newer, since the popup uses tmux's popup feature). - -The menu is fully configurable. This is how I replace it with a smaller custom menu: - -```toml -[[tmux_action.menu]] -kind = "rewrite" -hotkey = "r" - -[[tmux_action.menu]] -kind = "document" -hotkey = "c" - -[[tmux_action.menu]] -kind = "custom" -custom_id = "extract-function" -hotkey = "e" - -[[tmux_action.menu]] -kind = "skip" -hotkey = "s" -``` - -Custom actions reference entries under `[[prompts.code_action.custom]]` in the same config file. - -=> ./unleashing-hexai/06-tmux-popup.jpg The hexai-tmux-action popup menu inside tmux - -Optional but useful: have tmux show live Hexai stats (provider, model, rpm, bytes) in the status line. Add this to `~/.config/tmux/tmux.conf` (or `~/.tmux.conf`): - -``` -set -g status-right '#{@hexai_status} #[fg=colour8]| %H:%M' -set -g status-right-length 120 -``` - -The `@hexai_status` option is updated by the CLI, the LSP, and the action runner. Disable it with `HEXAI_TMUX_STATUS=0` if you don't want it. - -=> ./unleashing-hexai/10-tmux-status.png tmux status line showing live Hexai LLM stats - -## The CLI - -The `hexai` CLI is useful for quick questions from the terminal or from scripts: - -```sh -# Ask from stdin -cat some-file.go | hexai - -# Ask from an argument -hexai 'explain this function' - -# Both stdin and argument are concatenated -cat some-file.go | hexai 'write unit tests for this' - -# Open the global config in $HEXAI_EDITOR or $EDITOR -hexai config - -# Simulate how fast a model feels without calling a provider -hexai --tps-simulation 12-18 -``` - -A real one-shot looks like this (only stdout is shown): - -``` -$ hexai 'install ripgrep on fedora' -sudo dnf install ripgrep -``` - -The provider label and the run summary (timing, token counts, rpm) go to stderr, so `stdout` stays clean for pipes — `hexai 'install ripgrep on fedora' | sh` just works. - -## Managing agent tasks with ask - -`ask` is a thin wrapper around Taskwarrior that auto-scopes tasks to the current git project and tags them with `+agent`. I use it to keep track of what the coding agent is supposed to do next. - -Under the hood every `ask` command is just a Taskwarrior command filtered to `project:REPO +agent`, where `REPO` is the name of the git repository root `ask` was run in. The tasks are plain Taskwarrior tasks, so you can drop down to `task` itself any time and work with the same data. From the hexai repo, for example: - -```sh -# Same tasks, raw Taskwarrior -task project:hexai list -task project:hexai +agent next -``` - -`ask` just hides the project filter, the `+agent` tag, and the raw UUIDs so the day-to-day output stays small and project-local. - -That scoping is also a security boundary, and the main reason I let an LLM agent touch my Taskwarrior database at all. Because `ask` always applies the `project:REPO +agent` filter, the agent can only see and modify tasks in its own current project — it cannot delete, reprioritize, or even see anything outside that filter. So `ask` is really a safety wrapper around `task`: you can hand it to a coding agent without giving it free rein over the rest of your tasks. - -```sh -# Add a task for the current project -ask add priority:H "implement config reload" - -# List pending agent tasks -ask list - -# Start and finish work (ask add prints the alias, e.g. os0) -ask start os0 -ask done os0 - -# See details without exposing raw UUIDs -ask info os0 -``` - -The IDs shown are stable local aliases, not Taskwarrior's numeric IDs. Taskwarrior gives you two built-in identifiers: a numeric ID that isn't stable across syncs and exports, and a UUID that is stable but far too long to type by hand. `ask` instead keeps its own mapping from each task's UUID to a short, permanent alias (cached under Hexai's cache dir) — so you get the best of both: a stable, short ID that never changes even if tasks above it get completed or deleted. `ask info` hides the raw UUID unless `HEXAI_DEBUG` is set, so the short alias is the one you actually use day to day. - -`ask` works from anywhere inside the project git tree and derives the project name from the repo root. To manage tasks for another project, use `ask proj:hexai list`. - -One detail worth knowing: the alias strings are reversed on purpose. The underlying counter is monotonic (1, 2, 3, …), and a naive encoding would make consecutive tasks share a leading character once the list grows past 36 (`00`, `01`, `02`, … all start with `0`), which kills shell tab-completion. Reversing the string makes the first character vary as fast as possible (`00`, `10`, `20`, … instead of `00`, `01`, `02`, …), so typing the first letter in Fish actually narrows the list. That is the whole reason the IDs look slightly odd. - -To actually get those completions in Fish, run `ask fish | source` (or drop it into Fish's `conf.d`) — it gives you tab-completion for both subcommands and the reversed alias IDs. - -`ask list` prints a compact table: - -``` -Urg | Pri | ID | Status | Started | Tags | Description ----------------------------------------------------------------------------- -7.8 | H | os0 | pending | no | agent | implement config reload -5.7 | M | ps0 | pending | no | agent | add fish completion docs -3.6 | L | qs0 | pending | no | agent | deprecate hexai-mcp-server README note -``` - -And `ask info os0` shows one task without exposing the raw UUID: - -``` -ID: os0 -Description: implement config reload -Status: pending -Started: no -Priority: H -Urgency: 7.8 -Tags: agent -``` - -## Running multiple providers side by side - -One feature I use more than I expected: per-surface model lists. In `config.toml` you can configure several providers or models for the same entry point, and Hexai fans the request out to all of them in parallel. - -```toml -[[models.cli]] -provider = "openai" -model = "gpt-4o-mini" -temperature = 0.4 - -[[models.cli]] -provider = "ollama" -model = "qwen3-coder:30b-a3b-q4_K_M" -temperature = 0.2 -``` - -With that, `hexai 'summarize this file'` prints two labeled answers side by side: - -``` -ollama:qwen3-coder:30b-a3b-q4_K_M: -A short Go program that reads a file line by line and prints each line. - -openai:gpt-4o-mini: -Reads a file and echoes each line. Returns early on open errors. -``` - -It is handy for comparing local and cloud models, or for just seeing which one gives the cleaner response. Code actions still use only the first entry; extra entries there are ignored with a warning. - -## What to watch out for - -A few honest caveats: - -* I mainly test Hexai with Helix inside tmux. Other editors might work through LSP, but your mileage will vary. -* The `hexai-mcp-server` binary is experimental and effectively deprecated. I manage prompts through slash commands and the agent system now, so the MCP server is not getting much attention. -* Wiring the tmux popup and status line takes a little manual config. It is not plug-and-play like a VS Code extension. -* Auto-completions can be chatty. You can disable them on the fly with `/disable>` in chat, or tune the debounce in `config.toml`. - -## It will keep changing - -Hexai is a personal tool, and it will keep changing. Things go in and come back out: the tmux popup editor for Cursor Agent prompts I wrote about earlier got folded into Hexai, then removed again once every agent added Ctrl+g or Ctrl+e to edit a prompt in `$EDITOR`. - -=> ./2026-02-02-tmux-popup-editor-for-cursor-agent-prompts.gmi 2026-02-02 - A tmux popup editor for Cursor Agent CLI prompts - -The MCP server that ships with Hexai is experimental and may get cut too. As time goes on I will keep trying ideas — maybe a whole coding agent one day, maybe not. If you want to poke at it or open an issue, it lives on Codeberg. - -## Other related posts: - -=> ./2026-02-02-tmux-popup-editor-for-cursor-agent-prompts.gmi 2026-02-02 - A tmux popup editor for Cursor Agent CLI prompts -=> ./2026-02-14-meta-slash-commands-for-prompts-and-context.gmi 2026-02-14 - Meta slash commands for prompts and context - -E-Mail your comments to `paul@nospam.buetow.org` :-) - -=> ../ Back to the main site diff --git a/gemfeed/atom.xml b/gemfeed/atom.xml index 7477472c..4d8934b2 100644 --- a/gemfeed/atom.xml +++ b/gemfeed/atom.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> - <updated>2026-07-08T17:16:26+03:00</updated> + <updated>2026-07-08T17:18:58+03:00</updated> <title>foo.zone feed</title> <subtitle>To be in the .zone!</subtitle> <link href="gemini://foo.zone/gemfeed/atom.xml" rel="self" /> @@ -431,430 +431,6 @@ Reads a file and echoes each line. Returns early on open errors. </content> </entry> <entry> - <title>Unleashing Hexai: AI companion for Helix and the terminal in general</title> - <link href="gemini://foo.zone/gemfeed/2026-07-09-unleashing-hexai.gmi" /> - <id>gemini://foo.zone/gemfeed/2026-07-09-unleashing-hexai.gmi</id> - <updated>2026-07-08T17:10:52+03:00</updated> - <author> - <name>Paul Buetow aka snonux</name> - <email>paul@dev.buetow.org</email> - </author> - <summary>I have been using Helix as my main editor for a while now. It is fast, modal, and stays out of the way. The one thing I missed was a bit of LLM help without leaving the editor or opening a browser tab. So I built Hexai.</summary> - <content type="xhtml"> - <div xmlns="http://www.w3.org/1999/xhtml"> - <h1 style='display: inline' id='unleashing-hexai-ai-companion-for-helix-and-the-terminal-in-general'>Unleashing Hexai: AI companion for Helix and the terminal in general</h1><br /> -<br /> -<span class='quote'>Published at 2026-07-08T17:10:52+03:00</span><br /> -<br /> -<span>I have been using Helix as my main editor for a while now. It is fast, modal, and stays out of the way. The one thing I missed was a bit of LLM help without leaving the editor or opening a browser tab. So I built Hexai.</span><br /> -<br /> -<span>Hexai is an AI add-on for Helix. It speaks LSP, so it also works with other editors in theory, but I only test it with Helix. It gives me inline completions, in-editor chat, code actions, a terminal CLI, a tmux popup action runner, and a small task manager for agent work. It is written in Go, lives on Codeberg, and is configured through plain TOML files.</span><br /> -<br /> -<span>Hexai has been an undercover pet project of mine since around mid-last year. As I write this it is at version <span class='inlinecode'>0.42.1</span>, so it has been quietly growing for a good while before this first proper write-up.</span><br /> -<br /> -<a class='textlink' href='https://codeberg.org/snonux/hexai'>Hexai source code</a><br /> -<a class='textlink' href='https://helix-editor.com'>Helix editor</a><br /> -<br /> -<a href='./unleashing-hexai/01-logo.png'><img alt='Hexai logo' title='Hexai logo' src='./unleashing-hexai/01-logo.png' /></a><br /> -<br /> -<h2 style='display: inline' id='table-of-contents'>Table of Contents</h2><br /> -<br /> -<ul> -<li><a href='#unleashing-hexai-ai-companion-for-helix-and-the-terminal-in-general'>Unleashing Hexai: AI companion for Helix and the terminal in general</a></li> -<li>⇢ <a href='#what-it-is'>What it is</a></li> -<li>⇢ <a href='#installing-it'>Installing it</a></li> -<li>⇢ <a href='#configuring-providers'>Configuring providers</a></li> -<li>⇢ <a href='#wiring-it-into-helix'>Wiring it into Helix</a></li> -<li>⇢ <a href='#inline-chat-and-prompts'>Inline chat and prompts</a></li> -<li>⇢ <a href='#code-actions-via-the-tmux-popup'>Code actions via the tmux popup</a></li> -<li>⇢ <a href='#the-cli'>The CLI</a></li> -<li>⇢ <a href='#managing-agent-tasks-with-ask'>Managing agent tasks with ask</a></li> -<li>⇢ <a href='#running-multiple-providers-side-by-side'>Running multiple providers side by side</a></li> -<li>⇢ <a href='#what-to-watch-out-for'>What to watch out for</a></li> -<li>⇢ <a href='#it-will-keep-changing'>It will keep changing</a></li> -<li>⇢ <a href='#other-related-posts'>Other related posts:</a></li> -</ul><br /> -<h2 style='display: inline' id='what-it-is'>What it is</h2><br /> -<br /> -<span>Hexai is really a bundle of small tools that share the same configuration:</span><br /> -<br /> -<ul> -<li><span class='inlinecode'>hexai-lsp-server</span> — the LSP server that Helix talks to.</li> -<li><span class='inlinecode'>hexai</span> — a standalone CLI for quick LLM questions from the terminal or scripts.</li> -<li><span class='inlinecode'>hexai-tmux-action</span> — a Bubble Tea TUI that pops up inside tmux and runs code actions on the current selection.</li> -<li><span class='inlinecode'>ask</span> — a tiny task management CLI for agent-managed project work.</li> -</ul><br /> -<span>Everything uses the same <span class='inlinecode'>config.toml</span>, the same provider pool, and the same prompt overrides. I can switch models in one place and the LSP, CLI, and popup all follow along.</span><br /> -<br /> -<span>These are opinionated tools. They reflect how I work — Helix inside tmux, a terminal CLI, a thin Taskwarrior wrapper — not a generic plugin system. If your workflow matches mine, they get out of the way; if it doesn't, you will probably want to tweak the config or fork it.</span><br /> -<br /> -<h2 style='display: inline' id='installing-it'>Installing it</h2><br /> -<br /> -<span>The easiest way is to install the binaries with <span class='inlinecode'>go install</span>. Each binary is a separate <span class='inlinecode'>cmd/</span> package:</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre>go install codeberg.org/snonux/hexai/cmd/hexai@latest -go install codeberg.org/snonux/hexai/cmd/hexai-lsp-server@latest -go install codeberg.org/snonux/hexai/cmd/hexai-tmux-action@latest -go install codeberg.org/snonux/hexai/cmd/ask@latest -</pre> -<br /> -<span>If you prefer to build from a checkout, Hexai uses Mage:</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre>go install github.com/magefile/mage@latest -mage build -mage install -</pre> -<br /> -<span>That drops <span class='inlinecode'>hexai</span>, <span class='inlinecode'>hexai-lsp-server</span>, <span class='inlinecode'>hexai-tmux-action</span>, and <span class='inlinecode'>ask</span> into your <span class='inlinecode'>GOPATH/bin</span>.</span><br /> -<br /> -<h2 style='display: inline' id='configuring-providers'>Configuring providers</h2><br /> -<br /> -<span>Hexai looks for a global config at <span class='inlinecode'>~/.config/hexai/config.toml</span> and a per-project override at <span class='inlinecode'>.hexaiconfig.toml</span> in the git root. Environment variables prefixed with <span class='inlinecode'>HEXAI_</span> win over both files.</span><br /> -<br /> -<span>The default provider is Ollama Cloud with <span class='inlinecode'>kimi-k2.6</span> (it might be different by the time you read this!). To use a local Ollama server instead, override the base URL:</span><br /> -<br /> -<pre> -[provider] -name = "ollama" - -[ollama] -model = "qwen3-coder:30b-a3b-q4_K_M" -base_url = "http://localhost:11434" -</pre> -<br /> -<span>Because that points at <span class='inlinecode'>localhost</span>, nothing leaves your machine — prompt, code, and reply all stay local. That is the main reason I keep a local Ollama around.</span><br /> -<br /> -<span>For OpenAI, the config is similar:</span><br /> -<br /> -<pre> -[provider] -name = "openai" - -[openai] -model = "gpt-4o-mini" -</pre> -<br /> -<span>Hexai reads the API key from <span class='inlinecode'>HEXAI_OPENAI_API_KEY</span> first, then falls back to <span class='inlinecode'>OPENAI_API_KEY</span>. The same pattern works for OpenRouter, Anthropic, and You.com.</span><br /> -<br /> -<h2 style='display: inline' id='wiring-it-into-helix'>Wiring it into Helix</h2><br /> -<br /> -<span>Tell Helix about the Hexai LSP server in <span class='inlinecode'>~/.config/helix/languages.toml</span>. Here is my Go setup:</span><br /> -<br /> -<pre> -[[language]] -name = "go" -auto-format = true -formatter = { command = "goimports" } -language-servers = [ "gopls", "hexai" ] - -[language-server.hexai] -command = "hexai-lsp-server" -</pre> -<br /> -<span>You can add <span class='inlinecode'>hexai</span> after <span class='inlinecode'>gopls</span> or any other LSP. It does not replace them; it just adds completions, code actions, and chat on top.</span><br /> -<br /> -<span>Once the LSP is wired in, Hexai also offers inline auto-completions as you type. By default it fires after a short idle debounce (<span class='inlinecode'>completion_debounce_ms</span>, 800 ms) when you hit one of the trigger characters (<span class='inlinecode'>.</span> <span class='inlinecode'>:</span> <span class='inlinecode'>/</span> <span class='inlinecode'>_</span> space), and it waits for every configured backend before showing results (<span class='inlinecode'>completion_wait_all</span>). All of it is tunable in <span class='inlinecode'>config.toml</span>, and you can turn completions off for a session without restarting — see the slash commands below.</span><br /> -<br /> -<span>For the popup action runner, bind a key in <span class='inlinecode'>~/.config/helix/config.toml</span>:</span><br /> -<br /> -<pre> -[keys.select] -"A-a" = ":pipe hexai-tmux-action" - -[keys.normal] -"A-a" = ["select_line", ":pipe hexai-tmux-action"] -</pre> -<br /> -<span>I use Alt-a. Select some code, hit Alt-a, and the popup appears.</span><br /> -<br /> -<h2 style='display: inline' id='inline-chat-and-prompts'>Inline chat and prompts</h2><br /> -<br /> -<span>The LSP adds two lightweight ways to talk to the model without leaving the editor:</span><br /> -<br /> -<ul> -<li>End a line with <span class='inlinecode'>?></span>, <span class='inlinecode'>!></span>, <span class='inlinecode'>:></span>, or <span class='inlinecode'>;></span> to ask a question. Hexai removes only the trailing <span class='inlinecode'>></span>, keeps the question, and inserts a <span class='inlinecode'>> </span> quoted reply below the line.</li> -<li>Type <span class='inlinecode'>>!do something></span> inline to ask for a quick edit, or <span class='inlinecode'>>>!do something></span> to replace the whole line with the completion.</li> -</ul><br /> -<span>Chat example — a question ending in <span class='inlinecode'>?></span>:</span><br /> -<br /> -<pre> -What is a Go slice?> -</pre> -<br /> -<span>After the LSP responds you get something like:</span><br /> -<br /> -<pre> -What is a Go slice? - -> A slice is a dynamically-sized view into an array. It stores a pointer to -> the backing array plus length and capacity. -</pre> -<br /> -<span>Inline example — <span class='inlinecode'>>>!</span> replaces the whole line with the completion:</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre>>>!document this function> -</pre> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><i><font color="silver">// Foo returns the square of n.</font></i> -<b><u><font color="#000000">func</font></u></b> Foo(n int) int { <b><u><font color="#000000">return</font></u></b> n * n } -</pre> -<br /> -<span>Context is included automatically. For follow-ups, Hexai keeps the last few Q/A pairs above the cursor in mind, so you can ask related questions without repeating yourself.</span><br /> -<br /> -<span>There are a few slash commands you can type at the end of a chat line: <span class='inlinecode'>/reload></span> re-reads <span class='inlinecode'>config.toml</span> without restarting the LSP, <span class='inlinecode'>/disable></span> pauses auto-completions for the session, and <span class='inlinecode'>/enable></span> turns them back on.</span><br /> -<br /> -<span>In the editor buffer it ends up looking like this — the question stays, the reply is quoted below, and a follow-up picks up the same context:</span><br /> -<br /> -<pre> -What is a Go slice? - -> A slice is a dynamically-sized view into an array. It stores a pointer to -> the backing array plus length and capacity. - -And how do I append to one? - -> Use the built-in append: s = append(s, x). It grows the backing array -> when capacity is exhausted, returning a new slice. -</pre> -<br /> -<h2 style='display: inline' id='code-actions-via-the-tmux-popup'>Code actions via the tmux popup</h2><br /> -<br /> -<span><span class='inlinecode'>hexai-tmux-action</span> is my favorite part. Inside a tmux session, select code in Helix and press the bound key. A tmux popup opens with this menu:</span><br /> -<br /> -<pre> -r Rewrite selection -i Simplify and improve -c Document code -t Generate Go unit test(s) -f Fix typos and improve grammar and clarity -p Custom prompt (opens your editor) -s Skip -</pre> -<br /> -<span>Pick one, the popup closes, and the rewritten code is piped back into Helix. For rewrite actions, I usually add a small instruction in a strict marker like <span class='inlinecode'>;extract this into a helper;</span> inside the selection. The runner finds the first instruction and uses it.</span><br /> -<br /> -<span>A mandatory detail: the popup is a real tmux popup, so Helix must be running inside a tmux session for this to work — there is no fallback to a separate window. Start it with:</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre>tmux new -s hx -hx some-file.go -</pre> -<br /> -<span>Then select code and hit Alt-a. No special <span class='inlinecode'>tmux.conf</span> is required for the popup itself; the only hard requirement is that Helix lives inside tmux (and tmux 3.2 or newer, since the popup uses tmux's popup feature).</span><br /> -<br /> -<span>The menu is fully configurable. This is how I replace it with a smaller custom menu:</span><br /> -<br /> -<pre> -[[tmux_action.menu]] -kind = "rewrite" -hotkey = "r" - -[[tmux_action.menu]] -kind = "document" -hotkey = "c" - -[[tmux_action.menu]] -kind = "custom" -custom_id = "extract-function" -hotkey = "e" - -[[tmux_action.menu]] -kind = "skip" -hotkey = "s" -</pre> -<br /> -<span>Custom actions reference entries under <span class='inlinecode'>[[prompts.code_action.custom]]</span> in the same config file.</span><br /> -<br /> -<a href='./unleashing-hexai/06-tmux-popup.jpg'><img alt='The hexai-tmux-action popup menu inside tmux' title='The hexai-tmux-action popup menu inside tmux' src='./unleashing-hexai/06-tmux-popup.jpg' /></a><br /> -<br /> -<span>Optional but useful: have tmux show live Hexai stats (provider, model, rpm, bytes) in the status line. Add this to <span class='inlinecode'>~/.config/tmux/tmux.conf</span> (or <span class='inlinecode'>~/.tmux.conf</span>):</span><br /> -<br /> -<pre> -set -g status-right '#{@hexai_status} #[fg=colour8]| %H:%M' -set -g status-right-length 120 -</pre> -<br /> -<span>The <span class='inlinecode'>@hexai_status</span> option is updated by the CLI, the LSP, and the action runner. Disable it with <span class='inlinecode'>HEXAI_TMUX_STATUS=0</span> if you don't want it.</span><br /> -<br /> -<a href='./unleashing-hexai/10-tmux-status.png'><img alt='tmux status line showing live Hexai LLM stats' title='tmux status line showing live Hexai LLM stats' src='./unleashing-hexai/10-tmux-status.png' /></a><br /> -<br /> -<h2 style='display: inline' id='the-cli'>The CLI</h2><br /> -<br /> -<span>The <span class='inlinecode'>hexai</span> CLI is useful for quick questions from the terminal or from scripts:</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><i><font color="silver"># Ask from stdin</font></i> -cat some-file.go | hexai - -<i><font color="silver"># Ask from an argument</font></i> -hexai <font color="#808080">'explain this function'</font> - -<i><font color="silver"># Both stdin and argument are concatenated</font></i> -cat some-file.go | hexai <font color="#808080">'write unit tests for this'</font> - -<i><font color="silver"># Open the global config in $HEXAI_EDITOR or $EDITOR</font></i> -hexai config - -<i><font color="silver"># Simulate how fast a model feels without calling a provider</font></i> -hexai --tps-simulation <font color="#000000">12</font>-<font color="#000000">18</font> -</pre> -<br /> -<span>A real one-shot looks like this (only stdout is shown):</span><br /> -<br /> -<pre> -$ hexai 'install ripgrep on fedora' -sudo dnf install ripgrep -</pre> -<br /> -<span>The provider label and the run summary (timing, token counts, rpm) go to stderr, so <span class='inlinecode'>stdout</span> stays clean for pipes — <span class='inlinecode'>hexai 'install ripgrep on fedora' | sh</span> just works.</span><br /> -<br /> -<h2 style='display: inline' id='managing-agent-tasks-with-ask'>Managing agent tasks with ask</h2><br /> -<br /> -<span><span class='inlinecode'>ask</span> is a thin wrapper around Taskwarrior that auto-scopes tasks to the current git project and tags them with <span class='inlinecode'>+agent</span>. I use it to keep track of what the coding agent is supposed to do next.</span><br /> -<br /> -<span>Under the hood every <span class='inlinecode'>ask</span> command is just a Taskwarrior command filtered to <span class='inlinecode'>project:REPO +agent</span>, where <span class='inlinecode'>REPO</span> is the name of the git repository root <span class='inlinecode'>ask</span> was run in. The tasks are plain Taskwarrior tasks, so you can drop down to <span class='inlinecode'>task</span> itself any time and work with the same data. From the hexai repo, for example:</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><i><font color="silver"># Same tasks, raw Taskwarrior</font></i> -task project:hexai list -task project:hexai +agent next -</pre> -<br /> -<span><span class='inlinecode'>ask</span> just hides the project filter, the <span class='inlinecode'>+agent</span> tag, and the raw UUIDs so the day-to-day output stays small and project-local.</span><br /> -<br /> -<span>That scoping is also a security boundary, and the main reason I let an LLM agent touch my Taskwarrior database at all. Because <span class='inlinecode'>ask</span> always applies the <span class='inlinecode'>project:REPO +agent</span> filter, the agent can only see and modify tasks in its own current project — it cannot delete, reprioritize, or even see anything outside that filter. So <span class='inlinecode'>ask</span> is really a safety wrapper around <span class='inlinecode'>task</span>: you can hand it to a coding agent without giving it free rein over the rest of your tasks.</span><br /> -<br /> -<!-- Generator: GNU source-highlight 3.1.9 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><i><font color="silver"># Add a task for the current project</font></i> -ask add priority:H <font color="#808080">"implement config reload"</font> - -<i><font color="silver"># List pending agent tasks</font></i> -ask list - -<i><font color="silver"># Start and finish work (ask add prints the alias, e.g. os0)</font></i> -ask start os0 -ask <b><u><font color="#000000">done</font></u></b> os0 - -<i><font color="silver"># See details without exposing raw UUIDs</font></i> -ask info os0 -</pre> -<br /> -<span>The IDs shown are stable local aliases, not Taskwarrior's numeric IDs. Taskwarrior gives you two built-in identifiers: a numeric ID that isn't stable across syncs and exports, and a UUID that is stable but far too long to type by hand. <span class='inlinecode'>ask</span> instead keeps its own mapping from each task's UUID to a short, permanent alias (cached under Hexai's cache dir) — so you get the best of both: a stable, short ID that never changes even if tasks above it get completed or deleted. <span class='inlinecode'>ask info</span> hides the raw UUID unless <span class='inlinecode'>HEXAI_DEBUG</span> is set, so the short alias is the one you actually use day to day.</span><br /> -<br /> -<span><span class='inlinecode'>ask</span> works from anywhere inside the project git tree and derives the project name from the repo root. To manage tasks for another project, use <span class='inlinecode'>ask proj:hexai list</span>.</span><br /> -<br /> -<span>One detail worth knowing: the alias strings are reversed on purpose. The underlying counter is monotonic (1, 2, 3, …), and a naive encoding would make consecutive tasks share a leading character once the list grows past 36 (<span class='inlinecode'>00</span>, <span class='inlinecode'>01</span>, <span class='inlinecode'>02</span>, … all start with <span class='inlinecode'>0</span>), which kills shell tab-completion. Reversing the string makes the first character vary as fast as possible (<span class='inlinecode'>00</span>, <span class='inlinecode'>10</span>, <span class='inlinecode'>20</span>, … instead of <span class='inlinecode'>00</span>, <span class='inlinecode'>01</span>, <span class='inlinecode'>02</span>, …), so typing the first letter in Fish actually narrows the list. That is the whole reason the IDs look slightly odd.</span><br /> -<br /> -<span>To actually get those completions in Fish, run |