diff --git a/README.md b/README.md
index 7bbd125a..5a93d72a 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,7 @@ A personal task management system with a beautiful terminal UI, SQLite storage,
 - **Fully Scriptable CLI** - 100% of Task You is controllable via CLI—agents can manage tasks, read executor output, and send input to running executors programmatically (see [Full CLI Scriptability](#full-cli-scriptability))
 - **SSH Access** - Run as an SSH server to access your tasks from anywhere (see [SSH Access & Deployment](#ssh-access--deployment))
 - **Project Context Caching** - AI agents automatically cache codebase exploration results and reuse them across tasks, eliminating redundant exploration (see [Project Context](#project-context))
+- **Shell Completion** - Tab completion for commands, task IDs, projects, statuses, and flags in bash, zsh, fish, and PowerShell (see [Shell Completion](#shell-completion))
 
 ## Project Context
 
@@ -694,6 +695,53 @@ npm install
 cp .env.example .env.local
 ```
 
+## Shell Completion
+
+TaskYou supports tab completion for all CLI commands, subcommands, flags, and dynamic values (task IDs, project names, statuses, etc.).
+
+### Setup
+
+**Zsh** (macOS default):
+```bash
+# Enable completion if not already done:
+echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+# Generate and install the completion script:
+ty completion zsh > "${fpath[1]}/_ty"
+
+# Restart your shell or run:
+source ~/.zshrc
+```
+
+**Bash**:
+```bash
+# Linux:
+ty completion bash > /etc/bash_completion.d/ty
+
+# macOS (with Homebrew):
+ty completion bash > $(brew --prefix)/etc/bash_completion.d/ty
+```
+
+**Fish**:
+```bash
+ty completion fish > ~/.config/fish/completions/ty.fish
+```
+
+**PowerShell**:
+```powershell
+ty completion powershell >> $PROFILE
+```
+
+### What completes
+
+- **Subcommands** — `ty <TAB>` shows all available commands
+- **Task IDs** — `ty show <TAB>` lists tasks with their status and title
+- **Statuses** — `ty status 42 <TAB>` suggests backlog, queued, processing, etc.
+- **Projects** — `ty move 42 <TAB>` and `--project <TAB>` complete project names
+- **Task types** — `--type <TAB>` completes from your configured task types
+- **Executors** — `--executor <TAB>` suggests claude, codex, gemini, etc.
+- **Settings** — `ty settings set <TAB>` shows available setting keys
+
 ## SSH Access & Deployment
 
 Task You can run as an SSH server, allowing you to access your task board from anywhere.