docs: cli external editor (#6922)

documentation/docs/guides/environment-variables.md

@@ -157,6 +157,7 @@ These variables control how goose manages conversation sessions and context.
 | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 |
 | `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/subagents) to complete before timeout | Integer (e.g., 25) | 25 |
 | `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` |
+| `GOOSE_PROMPT_EDITOR` | [External editor](/docs/guides/goose-cli-commands#external-editor-mode) to use for composing prompts instead of CLI input | Editor command (e.g., "vim", "code --wait") | Unset (uses CLI input) |
 | `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response  markdown | "light", "dark", "ansi" | "dark" |
 | `GOOSE_CLI_NEWLINE_KEY` | Customize the keyboard shortcut for [inserting newlines in CLI input](/docs/guides/goose-cli-commands#keyboard-shortcuts) | Single character (e.g., "n", "m") | "j" (Ctrl+J) |
 | `GOOSE_RANDOM_THINKING_MESSAGES` | Controls whether to show amusing random messages during processing | "true", "false" | "true" |
@@ -187,6 +188,9 @@ export GOOSE_SUBAGENT_MAX_TURNS=50
 # Use multiple context files
 export CONTEXT_FILE_NAMES='["CLAUDE.md", ".goosehints", ".cursorrules", "project_rules.txt"]'
 
+# Use vim for composing prompts
+export GOOSE_PROMPT_EDITOR=vim
+
 # Set the ANSI theme for the session
 export GOOSE_CLI_THEME=ansi
 

documentation/docs/guides/goose-cli-commands.md

@@ -740,6 +740,59 @@ goose session --name use-custom-theme
 
 ---
 
+### External Editor Mode
+
+For composing longer prompts or working with complex code snippets, you can configure goose to use your preferred text editor instead of CLI input. This replaces the standard CLI input and keyboard shortcuts for the entire session.
+
+**How it works:**
+1. goose opens your configured editor with a template file
+2. Type your prompt after the `# Your prompt:` heading (conversation history is shown below for context)
+3. Save the file and close/exit the editor to send your prompt to goose
+4. goose processes your prompt and reopens the editor with the response added to the conversation history
+5. Repeat steps 2-4 for each message in the conversation
+
+You can use any editor that accepts a file path argument, such as vim, nano, emacs, and VS Code.
+
+**Configuration:**
+
+<Tabs>
+  <TabItem value="envvar" label="Environment Variable" default>
+
+  Applies to the current session only.
+
+  ```bash
+  # For terminal editors like vim or nano
+  export GOOSE_PROMPT_EDITOR=vim
+
+  # Or for GUI editors like VS Code (use --wait flag)
+  export GOOSE_PROMPT_EDITOR="code --wait"
+  ```
+
+  </TabItem>
+  <TabItem value="config" label="Config File">
+
+  Persists across all sessions unless overridden by the environment variable.
+  
+  1. Navigate to the goose [configuration file](/docs/guides/config-files). For example, navigate to `~/.config/goose/config.yaml` on macOS.
+  2. Add `GOOSE_PROMPT_EDITOR` and set it to your preferred editor:
+  
+  ```yaml
+  # For terminal editors like vim or nano
+  GOOSE_PROMPT_EDITOR: vim
+
+  # Or for GUI editors like VS Code (use --wait flag)
+  GOOSE_PROMPT_EDITOR: code --wait
+  ```
+
+  </TabItem>
+</Tabs>
+
+**Using GUI Editors:**
+
+GUI editors require a `--wait` or equivalent flag to ensure goose waits for you to finish editing before continuing. Without this flag, the editor opens but goose immediately proceeds as if you're done. Terminal editors like vim and nano don't need this flag.
+
+---
+
 ### Command History Search
 
 The `Ctrl+R` shortcut provides interactive search through your stored CLI [command history](/docs/guides/logs#command-history). This feature makes it easy to find and reuse recent commands without retyping them. When you type a search term, goose searches backwards through your history for matches.