Smart shell completions for opencode CLI
Intelligent tab completion for sessions, models, agents, and all subcommands

Why? • Features • Installation • Usage • Configuration

Zsh completions for opencode, an AI-powered CLI tool.

The built-in opencode completion zsh only provides subcommand names (e.g., mcp, debug, providers), but no completion for:

• Flags/Options — typing opencode -<TAB> or opencode --<TAB> shows nothing
• Argument values — opencode -s <TAB> or opencode -m <TAB> has no completion

• Complete option completion for all opencode flags (-m, -c, -s, --model, --session, --agent, etc.)
• Subcommand completion with descriptions for all commands:
  • completion, mcp, debug, providers, agent, models
  • export, import, session, github, pr, run, serve, upgrade
  • and more...
• Smart session selection with opencode -s <TAB> — shows recent sessions with titles, directories, and timestamps
• Model completion — caches and completes available AI models
• Agent completion — suggests available agents (--agent <TAB>)
• MCP server management — completion for mcp add/list/auth/logout/debug
• Provider management — completion for providers list/login/logout
• Cached completions for sessions and models (auto-invalidated when data changes)
• Configurable session limit — control how many recent sessions to show (default: 30)

zinit ice as"completion"
zinit snippet https://raw.githubusercontent.com/PEMessage/opencode-zsh-completion/main/_opencode

zinit ice as"completion" blockf
zinit light PEMessage/opencode-zsh-completion

Clone this repository into your custom plugins directory:

git clone https://github.com/PEMessage/opencode-zsh-completion.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/opencode

Then add opencode to your plugins array in ~/.zshrc:

plugins=(... opencode)

You can manually install the completion file to any directory in your $fpath.

# Create completions directory if it doesn't exist
mkdir -p ~/.zsh/completions

# Download the completion file
curl -L https://raw.githubusercontent.com/PEMessage/opencode-zsh-completion/main/_opencode -o ~/.zsh/completions/_opencode

# Add to fpath in your ~/.zshrc (before calling compinit)
echo 'fpath+=(~/.zsh/completions)' >> ~/.zshrc

# Download to system completions directory (may require sudo)
# Common paths:
# - macOS (Homebrew): /usr/local/share/zsh/site-functions or /opt/homebrew/share/zsh/site-functions
# - Linux: /usr/share/zsh/site-functions or /usr/local/share/zsh/site-functions

sudo curl -L https://raw.githubusercontent.com/PEMessage/opencode-zsh-completion/main/_opencode \
  -o /usr/local/share/zsh/site-functions/_opencode

# Clone the repository
git clone https://github.com/PEMessage/opencode-zsh-completion.git ~/opencode-zsh-completion

# Add to fpath in ~/.zshrc
echo 'fpath+=(~/opencode-zsh-completion)' >> ~/.zshrc

After installation, reload your shell configuration or run:

# Remove cached function (if any) and reload
unfunction _opencode 2>/dev/null
autoload -U _opencode
# Reinitialize completions
compinit

Or simply open a new terminal window.

After installation, use tab completion with the opencode command:

# Complete global options
opencode --<TAB>

# Select a model
opencode -m <TAB>

# Select from recent sessions
opencode -s <TAB>

# List subcommands
opencode <TAB>

# Complete subcommand options
opencode mcp <TAB>
opencode debug <TAB>
opencode providers <TAB>

# Select provider for models command
opencode models <TAB>

# Complete MCP server names
opencode mcp auth <TAB>

# Export a session
opencode export <TAB>

You can customize the behavior of the completions using zstyle.

The maximum number of recent sessions shown in the completion list (default: 30):

# Show up to 50 recent sessions
zstyle ':completion:*:opencode:*' session-limit 50

# Show all sessions (no limit)
zstyle ':completion:*:opencode:*' session-limit 9999

The location where session data is cached (auto-configured by default):

zstyle ':completion:*:opencode:*' cache-path "${ZSH_CACHE_DIR:-$HOME/.cache/zsh}/opencode"

When extending this completion, use this prompt to guide AI assistants:

Please add more opencode completions to _opencode.

Requirements:
- 'opencode -s' (session completion) is already stable — DO NOT break it
- Load the smux skill to test completions in a background tmux session
- Environment is already set up; current directory is in $fpath

Feed AGENTS.md to your AI assistant — it contains everything needed to write, debug, or extend zsh completions.

"I took your AGENTS.md and the ai almost one-shot it and for the first time I actually get what is happening on the zsh completion itself." — Gerson Gallo, opencode-zsh-completion#1

GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE file for details.