Skip to main content

​
Overview

Forge provides intelligent tab completion for commands, options, and arguments across multiple shells. The completion system includes:
  • Command name completion
  • Option and flag completion
  • Argument value suggestions
  • Context-aware completions
  • Agent name completion
  • File path completion

​
Supported Shells

Forge provides native completion support for:
  • ZSH - Full integration with plugin
  • Bash - Standard completion script
  • Fish - Native Fish completions
  • PowerShell - Windows PowerShell support

​
Installation

​
ZSH

1

Automatic Setup

The completions are automatically installed with the ZSH plugin:
forge zsh setup
This includes:
  • Standard Forge command completions
  • Custom :command completion widget
  • File tagging completion with @[file] syntax
  • Agent name completion
2

Manual Setup

If you need to set up completions separately:
# Generate completion script
forge completions zsh > ~/.zsh/completions/_forge

# Add to fpath in ~/.zshrc (before compinit)
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit
3

Verify Installation

Test completions:
forge <TAB>  # Shows available commands
forge config <TAB>  # Shows config subcommands

​
Bash

1

Generate Completion Script

forge completions bash > ~/.forge-completion.bash
2

Load Completions

Add to your ~/.bashrc:
# Forge completions
if [ -f ~/.forge-completion.bash ]; then
    source ~/.forge-completion.bash
fi
3

System-Wide Installation (Optional)

For system-wide completions:
# macOS
forge completions bash > /usr/local/etc/bash_completion.d/forge

# Linux
sudo forge completions bash > /usr/share/bash-completion/completions/forge
4

Reload Shell

source ~/.bashrc

​
Fish

1

Generate Completion Script

forge completions fish > ~/.config/fish/completions/forge.fish
2

Verify Installation

Fish will automatically load completions from the completions directory. Test with:
forge <TAB>

​
PowerShell

1

Generate Completion Script

forge completions powershell > $PROFILE\..\Completions\forge.ps1
2

Load Completions

Add to your PowerShell profile:
# Forge completions
. $PSScriptRoot\Completions\forge.ps1
3

Reload Profile

. $PROFILE

​
ZSH Advanced Completions

The Forge ZSH plugin includes enhanced completion features beyond standard command completion.

​
Custom Completion Widget

The plugin implements a custom completion widget that handles: 
# File and directory completion with @
: Review this file @<TAB>
# Opens fzf with file preview

# Agent completion with :
:<TAB>
# Shows list of available agents

# Filtered completion
:sage<TAB>
# Pre-filters to agents matching "sage"

​
Implementation Details

From shell-plugin/lib/completion.zsh:5: 
function forge-completion() {
    local current_word="${LBUFFER##* }"
    
    # Handle @ completion (files and directories)
    if [[ "$current_word" =~ ^@.*$ ]]; then
        local filter_text="${current_word#@}"
        local selected
        local fzf_args=(
            --preview="if [ -d {} ]; then ls -la --color=always {}; 
                       else bat --color=always --style=numbers {}; fi"
        )
        
        local file_list=$(fd --type f --type d --hidden --exclude .git)
        selected=$(echo "$file_list" | fzf --query "$filter_text" "${fzf_args[@]}")
        
        if [[ -n "$selected" ]]; then
            selected="@[${selected}]"
            LBUFFER="${LBUFFER%$current_word}"
            BUFFER="${LBUFFER}${selected}${RBUFFER}"
        fi
    fi
    
    # Handle :command completion
    if [[ "${LBUFFER}" =~ "^:([a-zA-Z][a-zA-Z0-9_-]*)?$" ]]; then
        local filter_text="${LBUFFER#:}"
        local commands_list=$(forge commands list)
        local selected=$(echo "$commands_list" | fzf --query "$filter_text")
        
        if [[ -n "$selected" ]]; then
            local command_name="${selected%% *}"
            BUFFER=":$command_name "
        fi
    fi
}

​
Keybindings

From shell-plugin/lib/bindings.zsh:31: 
# Register completion widget
zle -N forge-completion

# Bind Tab to custom completion
bindkey '^I' forge-completion

​
Available Completions

​
Command Completions

forge <TAB>
# Shows: config, agent, conversation, auth, sync, version, help

forge config <TAB>
# Shows: get, set, list, edit, path

forge agent <TAB>
# Shows: list, info, create, edit, delete

​
Option Completions

forge --<TAB>
# Shows: --help, --version, --config, --quiet, --verbose

forge agent list --<TAB>
# Shows: --format, --sort, --filter

​
Argument Completions

forge config get <TAB>
# Shows available configuration keys

forge agent info <TAB>
# Shows available agent names

​
Completion Configuration

​
ZSH Completion Styles

Customize completion behavior in your ~/.zshrc: 
# Case-insensitive completion
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'

# Use menu selection
zstyle ':completion:*' menu select

# Group results by category
zstyle ':completion:*' group-name ''

# Show descriptions for options
zstyle ':completion:*' verbose yes

# Color completion menu
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"

​
File Completion Configuration

Customize file completion behavior: 
# Use fd instead of find (faster)
export _FORGE_FD_CMD="fd"

# Use bat for file previews
export _FORGE_CAT_CMD="bat --color=always --style=numbers"

# Customize preview window
export _FORGE_PREVIEW_WINDOW="--preview-window=bottom:75%:wrap"

​
Troubleshooting

​
ZSH

Ensure compinit is called after adding to fpath:
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit
Clear completion cache:
rm -f ~/.zcompdump*
compinit

​
Bash

Verify bash-completion is installed:
# macOS
brew install bash-completion

# Linux
sudo apt install bash-completion

​
Check Dependencies

Ensure fast tools are installed:
# Use fd instead of find
brew install fd  # or: sudo apt install fd-find

# Use bat instead of cat
brew install bat  # or: sudo apt install bat

​
Disable Preview

If previews are slow, disable them:
export _FORGE_PREVIEW_WINDOW="--preview-window=hidden"

​
ZSH Plugin

Verify the completion widget is registered:
zle -l | grep forge-completion
# Should show: forge-completion
Check keybinding:
bindkey '^I'
# Should show: "^I" forge-completion

​
Install Required Tools

# Install fd
brew install fd  # macOS
sudo apt install fd-find  # Ubuntu/Debian

# Install bat
brew install bat  # macOS
sudo apt install bat  # Ubuntu/Debian

​
Check Configuration

echo $_FORGE_FD_CMD
echo $_FORGE_CAT_CMD

​
Examples

​
Basic Command Completion

# Complete command names
$ forge co<TAB>
config  conversation

# Complete subcommands
$ forge config <TAB>
get  set  list  edit  path

# Complete options
$ forge --<TAB>
--help  --version  --config  --quiet  --verbose

​
ZSH Plugin Advanced Completion

# Agent completion with fuzzy matching
$ :sag<TAB>
# Opens fzf with agents matching "sag" highlighted

# File completion with preview
$ : Review @<TAB>
# Opens fzf with file browser and preview

# Multiple file tags
$ : Compare @[src/main.rs] and @<TAB>
# Completes second file

​
Filtered Completion

# Type prefix before TAB for filtered results
$ forge agent li<TAB>
list  # Only shows commands starting with "li"

$ :plan<TAB>
planner  # Only shows agents starting with "plan"

​
Next Steps

ZSH Plugin

Full ZSH plugin with advanced features

ZSH Theme

Enhance your prompt with AI context

VS Code Integration

Use Forge in VS Code

Configuration

Configure Forge settings

Build docs developers (and LLMs) love

Get started for freeTalk to us