harness-feedback/forgecode/feedback/localllm/installation-platform-issues.md

Installation & Platform Issues - Feedback Report

Topic: Setup problems, platform compatibility, requirements
Source References: GitHub issues, ForgeCode docs, Reddit
Date Compiled: April 9, 2026

---

Supported Platforms

Officially Supported

• macOS: Full support
• Linux: Best support
• Android: Supported
• Windows: Via WSL or Git Bash only

Not Supported

• Native Windows: Not officially supported

---

Installation Methods

Method 1: YOLO Install (Recommended)

curl -fsSL https://forgecode.dev/cli | sh

Method 2: Nix

nix run github:antinomyhq/forge

Method 3: NPM

npx forgecode@latest

---

Common Installation Issues

Issue #2485: Mac Installation Problems

Symptoms:

• Oh My Zsh not found
• Terminal configuration issues
• Shell environment problems

Environment Reported:

• Shell: zsh 5.9
• Terminal: iTerm.app 3.6.8
• Oh My Zsh: Not installed

Solution:

# Install Oh My Zsh first
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Then re-run forge setup
forge zsh setup

Terminal Requirements

Required: Nerd Font

• Purpose: Icon display
• Recommended: FiraCode Nerd Font
• Verification: Icons should display without overlap during setup

Recommended Terminals

• iTerm2 (macOS)
• Ghostty (macOS) - NOTE: Has resize bug (#2893)
• Any modern Linux terminal

---

ZSH Integration Issues

Interactive Mode Isolation

Design: ForgeCode's interactive mode runs in isolated environment

Impact:

• ZSH aliases don't work inside interactive mode
• Custom functions unavailable
• Shell tooling not accessible

Solution: Use : sentinel from native ZSH session instead

Tab Completion

Requirements:

• fd (file finder)
• fzf (fuzzy finder)

Usage:

:<TAB>        # Open command list
@file<TAB>    # Fuzzy file picker

Fallback: Use full path with brackets: @[src/components/Header.tsx]

---

Platform-Specific Notes

macOS

Best Practices:

• Use iTerm2 or Ghostty
• Install Oh My Zsh for best experience
• Enable Nerd Font in terminal preferences

Troubleshooting:

forge zsh doctor   # Check setup
forge zsh setup    # Reconfigure

Linux

Advantages:

• Best performance for local models
• Native ZSH support
• Package manager availability

Tips:

• Use system package manager when available
• Check htop for resource monitoring

Windows

Limitations:

• No native support
• Must use WSL or Git Bash

WSL Recommendation:

• Ubuntu 22.04+ recommended
• Install ZSH within WSL
• Windows Terminal for best experience

Android

Status: Supported but limited documentation Use Case: Primarily for remote development scenarios

---

Verification Steps

Post-Installation Checklist

1. Run doctor:

   forge zsh doctor
   

2. Verify icons:

   • Should display without overlap
   • Check during interactive setup

3. Test basic commands:

   : hi
   :new
   :agent
   

4. Configure provider:

   forge provider login
   

---

Open Issues

#2893: Ghostty Terminal Resize Bug

• Problem: Terminal output disappears on window resize
• Status: Open, 1 linked PR
• Workaround: Avoid resizing or use different terminal

#2884: Muse Mode Shell Blocked

• Problem: Cannot use muse agent
• Status: Open
• Impact: Planning workflow blocked

---

Resource Requirements

Minimum

• RAM: 4GB (for cloud models)
• Disk: 500MB
• Shell: ZSH 5.0+

For Local Models

• RAM: 16GB+ recommended
• GPU: Optional but recommended for larger models
• Storage: 10GB+ for model downloads

---

Source References

1. GitHub Issue #2485: https://github.com/antinomyhq/forgecode/issues/2485
2. GitHub Issue #2893: https://github.com/antinomyhq/forgecode/issues/2893
3. ForgeCode Docs: https://forgecode.dev/docs/installation/
4. ZSH Support: https://forgecode.dev/docs/zsh-support/