ZSH Theme Setup

Overview

The Forge ZSH theme adds AI context to your prompt, displaying active agent information, model details, and token usage directly in your terminal. It integrates seamlessly with your existing ZSH theme by augmenting the right prompt (RPROMPT).

Features

Active agent and model display
Real-time token count tracking
Cost estimation per conversation
Nerd Font icon support (auto-detected)
Currency conversion support
Non-intrusive right-prompt integration
High-performance prompt rendering

Installation

Automatic Setup

The theme is automatically installed when you set up the Forge ZSH plugin:

forge zsh setup

This adds the theme loader to your ~/.zshrc:

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

Manual Setup (Alternative)

To manually load just the theme, add this to your ~/.zshrc:

# Load Forge theme
source /path/to/forge/shell-plugin/forge.theme.zsh

Or generate the theme dynamically:

eval "$(forge zsh theme)"

Reload Shell

Apply the changes:

source ~/.zshrc

Verify Theme

Start a conversation to see the theme in action:

: hello

You should see AI context information in your right prompt.

Theme Components

The theme displays information in your right prompt (RPROMPT):

┌─[user@hostname] ~/project
└─❯                                    🤖 agent-name • gpt-4 • 1.2K tokens • $0.05

Information Display

Agent Name: Current active agent (if any)
Model: AI model being used
Token Count: Total tokens in conversation
Cost: Estimated cost in your configured currency
Icons: Nerd Font icons (when supported)

Configuration

Customize the theme using environment variables:

Currency Settings

# Set currency symbol (default: $)
export FORGE_CURRENCY_SYMBOL="€"

# Set conversion rate from USD (default: 1.0)
export FORGE_CURRENCY_CONVERSION_RATE="0.85"

Font Settings

# Enable/disable Nerd Font icons
export NERD_FONT="1"  # Enable
export NERD_FONT="0"  # Disable

# Alternative variable name
export USE_NERD_FONT="true"  # Enable
export USE_NERD_FONT="false"  # Disable

Complete Configuration Example

~/.zshrc

# Forge Theme Configuration
export FORGE_CURRENCY_SYMBOL="£"
export FORGE_CURRENCY_CONVERSION_RATE="0.79"
export NERD_FONT="1"

# Load Forge theme
eval "$(forge zsh theme)"

Theme Implementation

The theme is implemented as a single function that queries Forge for prompt information:

# Enable prompt substitution
setopt PROMPT_SUBST

# Get AI context from Forge
function _forge_prompt_info() {
    local forge_bin="${_FORGE_BIN:-${FORGE_BIN:-forge}}"
    
    # Get fully formatted prompt from forge
    _FORGE_CONVERSATION_ID=$_FORGE_CONVERSATION_ID \
      _FORGE_ACTIVE_AGENT=$_FORGE_ACTIVE_AGENT \
      "$forge_bin" zsh rprompt
}

# Set right prompt
RPROMPT='$(_forge_prompt_info)'"${RPROMPT:+ ${RPROMPT}}"

Performance Optimization

The theme is designed for minimal performance impact:

Single command execution per prompt
Fully formatted output from Rust (no shell string manipulation)
Cached conversation state
Fast binary execution (under 60ms)

Integration with Existing Themes

Oh My Zsh Themes

The Forge theme works alongside Oh My Zsh themes:

~/.zshrc

# Oh My Zsh configuration
ZSH_THEME="robbyrussell"  # or any theme

source $ZSH/oh-my-zsh.sh

# Load Forge theme (appends to RPROMPT)
eval "$(forge zsh theme)"

Powerlevel10k

For Powerlevel10k users, the Forge theme appends to the right prompt:

~/.zshrc

# Powerlevel10k initialization
source ~/powerlevel10k/powerlevel10k.zsh-theme

# Forge theme adds AI context to right prompt
eval "$(forge zsh theme)"

Starship

If using Starship, you can still use the Forge theme:

~/.zshrc

# Starship initialization
eval "$(starship init zsh)"

# Forge theme provides RPROMPT (Starship uses PROMPT)
eval "$(forge zsh theme)"

Pure Prompt

The theme works with Pure and other async prompts:

~/.zshrc

# Pure prompt
autoload -U promptinit; promptinit
prompt pure

# Forge theme on right side
eval "$(forge zsh theme)"

Customizing Display

The theme output is controlled by the Forge CLI. You can influence what’s displayed through configuration:

Show/Hide Elements

# The theme respects your Forge configuration
# Edit ~/.config/forge/config.yaml to customize display preferences

Custom Formatting

The theme uses Forge’s internal formatting, which includes:

ANSI color codes for styling
Icon rendering based on terminal capabilities
Automatic truncation for long values
Responsive width adjustment

Nerd Font Icons

Automatic Detection

