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

Advanced Features (Require fd and fzf)

• Fuzzy File Finding: Quick file tagging with @filename<Tab>
• Fuzzy Agent Selection: Press Tab after : to get a searchable list of available agents

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

Installation

1

Install Optional File Finding Tools (Recommended)

For fuzzy file finding and agent selection, install fd and fzf:

# macOS
brew install fd fzf

# Ubuntu/Debian
sudo apt install fd-find fzf

# Arch Linux
sudo pacman -S fd fzf

Other platforms: See our fd and fzf Installation Guide

Optional but Recommended

ZSH Support works without these tools, but you'll need to type full file paths instead of using fuzzy finding. You can install them later if you skip this step.

2

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.

3

Configure ZSH Integration

Add Forge ZSH integration to your shell configuration:

If you installed Forge globally:

# Add to ~/.zshrc
export FORGEBIN=forge
source <($FORGEBIN generate-zsh-prompt)

If you're using npx:

# Add to ~/.zshrc
export FORGEBIN="npx forgecode"
source <($FORGEBIN generate-zsh-prompt)

Then reload your shell:

source ~/.zshrc

4

Verify Installation

Test that everything works:

# Basic prompt - should show syntax highlighting
: hello world

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

You should see 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 FORGEBIN is set correctly: echo $FORGEBIN
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 1 or our fd and fzf 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 you're using ZSH (not bash): echo $SHELL
2. Check that your terminal supports colors: echo $TERM
3. Try reloading: source ~/.zshrc

No agent has subscribed to the event

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