add hexai-tmux-edit documentation to all doc files

Update README, build guide, configuration guide, usage guide, and tmux
guide with hexai-tmux-edit popup editor documentation including supported
agents, keybinding setup, flags, workflow, and configuration examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

4 files changed, 92 insertions, 2 deletions

diff --git a/docs/buildandinstall.md b/docs/buildandinstall.md
index 7400eda..89a7c57 100644
--- a/docs/buildandinstall.md
+++ b/docs/buildandinstall.md
@@ -3,7 +3,7 @@
 Hexai uses Mage for developer tasks. Install Mage, then run targets like build, dev, test, and install.
 
 - Install Mage: `go install github.com/magefile/mage@latest`
-- Build binaries: `mage build` (produces `hexai`, `hexai-lsp`, and `hexai-tmux-action`)
+- Build binaries: `mage build` (produces `hexai`, `hexai-lsp`, `hexai-tmux-action`, and `hexai-tmux-edit`)
 - Dev build (+ tests, vet, lint): `mage dev`
 - Run tests: `mage test`
 - Run tests with coverage: `go test ./... -cover`
@@ -21,3 +21,4 @@ Either use the Mage method as mentioned above, or install directly with:
 - CLI: `go install codeberg.org/snonux/hexai/cmd/hexai@latest`
 - LSP: `go install codeberg.org/snonux/hexai/cmd/hexai-lsp@latest`
 - Action runner: `go install codeberg.org/snonux/hexai/cmd/hexai-tmux-action@latest`
+- Tmux popup editor: `go install codeberg.org/snonux/hexai/cmd/hexai-tmux-edit@latest`
diff --git a/docs/configuration.md b/docs/configuration.md
index 10e3c59..52e0689 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -110,6 +110,35 @@ See the [tmux integration guide](docs/tmux.md) for details on configuring the st
 
 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:
+- 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 \u201cSimplify and improve\u201d action:
   - `simplify_system`
   - `simplify_user` (uses `{{selection}}`)
+
+Hexai Tmux Edit (popup editor)
+
+- `hexai-tmux-edit` opens `$EDITOR` in a tmux popup for composing longer AI agent prompts.
+- Configure popup dimensions and agent detection patterns in the `[tmux_edit]` section:
+
+  ```toml
+  [tmux_edit]
+  popup_width = "80%"
+  popup_height = "80%"
+  # default_agent = "claude"   # force agent; skip auto-detect
+  ```
+
+- Override or add agent definitions with `[[tmux_edit.agents]]` (merged with built-in defaults by name):
+
+  ```toml
+  [[tmux_edit.agents]]
+  name = "claude"
+  display_name = "Claude Code"
+  detect_pattern = "(?i)(claude|anthropic)"
+  prompt_pattern = '(?m)>\s*(.+)$'
+  clear_first = true
+  clear_keys = "C-u"
+  newline_keys = "S-Enter"
+  submit_keys = "Enter"
+  ```
+
+- Built-in agents: `claude`, `cursor`, `amp`, `aider`. See [config.toml.example](../config.toml.example) for all fields.
+- Tmux keybinding: `bind e run-shell -b "hexai-tmux-edit --pane '#{pane_id}'"`
diff --git a/docs/tmux.md b/docs/tmux.md
index a5e397c..250903e 100644
--- a/docs/tmux.md
+++ b/docs/tmux.md
@@ -68,3 +68,17 @@ 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 (Claude Code, Cursor, Amp, Aider, etc.).
+
+Add this keybinding to `~/.tmux.conf`:
+
+```
+bind e run-shell -b "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.
diff --git a/docs/usage.md b/docs/usage.md
index 49ed4e6..9a6d9ed 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -151,6 +151,52 @@ Tips:
 - Ensure Helix runs inside tmux to see the status updates.
 - You can also set a language-specific binding in `languages.toml` if preferred.
 
+## Hexai Tmux Edit (Popup Editor)
+
+`hexai-tmux-edit` opens your `$EDITOR` in a tmux popup for composing longer AI agent prompts. It captures existing prompt text from the target pane, pre-fills the editor, and sends the edited text back via `tmux send-keys`.
+
+This is useful when working with AI CLI agents (Claude Code, Cursor, Amp, Aider, etc.) and you need to compose a longer, multi-line prompt with the comfort of your regular editor (spellcheck, search/replace, etc.).
+
+### Supported agents
+
+Built-in agent detection (auto-detected from pane content):
+- **Claude Code** -- detects "claude" or "anthropic" in pane
+- **Cursor** -- detects "cursor" in pane, strips "INSERT"/"Add a follow-up"
+- **Amp** -- detects "amp" or "sourcegraph" in pane
+- **Aider** -- detects "aider" in pane
+
+Additional agents can be added via `[tmux_edit.agents]` in config.toml without code changes.
+
+### Tmux keybinding
+
+Add to `~/.tmux.conf`:
+
+```
+bind e run-shell -b "hexai-tmux-edit --pane '#{pane_id}'"
+```
+
+The `#{pane_id}` is expanded by tmux to the active pane at keypress time, so the popup editor always knows which pane to send text back to.
+
+### Flags
+
+- `--config` path to config file (default: `$XDG_CONFIG_HOME/hexai/config.toml`)
+- `--agent` explicit agent name (auto-detected if omitted)
+- `--pane` tmux target pane ID (e.g. `%5`)
+
+### Workflow
+
+1. Press your tmux keybinding (e.g. `prefix + e`)
+2. A tmux popup opens with your `$EDITOR`, pre-filled with any existing prompt text
+3. Edit or compose your prompt
+4. Save and close the editor
+5. The edited text is sent to the agent's pane via `tmux send-keys`
+
+If you keep the original text unchanged and append new text, only the appended text is sent. If you rewrite the prompt entirely, the full new text is sent. If you save an empty file or don't change anything, nothing is sent.
+
+### Configuration
+
+See `[tmux_edit]` in [config.toml.example](../config.toml.example) for all options, including custom popup dimensions and agent overrides.
+
 ### Slash commands
 
 Type a slash command at the end of a chat line (for example `/? reload>`). Available commands: