From 70d217a2a8e2efc59c03afe64695e69b3b4eea36 Mon Sep 17 00:00:00 2001
From: Ogulcan Celik <ogulcancelik@gmail.com>
Date: Sun, 10 May 2026 03:08:17 +0300
Subject: docs: document custom command keybindings

---
 CONFIGURATION.md | 38 ++++++++++++++++++++++++++++++++++++++
 README.md        |  9 +++++++++
 src/main.rs      |  8 ++++++++
 3 files changed, 55 insertions(+)

diff --git a/CONFIGURATION.md b/CONFIGURATION.md
index d1210554..bdea9919 100644
--- a/CONFIGURATION.md
+++ b/CONFIGURATION.md
@@ -139,6 +139,44 @@ focus_pane_right = "alt+l"
 | `resize_mode` | `r` | enter or leave resize mode |
 | `toggle_sidebar` | `b` | collapse or expand the sidebar |
 
+### custom command keybindings
+
+Use `[[keys.command]]` to bind a prefix-mode key to a command. Press the prefix key, then the configured key.
+
+```toml
+[[keys.command]]
+key = "g"
+type = "pane"
+command = "lazygit"
+```
+
+`type` is optional and defaults to `shell`.
+
+| type | behavior |
+|------|----------|
+| `shell` | run the command detached in the background |
+| `pane` | open a temporary zoomed pane, run the command there, then close the pane when the command exits |
+
+Commands run through `/bin/sh -lc`. Herdr sets the command working directory to the active pane cwd when available and provides context through environment variables:
+
+| variable | value |
+|----------|-------|
+| `HERDR_SOCKET_PATH` | active herdr socket path |
+| `HERDR_BIN_PATH` | current herdr binary path |
+| `HERDR_ACTIVE_WORKSPACE_ID` | active workspace id |
+| `HERDR_ACTIVE_TAB_ID` | active tab id |
+| `HERDR_ACTIVE_PANE_ID` | focused pane id |
+| `HERDR_ACTIVE_PANE_CWD` | focused pane cwd |
+
+Example detached helper:
+
+```toml
+[[keys.command]]
+key = "shift+g"
+type = "shell"
+command = "notify-send herdr 'custom command ran'"
+```
+
 ## theme
 
 herdr ships with 10 built-in color themes. set one in config:
diff --git a/README.md b/README.md
index efeeb85f..f25bd300 100644
--- a/README.md
+++ b/README.md
@@ -192,6 +192,15 @@ press `ctrl+b` to enter navigate mode.
 
 resize mode: `h`/`l` resize width, `j`/`k` resize height, `esc` exit.
 
+custom command keybindings can launch detached shell helpers or temporary panes from prefix mode:
+
+```toml
+[[keys.command]]
+key = "g"
+type = "pane" # "shell" or "pane"
+command = "lazygit"
+```
+
 mouse is supported throughout. full reference: [`CONFIGURATION.md`](./CONFIGURATION.md).
 
 ## configuration
diff --git a/src/main.rs b/src/main.rs
index c35a4084..2b8c76b6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -103,6 +103,14 @@ const DEFAULT_CONFIG: &str = r##"# herdr configuration
 # resize_mode = "r"
 # toggle_sidebar = "b"
 
+# Custom prefix-mode commands. Press prefix, then the configured key.
+# type = "shell" runs detached in the background.
+# type = "pane" opens a temporary pane and closes it when the command exits.
+# [[keys.command]]
+# key = "g"
+# type = "pane"
+# command = "lazygit"
+
 [ui]
 # Sidebar width (auto-scaled based on workspace names, this sets the default)
 # sidebar_width = 26
-- 
cgit v1.2.3