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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
# Hexai usage and examples
This document describes how to run the LSP server, configure Helix, use in-editor chat,
inline triggers, code actions, and the CLI — with examples.
## LSP server
- Run over stdio: `hexai-lsp`
- Flags:
- `-version`: print Hexai version and exit.
- `-log`: path to log file (default `/tmp/hexai-lsp.log`).
### Configure in Helix
In `~/.config/helix/languages.toml`:
```toml
[[language]]
name = "go"
auto-format = true
diagnostic-severity = "hint"
formatter = { command = "goimports" }
language-servers = [ "gopls", "golangci-lint-lsp", "hexai" ]
[language-server.hexai]
command = "hexai-lsp"
```
Note: additional LSPs (`gopls`, `golangci-lint-lsp`) are optional; Hexai works without them.
## In-editor chat
Ask a question at the end of a line and receive the answer inline.
- End your question line with a trigger: `?>`, `!>`, or `:>`.
- Hexai removes only the trailing `>` from the question line (and keeps your trailing punctuation). Inline code-completion triggers now use `>text>` (inline) or `>>text>` (line-replace).
- It inserts a blank line, then a reply line prefixed with `> `, then one extra newline so most
editors place the cursor on a fresh blank line after the answer.
- If a `>` reply already exists below the question, Hexai won’t answer again.
Example:
```text
What is a slice in Go?>
> A slice is a dynamically-sized, flexible view into the elements of an array. It references
> an underlying array and tracks length/capacity; most Go code uses slices instead of arrays.
```
Context: Hexai includes up to the three most recent Q/A pairs above the question when asking the LLM, so follow-ups remain on topic (e.g., “Are there many tourists?” after a location answer).
## Inline triggers
Hexai supports inline prompt tags you can type in code to request an action from the LLM and then auto-clean the tag. The new `>`-based forms are:
- `>do something>` — uses the text between `>` markers as the instruction and removes only the prompt. Strict form requires no space after the first `>` and no space before the closing `>`.
- `>>do something>` — same as above, but replaces the entire current line with the completion.
Spaced variants (e.g., `> spaced >`) are ignored.
## Code actions
Operate on the current selection in Helix:
- Rewrite selection: finds the first instruction inside the selection and rewrites accordingly.
- Resolve diagnostics: gathers only diagnostics overlapping the selection and fixes them by editing the selected code; diagnostics outside the selection are not changed.
- Implement unit test (Go): when editing a `.go` file, adds a code action to generate a unit test for the function under the cursor. If `<file>_test.go` exists, appends a new `Test*`; otherwise creates the test file with `package` and `import "testing"`.
- Document code: adds idiomatic documentation comments to the selected code, preserving behavior and returning only the documented code.
Instruction sources (first match wins):
- Strict marker: `;text;` (no space after first `;`).
- Line comments: `// text`, `# text`, `-- text`.
- Single-line block comments: `/* text */`, `<!-- text -->`.
## CLI usage
Process text via the configured LLM:
- `cat SOMEFILE.txt | hexai`
- `hexai 'some prompt text here'`
- `cat SOMEFILE.txt | hexai 'some prompt text here'` (stdin and arg are concatenated)
Defaults: concise answers. If the prompt asks for commands, Hexai outputs only commands. Add the word `explain` to request a verbose explanation. Exit codes: `0` success, `1` provider/config error, `2` no input.
### Examples
```sh
# From stdin only
cat SOMEFILE.txt | hexai
# From arg only
hexai 'summarize: list 3 bullets'
# From both (stdin first, then arg)
cat SOMEFILE.txt | hexai 'explain the tradeoffs'
# Commands-only output (no explanation)
hexai 'install ripgrep on macOS'
# Verbose explanation
hexai 'install ripgrep on macOS and explain'
```
## Hexai Action (TUI)
`hexai-tmux-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file.
- Choose an action with arrow keys, `j/k`, `g/G`, Enter, or hotkeys `[s] [r] [c] [t]`.
- Includes: Rewrite selection, Simplify and improve, Document code, Generate Go unit test(s), Skip.
- “Custom prompt” (hotkey `[p]`) opens your editor (`$HEXAI_EDITOR` or `$EDITOR`) on a temporary `.md` file to write a free-form instruction.
- Output is written to stdout by default, or to a file via `--outfile`.
Input formats
- Rewrite: include an inline instruction near the top of the selection using one of:
- `;do something;`
- `/* do something */`
- `<!-- do something -->`
- `// do something` (or `#`, `--`)
Examples
```sh
# From stdin
cat input.go | hexai-tmux-action
# From file to file
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.
|
