diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 6336474fb65c..da50b4cb6e93 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -283,6 +283,33 @@ export ALPHA_FEATURES=true
 ALPHA_FEATURES=true goose session
 ```
 
+## Variables Controlled by Goose
+
+These variables are automatically set by Goose during command execution.
+
+| Variable | Purpose | Values | Default |
+|----------|---------|---------|---------|
+| `GOOSE_TERMINAL` | Indicates that a command is being executed by Goose, enables customizing shell behavior | "1" when set | Unset |
+
+### Customizing Shell Behavior
+
+Sometimes you want Goose to use different commands or have different shell behavior than your normal terminal usage. For example, you might want Goose to use a different tool, or prevent Goose from running long-running development servers that could hang the AI agent. This is most useful when using Goose CLI, where shell commands are executed directly in your terminal environment.
+
+**How it works:**
+1. When Goose runs commands, `GOOSE_TERMINAL` is automatically set to "1"
+2. Your shell configuration can detect this and direct Goose to change its default behavior while keeping your normal terminal usage unchanged
+
+**Example:**
+
+```bash
+# In your ~/.bashrc or ~/.zshrc
+
+# Guide Goose toward better tool choices
+if [[ -n "$GOOSE_TERMINAL" ]]; then
+  alias find="echo 'Use rg instead: rg --files | rg <pattern> for filenames, or rg <pattern> for content search'"
+fi
+```
+
 ## Notes
 
 - Environment variables take precedence over configuration files.
diff --git a/documentation/docs/troubleshooting.md b/documentation/docs/troubleshooting.md
index cad17f66be09..5df20974b3f3 100644
--- a/documentation/docs/troubleshooting.md
+++ b/documentation/docs/troubleshooting.md
@@ -30,6 +30,14 @@ For particularly large or complex tasks, consider breaking them into smaller ses
 
 ---
 
+### Preventing Long-Running Commands
+
+If you use Goose CLI and work with web development projects, you may encounter commands that cause Goose to hang indefinitely. Commands like `npm run dev`, `python -m http.server`, or `webpack serve` start development servers that never exit on their own.
+
+You can prevent these issues by customizing your shell to handle these commands differently when Goose runs them. See [Customizing Shell Behavior](/docs/guides/environment-variables#customizing-shell-behavior) for details on using the `GOOSE_TERMINAL` environment variable.
+
+---
+
 ### Context Length Exceeded Error
 
 This error occurs when the input provided to Goose exceeds the maximum token limit of the LLM being used. To resolve this, try breaking down your input into smaller parts. You can also use `.goosehints` as a way to provide goose with detailed context. Refer to the [Using Goosehints Guide][goosehints] for more information.