ZSH Support: Keep Your Shell Aliases While Getting AI Help

Stop losing access to your carefully crafted ZSH aliases, custom functions, and shell tooling every time you need AI assistance. The : sentinel character lets you stay in your native shell while getting help from Forge.

The Problem: Forge's interactive mode creates a separate environment where your ZSH aliases, custom functions, and shell setup don't work. You're forced to choose between AI assistance or your productivity tools.

The Solution: Use : to send prompts to Forge while staying in your native ZSH session:

# Your zsh plugins work normally
gst
gcam "fix: resolve memory leak"

# But you can also get AI help instantly
: analyze the memory usage patterns in @src/server.rs

# Run your custom tools as part of your investigation
ps aux | grep server
htop -p $(pgrep server)

# Continue with full context about the analysis
: now optimize the memory allocations you identified in the server struct

The Result: Maintain context across both AI tasks and your custom shell operations, without switching environments or losing your workflow.

What You Get

Core Features (Work Immediately After Installation)

• Native Shell Integration: Use : to access Forge AI while preserving all your ZSH aliases, functions, PATH modifications, and custom tooling
• Intelligent Context Management: Maintain conversation context across prompts with :reset control and agent targeting like :sage or :muse
• Syntax Highlighting: Color-coded prompts optimized for dark terminals (requires zsh-syntax-highlighting plugin)

Advanced Features (Require fd, fzf, and bat)

• Fuzzy File Finding: Quick file tagging with @filename<Tab> (requires fd + fzf)
• Fuzzy Agent Selection: Press Tab after : to get a searchable list of available agents (requires fzf)
• Syntax-Highlighted Previews: See colorized code when selecting files (requires bat)

These features are optional but provide a significantly better experience. Installation instructions are in Step 3 below.

Installation

1

Install zsh-syntax-highlighting Plugin (Required)

The syntax highlighting feature requires the zsh-syntax-highlighting plugin to be installed and loaded in your ZSH configuration.

Option 1: Package Manager (Recommended)

# macOS
brew install zsh-syntax-highlighting

# Ubuntu/Debian
sudo apt install zsh-syntax-highlighting

# Arch Linux
sudo pacman -S zsh-syntax-highlighting

# Fedora
sudo dnf install zsh-syntax-highlighting

Option 2: Oh My Zsh

# Clone to Oh My Zsh plugins directory
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

# Add to plugins in ~/.zshrc (must be last plugin)
plugins=(... zsh-syntax-highlighting)

Option 3: Manual Installation

# Clone the repository
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git

# Add to ~/.zshrc (must be at the end)
echo "source ${(q-)PWD}/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc

Important Loading Order

zsh-syntax-highlighting must be sourced LAST in your .zshrc file, after all other plugins and the Forge integration. This ensures proper highlighting of Forge prompts.

2

Install zsh-autocomplete Plugin (Optional)

The zsh-autocomplete plugin provides real-time autocomplete suggestions as you type, making it easier to repeat previous Forge commands.

Option 1: Package Manager (Recommended)

# macOS
brew install zsh-autocomplete

# Arch Linux
sudo pacman -S zsh-autocomplete

# Gentoo (Portage)
sudo emerge app-shells/zsh-autocomplete

note

After installing via package manager, you still need to source the plugin in your ~/.zshrc:

source /path/to/zsh-autocomplete/zsh-autocomplete.plugin.zsh

The exact path may vary depending on your package manager and system.

Option 2: Oh My Zsh

# Clone to Oh My Zsh plugins directory
git clone --depth 1 https://github.com/marlonrichert/zsh-autocomplete.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autocomplete

# Add to plugins in ~/.zshrc (before zsh-syntax-highlighting)
plugins=(... zsh-autocomplete zsh-syntax-highlighting)

tip

The --depth 1 flag creates a shallow clone, downloading only the latest commit instead of the entire git history. This makes the installation faster and saves disk space. It's perfectly fine for plugin usage since you don't need the full repository history.

Option 3: Manual Installation

# Clone the repository
git clone --depth 1 https://github.com/marlonrichert/zsh-autocomplete.git ~/.zsh/zsh-autocomplete

# Add to ~/.zshrc (before zsh-syntax-highlighting)
source ~/.zsh/zsh-autocomplete/zsh-autocomplete.plugin.zsh

Optional Enhancement

This plugin is optional but highly recommended. It will show autocomplete suggestions as you type, making it easier to reuse previous Forge prompts and commands.

3

Install Optional File Finding Tools (Recommended)

These tools enhance the ZSH integration with fuzzy finding and better previews:

What each tool does:

• fd: Fast file search - enables finding files by partial name
• fzf: Fuzzy finder UI - provides the interactive selection interface
• bat: Syntax highlighter - shows colorized code previews in the fuzzy finder

Install all three:

# macOS
brew install fd fzf bat

# Ubuntu/Debian
sudo apt install fd-find fzf bat

# Arch Linux
sudo pacman -S fd fzf bat

Other platforms: See our ZSH Dependencies Installation Guide

Optional but Recommended

These tools enable fuzzy file finding with @filename<Tab>, agent selection with Tab after :, and syntax-highlighted file previews. You can install them later if you skip this step.

4

Install Forge

Install and set up Forge following the main installation guide.

Choose either global installation via npm or npx usage. Remember your choice for the next step.

5

Configure ZSH Integration

