# 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)
```bash
curl -fsSL https://forgecode.dev/cli | sh
```

### Method 2: Nix
```bash
nix run github:antinomyhq/forge
```

### Method 3: NPM
```bash
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:**
```bash
# 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:**
```bash
:<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:**
```bash
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:**
   ```bash
   forge zsh doctor
   ```

2. **Verify icons:**
   - Should display without overlap
   - Check during interactive setup

3. **Test basic commands:**
   ```bash
   : hi
   :new
   :agent
   ```

4. **Configure provider:**
   ```bash
   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/