The theme automatically detects Nerd Font support by checking:

NERD_FONT environment variable
USE_NERD_FONT environment variable
Terminal font capabilities
Common terminal emulators known to support Nerd Fonts

Supported Icons

When Nerd Fonts are available:

🤖 Robot icon for agents
💬 Chat bubble for conversations
📊 Chart for token usage
💵 Money bag for costs
🔧 Wrench for system operations

Fallback Display

Without Nerd Fonts, the theme uses:

Text labels (Agent:, Model:, Tokens:)
ASCII symbols
Plain text formatting

Troubleshooting

Theme not showing

Verify prompt substitution is enabled:

setopt PROMPT_SUBST

Check if theme is loaded:

echo $_FORGE_THEME_LOADED
# Should output: 1

Icons not displaying

Install a Nerd Font and configure your terminal:

# macOS with Homebrew
brew tap homebrew/cask-fonts
brew install --cask font-hack-nerd-font

# Then set your terminal to use the font

Or disable icon display:

export NERD_FONT="0"

Slow prompt rendering

Check Forge CLI performance:

time forge zsh rprompt

Should complete in under 60ms. If slower, check:

Disk I/O performance
Forge configuration file size
System resource usage

Prompt conflicts with existing theme

The Forge theme appends to RPROMPT. If you have conflicts:

# Manually set order
RPROMPT='$(_forge_prompt_info) ${RPROMPT}'

Or isolate the theme:

# Only show Forge info
RPROMPT='$(_forge_prompt_info)'

Performance Benchmarks

The theme is optimized for performance:

Operation	Time	Notes
Theme render	<60ms	Single Rust binary call
RPROMPT update	~50ms	Includes formatting
No active conversation	~10ms	Fast path for empty state

Performance is verified in CI using benchmark tests (see .github/workflows/ci.yml:57).

Examples

Minimal Setup

~/.zshrc

# Minimal Forge theme
eval "$(forge zsh theme)"

Full Setup with Customization

~/.zshrc

# Forge theme with custom settings
export FORGE_CURRENCY_SYMBOL="€"
export FORGE_CURRENCY_CONVERSION_RATE="0.85"
export NERD_FONT="1"
export FORGE_BIN="$HOME/.local/bin/forge"

# Load theme
eval "$(forge zsh theme)"

Oh My Zsh Integration

~/.zshrc

export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="agnoster"
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

source $ZSH/oh-my-zsh.sh

# Forge plugin and theme
eval "$(forge zsh plugin)"
eval "$(forge zsh theme)"

Next Steps

ZSH Plugin

Install the complete ZSH plugin

Shell Completions

Set up shell completions

Configuration

Configure Forge settings

Customization

Customize Forge appearance

Shell Integration

Editor Integration

CI/CD

ZSH Theme Setup

Overview

Features

Installation

Theme Components

Information Display

Configuration

Currency Settings

Font Settings

Complete Configuration Example

Theme Implementation

Performance Optimization

Integration with Existing Themes

Oh My Zsh Themes

Powerlevel10k

Starship

Pure Prompt

Customizing Display

Show/Hide Elements

Custom Formatting

Nerd Font Icons

Automatic Detection

Supported Icons

Fallback Display

Troubleshooting

Performance Benchmarks

Examples

Minimal Setup

Full Setup with Customization

Oh My Zsh Integration

Next Steps

ZSH Plugin

Shell Completions

Configuration

Customization

Build docs developers (and LLMs) love

Shell Integration

Editor Integration

CI/CD

​Overview

​Features

​Installation

​Theme Components

​Information Display

​Configuration

​Currency Settings

​Font Settings

​Complete Configuration Example

​Theme Implementation

​Performance Optimization

​Integration with Existing Themes

​Oh My Zsh Themes

​Powerlevel10k

​Starship

​Pure Prompt

​Customizing Display

​Show/Hide Elements

​Custom Formatting

​Nerd Font Icons

​Automatic Detection

​Supported Icons

​Fallback Display

​Troubleshooting

​Performance Benchmarks

​Examples

​Minimal Setup

​Full Setup with Customization

​Oh My Zsh Integration

​Next Steps

ZSH Plugin

Shell Completions

Configuration

Customization

Build docs developers (and LLMs) love

Overview

Features

Installation

Theme Components

Information Display

Configuration

Currency Settings

Font Settings

Complete Configuration Example

Theme Implementation

Performance Optimization

Integration with Existing Themes

Oh My Zsh Themes

Powerlevel10k

Starship

Pure Prompt

Customizing Display

Show/Hide Elements

Custom Formatting

Nerd Font Icons

Automatic Detection

Supported Icons

Fallback Display

Troubleshooting

Performance Benchmarks

Examples

Minimal Setup

Full Setup with Customization

Oh My Zsh Integration

Next Steps