Shell Integration

The Forge ZSH plugin transforms your shell into an AI-enhanced development environment. Execute Forge commands naturally with : prefix syntax, tag files with @[filename], and maintain conversation context across sessions.

Overview

The shell integration provides:

Smart command transformation - Convert :command syntax into Forge executions
File tagging - Reference files with @[filename] and interactive selection
Conversation continuity - Automatic session management across commands
Syntax highlighting - Visual feedback for commands and tagged files
Agent selection - Tab completion for available agents
Background syncing - Automatic workspace indexing

Quick Start

# Start a conversation
: What is the current time?

# Use specific agent
:sage How does caching work in this system?

# Tag files for context
: Review this code @[src/main.rs]

Installation

Prerequisites

Install required dependencies:

macOS (Homebrew)
Ubuntu/Debian
Arch Linux

brew install fzf fd

sudo apt install fzf fd-find

sudo pacman -S fzf fd

Plugin Setup

The plugin is automatically installed with Forge. Enable it in your ~/.zshrc:

# Load Forge plugin
source <(forge shell-init zsh)

Reload your shell:

source ~/.zshrc

Core Features

Conversation Commands

Start conversations with the : prefix:

: Explain how authentication works

Agent Selection

Specify agents by name with tab completion:

# Type and press TAB for completion
:sag<TAB>  # Completes to :sage
:mus<TAB>  # Completes to :muse

# Use agent for specialized tasks
:sage How does caching work?
:muse Create a deployment strategy
:planner Break down this feature into tasks

Type : followed by partial agent name and press TAB to see all available agents.

File Tagging

Reference files in your commands:

Manual Tagging
Interactive Selection

: Review this implementation @[src/auth.rs]
: Explain the config @[config.yaml]
: Compare @[old.rs] with @[new.rs]

# Type @ and press TAB for fuzzy finder
: Review this code @<TAB>

# Fuzzy search through your files
# Select with arrow keys and Enter

File tagging features:

Automatic context loading for referenced files
Multiple files in single command
Fuzzy finding with fzf integration
Syntax highlighting for tagged files (green bold)

Session Management

New Session
Switch Conversations
Clone Conversations

Start fresh conversation:

:new
# or shorthand
:n
# With immediate prompt
:new Explain the architecture

This will:

Clear current conversation context
Show banner with helpful info
Reset session state
Display confirmation with timestamp

Browse and switch conversations:

# Interactive list with preview
:conversation
# or shorthand
:c

# Switch to specific ID
:conversation abc123

# Toggle to previous conversation (like cd -)
:conversation -
:c -

Copy existing conversation:

# Interactive selection
:clone

# Clone specific conversation
:clone abc123

Useful for:

Creating backups before changes
Starting new branches from context
Experimenting with approaches

Workspace Operations

# Index current directory for semantic search
:sync

Syntax Highlighting

The plugin provides visual feedback:

Highlighting Legend

Tagged Files (@[filename]): Green bold
Agent Commands (:agent): Yellow bold for agent name
Command Text: White bold

Configuration

Customize plugin behavior with environment variables:

# Custom forge binary location
export FORGE_BIN="/path/to/custom/forge"

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

# Enable/disable automatic workspace sync (default: true)
export FORGE_SYNC_ENABLED=true

# Maximum diff size for commit messages in bytes (default: 100000)
export FORGE_MAX_COMMIT_DIFF=100000

# Currency display in theme
export FORGE_CURRENCY_SYMBOL="$"
export FORGE_CURRENCY_CONVERSION_RATE=1.0

# Nerd Font support (default: auto-detected)
export NERD_FONT=1  # or USE_NERD_FONT=1

Theme Customization

The Forge theme adds right-side prompt with agent and model info:

# Load theme in ~/.zshrc
source <(forge shell-init zsh)

Right prompt displays:

Active agent name
Current model
Token count
Cost estimation

Theme features:

Nerd Font icons (auto-detected)
Color-coded status
Real-time updates
Currency conversion

Advanced Features

Command History

All transformed commands save to ZSH history:

# Navigate with arrow keys
↑ : Review code @[src/main.rs]
↓

# Search with Ctrl+R
^R semantic
# Shows: : Explain semantic search implementation

Keyboard Shortcuts

Shortcut	Action
Tab	Interactive completion (files, agents)
Enter	Transform and execute `:commands`
Ctrl+C	Interrupt running Forge commands
Ctrl+R	Search command history
↑/↓	Navigate command history

Background Operations

The plugin handles background tasks:

Auto-sync: Periodic workspace indexing
Update checks: Notify about new Forge versions
Conversation saving: Automatic session persistence

