From 75f37360a02634b84c4c7a8eaeecb00327490c41 Mon Sep 17 00:00:00 2001
From: Emma Youndtsmith <eyoundtsmith@squareup.com>
Date: Thu, 22 Jan 2026 09:24:34 -0600
Subject: [PATCH] Document tab completion

---
 .../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 399809c494d1..40841620d143 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 f8023c524807..2a6a5d726f38 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:**