Skip to main content

​
Overview

The Forge ZSH plugin provides intelligent command transformation, file tagging, and conversation management directly in your terminal. It transforms :command syntax into Forge executions with automatic session management and context continuity.

​
Features

  • Smart command transformation with :command syntax
  • Agent selection with tab completion
  • Interactive file tagging using @[filename] syntax
  • Syntax highlighting for commands and files
  • Automatic conversation continuity across sessions
  • Interactive fuzzy finding for files and agents

​
Prerequisites

Before installing the plugin, ensure you have these tools:

fzf

Command-line fuzzy finder for interactive selections

fd

Fast file finder (alternative to find)

forge

The Forge CLI tool
1

Install Prerequisites

Install the required dependencies for your operating system:
brew install fzf fd
2

Automatic Setup

The easiest way to install the Forge ZSH plugin is using the automatic setup:
forge zsh setup
This command will:
  • Add the plugin configuration to your ~/.zshrc
  • Enable required ZSH plugins (zsh-autosuggestions, zsh-syntax-highlighting)
  • Load the Forge plugin and theme
  • Set up all necessary keybindings
The setup adds this block to your ~/.zshrc:
# !! Contents within this block are managed by 'forge zsh setup' !!
# !! Do not edit manually - changes will be overwritten !!

# Add required zsh plugins if not already present
if [[ ! " ${plugins[@]} " =~ " zsh-autosuggestions " ]]; then
    plugins+=(zsh-autosuggestions)
fi
if [[ ! " ${plugins[@]} " =~ " zsh-syntax-highlighting " ]]; then
    plugins+=(zsh-syntax-highlighting)
fi

# Load forge shell plugin (commands, completions, keybindings)
if [[ -z "$_FORGE_PLUGIN_LOADED" ]]; then
    eval "$(forge zsh plugin)"
fi

# Load forge shell theme (prompt with AI context)
if [[ -z "$_FORGE_THEME_LOADED" ]]; then
    eval "$(forge zsh theme)"
fi
3

Manual Setup (Alternative)

If you prefer manual installation, add this to your ~/.zshrc:
# Load Forge ZSH plugin
source /path/to/forge/shell-plugin/forge.plugin.zsh
Or if using Oh My Zsh, add forge to your plugins array:
plugins=(git zsh-autosuggestions zsh-syntax-highlighting forge)
4

Reload Shell

Apply the changes by reloading your shell:
source ~/.zshrc
Or simply open a new terminal window.
5

Verify Installation

Test the plugin is working:
: hello world
You should see Forge respond to your message. Try using tab completion:
:    # Press TAB to see available commands
@    # Press TAB to browse files

​
Basic Usage

​
Starting Conversations

Begin any command with : followed by your prompt: 
: What's the current time?
: Explain how Redis caching works

​
Using Specific Agents

Specify an agent by name after the colon: 
:sage How does caching work in this system?
:planner Create a deployment strategy
Tip: Type : and press TAB for interactive agent selection.

​
File Tagging

Tag files in your commands using @[filename] syntax: 
: Review this code @[src/main.rs]
: Debug the issue in @[logs/error.log] @[config/app.yml]
Tip: Type @ and press TAB to search and select files interactively.

​
Session Management

Clear context and start fresh:
:new  # or :n
This clears the conversation ID and resets the session state.
Browse and switch between conversations:
:conversation  # or :c for interactive list
:conversation <id>  # Switch to specific conversation
:conversation -  # Toggle between current and previous (like cd -)
Create a copy of an existing conversation:
:clone  # Interactive selection
:clone <conversation_id>  # Clone specific conversation
Display system and project information:
:info  # or :i

​
Configuration

Customize plugin behavior using environment variables in your ~/.zshrc: 
# Custom forge binary location
export FORGE_BIN="/path/to/custom/forge"

# Editor for :edit command
export FORGE_EDITOR="vim"

# Enable/disable automatic workspace sync
export FORGE_SYNC_ENABLED="true"

# Maximum diff size for commit message generation (bytes)
export FORGE_MAX_COMMIT_DIFF="100000"

# Currency symbol for cost display
export FORGE_CURRENCY_SYMBOL="$"

# Currency conversion rate
export FORGE_CURRENCY_CONVERSION_RATE="1.0"

# Enable Nerd Font icons (auto-detected by default)
export NERD_FONT="1"

​
Available Configuration Variables

VariableDefaultDescription
FORGE_BINforgePath to forge executable
FORGE_EDITOR$EDITOR or nanoEditor command for :edit
FORGE_SYNC_ENABLEDtrueEnable automatic workspace sync
FORGE_MAX_COMMIT_DIFF100000Max diff size for commits (bytes)
FORGE_CURRENCY_SYMBOL$Currency symbol for cost display
FORGE_CURRENCY_CONVERSION_RATE1.0Currency conversion rate
NERD_FONTauto-detectedEnable Nerd Font icons

​
Keyboard Shortcuts

The plugin registers these keybindings:
  • Tab (^I): Interactive completion for files and agents
  • Enter (^M, ^J): Transform and execute commands
  • Ctrl+C: Interrupt running Forge commands

​
Advanced Features

​
Syntax Highlighting

The plugin provides visual feedback:
  • Tagged files (@[filename]): Green bold
  • Agent commands (:agent): Yellow bold
  • Command text: White bold

​
Command History

All transformed commands are saved to ZSH history:
  • Navigate with arrow keys
  • Search with Ctrl+R
  • Reuse complex commands with file tags

​
Codebase Indexing

Sync your codebase for semantic search: 
:sync

​
Environment Diagnostics

Run comprehensive diagnostics: 
:doctor
This checks:
  • ZSH version and terminal info
  • Forge installation and version
  • Plugin and theme loading status
  • Dependencies (fzf, fd, bat)
  • Editor configuration
  • Nerd Font support

​
Troubleshooting

Ensure the plugin is sourced after Oh My Zsh initialization:
# In ~/.zshrc
source $ZSH/oh-my-zsh.sh  # Oh My Zsh first
eval "$(forge zsh plugin)"  # Then Forge plugin
Check that fzf is installed and in your PATH:
which fzf
which fd  # or fdfind on Ubuntu/Debian
Install zsh-syntax-highlighting:
# Oh My Zsh
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

# Then add to plugins in ~/.zshrc
plugins=(... zsh-syntax-highlighting)
Verify the plugin is loaded:
echo $_FORGE_PLUGIN_LOADED
# Should output: 1
If empty, the plugin isn’t loaded. Check your ~/.zshrc configuration.

​
Next Steps

ZSH Theme

Customize your prompt with AI context

Shell Completions

Set up completions for other shells

Configuration

Learn about Forge configuration options

Agents

Explore available agents and their capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us