# Control background sync
export FORGE_SYNC_ENABLED=false  # Disable auto-sync

Git Integration

Shell plugin integrates with git workflows:

# Generate commit messages
: Generate a commit message for staged changes

# Review PR changes
: Review the current branch changes

# Resolve conflicts
: Help me resolve git conflicts in @[src/app.rs]

See Git Operations for more details.

Diagnostics

Run :doctor for comprehensive environment check:

:doctor

Checks performed:

ZSH version and terminal info
Forge installation and version
Plugin and theme loading status
Completions availability
Dependencies (fzf, fd, bat)
ZSH plugins (autosuggestions, syntax-highlighting)
Editor configuration
PATH setup
Nerd Font support

Usage Examples

Basic Workflow

# Start your day
:new
: What tasks are in my TODO comments?

# Explore codebase
:sync
: Explain how authentication works

# Make changes
: Refactor the user service @[src/user.rs]

# Review changes
: Review my changes and suggest improvements

Multi-File Analysis

# Compare implementations
: Compare the error handling in @[api/v1.rs] and @[api/v2.rs]

# Debug across files
: Why is @[config.toml] not loading properly? Check @[src/config.rs]

# Generate tests
: Create unit tests for @[src/parser.rs] following patterns in @[tests/lexer_test.rs]

Session Management

# Work on feature
: Design the new caching system
: Implement the cache layer

# Switch to bug fix
:new
: Debug the authentication issue in @[src/auth.rs]

# Return to feature
:c -  # Toggle back to previous conversation

# Later, resume specific conversation
:c abc123

Troubleshooting

Commands not transforming

Verify plugin is loaded: type _forge_line_init
Check ZSH version: zsh --version (requires 5.0+)
Reload config: source ~/.zshrc
Look for errors in plugin loading

File completion not working

Install fzf: brew install fzf (or platform equivalent)
Install fd: brew install fd
Test fzf: echo test | fzf
Verify PATH includes fzf and fd

Conversation context lost

Check _FORGE_CONVERSATION_ID is set: echo $_FORGE_CONVERSATION_ID
Verify .forge directory exists in project
Don’t mix :new with :c - they manage context differently
Use :info to see current conversation status

Theme not showing

Verify theme loaded: echo $_FORGE_THEME_LOADED
Check RPROMPT: echo $RPROMPT
Enable prompt substitution: setopt PROMPT_SUBST
Reload shell config

Best Practices

Use :sync early - Index workspace when entering new projects
Leverage :new - Start fresh for unrelated tasks
Tag files liberally - Provide context with @[file] references
Use descriptive prompts - Clear instructions get better results
Switch agents - Use specialized agents for specific tasks
Review with :info - Check current session context
Run :doctor - Diagnose issues before reporting bugs

Custom Commands - Create reusable command workflows
Semantic Search - Power behind :sync and code exploration
Git Operations - Integrated git workflows
Multi-Agent Workflows - Orchestrate specialized agents

Getting Started

Core Concepts

Configuration

Providers

Features

Advanced Usage

Guides

Shell Integration

Overview

Quick Start

Installation

Prerequisites

Plugin Setup

Core Features

Conversation Commands

Agent Selection

File Tagging

Session Management

Workspace Operations

Syntax Highlighting

Highlighting Legend

Configuration

Theme Customization

Advanced Features

Command History

Keyboard Shortcuts

Background Operations

Git Integration

Diagnostics

Usage Examples

Basic Workflow

Multi-File Analysis

Session Management

Troubleshooting

Best Practices

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Providers

Features

Advanced Usage

Guides

​Overview

Quick Start

​Installation

​Prerequisites

​Plugin Setup

​Core Features

​Conversation Commands

​Agent Selection

​File Tagging

​Session Management

​Workspace Operations

​Syntax Highlighting

Highlighting Legend

​Configuration

​Theme Customization

​Advanced Features

​Command History

​Keyboard Shortcuts

​Background Operations

​Git Integration

​Diagnostics

​Usage Examples

​Basic Workflow

​Multi-File Analysis

​Session Management

​Troubleshooting

​Best Practices

​Related Features

Build docs developers (and LLMs) love

Overview

Installation

Prerequisites

Plugin Setup

Core Features

Conversation Commands

Agent Selection

File Tagging

Session Management

Workspace Operations

Syntax Highlighting

Configuration

Theme Customization

Advanced Features

Command History

Keyboard Shortcuts

Background Operations

Git Integration

Diagnostics

Usage Examples

Basic Workflow

Multi-File Analysis

Session Management

Troubleshooting

Best Practices

Related Features