Add Forge ZSH integration to your shell configuration:

If you installed Forge globally:

# Add to ~/.zshrc
export FORGE_BIN=forge
source <($FORGE_BIN extension zsh)

If you're using npx:

# Add to ~/.zshrc
export FORGE_BIN="npx forgecode"
source <($FORGE_BIN extension zsh)

Critical Loading Order

The Forge source line must come BEFORE the zsh-syntax-highlighting source line in your .zshrc file. The correct order is:

1. All other plugins
2. Forge integration (source <($FORGE_BIN extension zsh))
3. zsh-syntax-highlighting (last)

Then reload your shell:

source ~/.zshrc

6

Verify Installation

Test that everything works:

# Basic prompt - should show syntax highlighting
: hello world

# Test file tagging (requires fd/fzf from Step 3)
: help me with @README<Tab>

You should see color-coded syntax highlighting and successful command execution.

Quick Start

# Basic prompt
: hello, can you help me debug this shell script?

# Agent-specific prompt
:sage what are the performance implications of this database query?

# Continue the conversation with context
: what optimizations would you recommend?

# Reset when switching to a different task
:reset

# Fuzzy agent selection (requires fd/fzf)
:<Tab>

# Fuzzy file finding (requires fd/fzf)
: explain the config in @package<Tab>

Usage

Basic Prompt Execution

Send prompts to Forge using the : prefix:

: explain this error message
: refactor this function to be more readable
: add error handling to the database connection

The prompt goes to your last used agent, defaulting to the main Forge agent if this is your first interaction.

Agent Selection

Target specific agents by including the agent name after the colon:

:sage explain the algorithm complexity and performance characteristics
:muse create a plan for implementing user authentication with OAuth
:forge refactor this function to be more maintainable

Agent Selection Rules:

• No agent specified (:) = uses the previous agent, or Forge if first interaction
• Agent specified (:sage) = switches to that agent and makes it the new default
• :reset = clears conversation context but keeps the current agent selection

Example workflow:

# First interaction - goes to default Forge agent
: help me debug this performance issue

# Continues with same agent
: what tools should I use to profile memory usage?

# Switch to sage for analysis
:sage analyze the complexity of this sorting algorithm

# Continues with sage
: what are the potential edge cases?

# Clear context when switching tasks
:reset
:forge implement the user login validation function

Press Tab after : for fuzzy agent selection (requires fd/fzf).

Agent Names

• forge - Main agent for coding, refactoring, debugging, and general development tasks
• muse - Planning and strategy for complex features
• sage - Questions and analysis without making code modifications

Run /agents in a Forge session to see your configured agents.

Context Management

ZSH Support maintains conversation context across prompts. Use :reset to clear context when switching to a new task:

# Working on database optimization
: analyze the slow queries in @database/analytics.sql

# Run shell commands for investigation
ps aux | grep postgres
htop -p $(pgrep postgres)

# Continue the conversation - agent remembers context
: based on what I found, the CPU usage is high, what should I check next?

# Switch to a completely different task
:reset

# Start fresh - no database context carried over
: help me set up CI/CD pipeline for this project

The agent remembers previous conversations within the same session, letting you work naturally with a mix of shell commands and AI assistance.

File Tagging (requires fd/fzf)

Tag files in your prompts using @ followed by a partial filename and Tab:

: review the changes in @package<Tab>
: explain the logic in @src/utils/helper<Tab>
: optimize the performance of @database/queries<Tab>

When you press Tab:

1. A fuzzy finder window opens
2. Type to filter files by name
3. Use arrow keys to navigate
4. Press Enter to select the file
5. The full file path is inserted into your prompt

The fuzzy finder searches through your project files and respects your .gitignore automatically.

Troubleshooting

Command Not Found

If : command not found appears:

1. Ensure you added the source line to ~/.zshrc
2. Reload your shell: source ~/.zshrc or exec zsh
3. Verify FORGE_BIN is set correctly: echo $FORGE_BIN
4. Check the path matches your installation method (global vs npx)

File Tagging Doesn't Work

If @filename<Tab> does nothing, fd and fzf are not installed. See Step 3 or our ZSH Dependencies Installation Guide.

You can still use full file paths manually:

: review the changes in @[src/components/Header.tsx]

Syntax Highlighting Problems

If highlighting doesn't appear:

1. Ensure zsh-syntax-highlighting is installed:

   # Check if installed via package manager
   brew list | grep zsh-syntax-highlighting # macOS
   dpkg -l | grep zsh-syntax-highlighting   # Ubuntu/Debian

2. Verify correct loading order in ~/.zshrc:

   • Forge integration must be loaded BEFORE zsh-syntax-highlighting
   • zsh-syntax-highlighting must be the LAST plugin sourced

3. Check if zsh-syntax-highlighting is loaded:

   echo $ZSH_HIGHLIGHT_VERSION

   If this returns empty, the plugin isn't loaded.

4. Ensure you're using ZSH (not bash): echo $SHELL

5. Check that your terminal supports colors: echo $TERM

6. Try reloading: source ~/.zshrc

7. For manual installations, verify the path is correct:

   ls -la /path/to/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Agent Not Found Errors

If you get "agent not found" errors:

1. Check your available agents by running /agents in a Forge session
2. Verify agent name spelling (case-sensitive)
3. Test with a basic command: : list my current working directory and git status