From 24e85afd30fc0312b44fc65a5715bb04eea13d0d Mon Sep 17 00:00:00 2001
From: Emma Youndtsmith <90283317+emma-squared@users.noreply.github.com>
Date: Thu, 22 Jan 2026 10:00:17 -0600
Subject: [PATCH] Document tab completion (#6635)

---
 .../docs/guides/goose-cli-commands.md         | 84 +++++++++++++++++++
 .../docs/guides/terminal-integration.md       |  4 +
 2 files changed, 88 insertions(+)

diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md
index 399809c4..40841620 100644
--- a/documentation/docs/guides/goose-cli-commands.md
+++ b/documentation/docs/guides/goose-cli-commands.md
@@ -5,6 +5,9 @@ sidebar_label: CLI Commands
 toc_max_heading_level: 4
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. This guide covers all available CLI commands and interactive session features.
 
 ## Flag Naming Conventions
@@ -88,6 +91,87 @@ goose update --reconfigure
 
 ---
 
+#### completion
+Generate shell-specific scripts to enable tab completion of goose commands, subcommands, and options. The script is printed to stdout, so you need to redirect it to the appropriate location for your shell and then reload or source your shell configuration.
+
+Once installed, you can:
+- Press Tab to see available commands and subcommands
+- Complete command names and flags automatically
+- Discover options without checking `--help`
+
+**Arguments:**
+- **`<SHELL>`**: The shell to generate completions for. Supported shells: `bash`, `elvish`, `fish`, `powershell`, `zsh`
+
+**Usage:**
+```bash
+# Generate completion script for your shell (outputs to stdout)
+goose completion bash
+goose completion zsh
+goose completion fish
+```
+
+**Installation by Shell:**
+
+<Tabs groupId="shells">
+<TabItem value="zsh" label="Zsh" default>
+
+Add this line to your `~/.zshrc`:
+
+```bash
+eval "$(goose completion zsh)"
+```
+
+Then reload your shell:
+```bash
+source ~/.zshrc
+```
+
+</TabItem>
+<TabItem value="bash" label="Bash">
+
+Add this line to your `~/.bashrc` or `~/.bash_profile`:
+
+```bash
+eval "$(goose completion bash)"
+```
+
+Then reload your shell:
+```bash
+source ~/.bashrc
+```
+
+</TabItem>
+<TabItem value="fish" label="Fish">
+
+```bash
+goose completion fish > ~/.config/fish/completions/goose.fish
+```
+
+Then restart your terminal or run `exec fish`.
+
+</TabItem>
+<TabItem value="powershell" label="PowerShell">
+
+Add this line to your PowerShell profile:
+
+```powershell
+goose completion powershell | Out-String | Invoke-Expression
+```
+
+Then reload your profile:
+```powershell
+. $PROFILE
+```
+
+</TabItem>
+</Tabs>
+
+:::tip Testing
+After installing and reloading your shell, test completion by typing `goose ` and pressing Tab to see available commands, or `goose session --` and Tab to see available options.
+:::
+
+---
+
 ### Session Management
 
 :::info Session Storage Migration
diff --git a/documentation/docs/guides/terminal-integration.md b/documentation/docs/guides/terminal-integration.md
index f8023c52..2a6a5d72 100644
--- a/documentation/docs/guides/terminal-integration.md
+++ b/documentation/docs/guides/terminal-integration.md
@@ -156,6 +156,10 @@ Your terminal prompt now shows the context usage and model name (shortened for r
 ```bash
 ●●○○○ sonnet ~/projects $
 ```
+## Shell Completion for goose Commands
+
+`@goose` provides context-aware assistance based on your command history. To enable tab completion of goose CLI commands (like `goose session`, `goose run`, etc.), see the [shell completion documentation](/docs/guides/goose-cli-commands#completion).
+
 ## Troubleshooting
 
 **goose doesn't see recent commands:**