OpenWriterControle/docs/getting-started/platform-compatibility.md

Platform Compatibility Guide

The OpenAgents Control installer is designed to work across multiple platforms and bash versions.

Supported Platforms

✅ macOS

• Bash Version: 3.2+ (default macOS bash is 3.2.57)
• Installation Method: curl + bash
• Status: Fully Supported

# Standard installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash

# Profile-based installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s core

Dependencies:

# Install via Homebrew
brew install curl jq

---

✅ Linux

• Bash Version: 3.2+ (most distros ship with 4.0+)
• Installation Method: curl + bash
• Status: Fully Supported

# Standard installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash

# Profile-based installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer

Dependencies:

Ubuntu / Debian

sudo apt-get update
sudo apt-get install curl jq

Fedora / RHEL / CentOS

sudo dnf install curl jq

Arch Linux

sudo pacman -S curl jq

Alpine Linux

apk add curl jq bash

---

✅ Windows

Option 1: Git Bash (Recommended)

• Bash Version: 4.4+ (included with Git for Windows)
• Installation Method: curl + bash
• Status: Fully Supported

Install Git for Windows:

1. Download from git-scm.com
2. Install with default options
3. Open "Git Bash" from Start Menu

Run Installer:

# Standard installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash

# Profile-based installation
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s full

Option 2: WSL (Windows Subsystem for Linux)

• Bash Version: 4.0+ (depends on WSL distro)
• Installation Method: curl + bash
• Status: Fully Supported

Setup WSL:

# In PowerShell (Admin)
wsl --install

Run Installer:

# In WSL terminal
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash

Dependencies:

# Ubuntu/Debian on WSL
sudo apt-get update
sudo apt-get install curl jq

Option 3: PowerShell (Download + Run)

• Status: Supported (requires Git Bash installed)

# Download the script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh" -OutFile "install.sh"

# Run with Git Bash
& "C:\Program Files\Git\bin\bash.exe" install.sh core

# Or with WSL
wsl bash install.sh core

---

Requirements

Minimum Requirements

• Bash: 3.2 or higher
• curl: Any recent version
• jq: 1.5 or higher
• Disk Space: ~5MB for full installation
• Internet: Required for downloading components

Tested Configurations

Platform	Bash Version	Status	Notes
macOS 13+	3.2.57	✅ Pass	Default system bash
macOS 13+	5.2 (Homebrew)	✅ Pass	Upgraded bash
Ubuntu 24.04	5.2.21	✅ Pass	Fixed in v1.1.0
Ubuntu 22.04	5.1.16	✅ Pass	Default
Ubuntu 20.04	5.0.17	✅ Pass	Default
Debian 11	5.1.4	✅ Pass	Default
Fedora 38	5.2.15	✅ Pass	Default
Arch Linux	5.2.21	✅ Pass	Default
Alpine 3.18	5.2.15	✅ Pass	Requires bash package
Git Bash (Windows)	4.4.23	✅ Pass	Git for Windows
WSL2 Ubuntu	5.1.16	✅ Pass	Default

---

Compatibility Features

Bash 3.2 Compatibility

The installer is specifically designed to work with bash 3.2 (macOS default):

✅ No mapfile usage - Uses while-read loops instead
✅ No process substitution issues - Uses temp files for compatibility
✅ POSIX-compliant - Avoids bash 4+ specific features
✅ Array operations - Uses bash 3.2 compatible syntax

Bash 5.x Compatibility (Fixed in v1.1.0)

The installer now works correctly with bash 5.x (Ubuntu 24.04, modern Linux):

✅ set -e compatible arithmetic - Uses variable=$((variable + 1)) instead of ((variable++))
✅ No premature exits - Fixed issue where counters starting at 0 caused script exit
✅ Tested on bash 5.2.21 - Fully compatible with Ubuntu 24.04 and newer systems

What was fixed:

• Changed all arithmetic increment operations from ((variable++)) to variable=$((variable + 1))
• This prevents set -e from triggering exit when variables start at 0
• Maintains error detection while ensuring compatibility across all bash versions

Cross-Platform Features

✅ Platform detection - Automatically detects macOS/Linux/Windows
✅ Color support detection - Disables colors on unsupported terminals
✅ Path handling - Works with Unix and Windows paths (tilde expansion, backslash conversion)
✅ Line endings - Handles both LF and CRLF
✅ Custom install directories - Supports local, global, and custom installation paths

---

Testing Your System

Run the compatibility test to verify your system:

# Download and run the test
curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/scripts/tests/test-compatibility.sh | bash

Or manually:

# Clone the repo
git clone https://github.com/darrenhinde/OpenAgentsControl.git
cd OpenAgentsControl

# Run the test
bash scripts/tests/test-compatibility.sh

The test checks:

• ✅ Bash version (3.2+)
• ✅ Required dependencies (curl, jq)
• ✅ Script syntax
• ✅ Argument parsing
• ✅ Array operations
• ✅ File operations
• ✅ Network connectivity

---

Troubleshooting

Script exits immediately on Ubuntu 24.04 / bash 5.x

Cause: Older versions of the installer had a set -e compatibility issue with bash 5.x
Status: ✅ FIXED in v1.1.0
Solution: Update to the latest installer:

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh > install.sh
bash install.sh developer

Technical Details:

• Issue: ((variable++)) returns 0 when variable is 0, triggering set -e exit in bash 5.x
• Fix: Changed to variable=$((variable + 1)) which is safe with set -e
• Affected: Ubuntu 24.04 (bash 5.2.21) and other modern Linux distributions
• All arithmetic operations now use the safe pattern

"mapfile: command not found"

Cause: Using bash version < 4.0
Solution: This should be fixed in the latest version. Update the installer:

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh > install.sh
bash install.sh developer

"curl: command not found"

Cause: curl is not installed
Solution:

# macOS
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Fedora/RHEL
sudo dnf install curl

# Windows: Install Git for Windows (includes curl)

"jq: command not found"

Cause: jq is not installed
Solution:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Fedora/RHEL
sudo dnf install jq

# Windows Git Bash
curl -L -o /usr/bin/jq.exe https://github.com/stedolan/jq/releases/latest/download/jq-win64.exe

Colors not displaying correctly (Windows)

Cause: Terminal doesn't support ANSI colors
Solution: Use Windows Terminal, Git Bash, or WSL instead of cmd.exe

"Permission denied" errors

Cause: Insufficient permissions
Solution:

# Don't use sudo with the installer
# It installs to .opencode/ in current directory

# If you need to install globally:
sudo bash install.sh core

Script fails on Windows PowerShell

Cause: PowerShell can't run bash scripts directly
Solution: Use Git Bash or WSL:

# Download first
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh" -OutFile "install.sh"

# Run with Git Bash
& "C:\Program Files\Git\bin\bash.exe" install.sh

---

Known Limitations

Windows cmd.exe

❌ Not Supported - Use Git Bash or WSL instead

Bash < 3.2

❌ Not Supported - Upgrade bash or use a different system

No Internet Connection

❌ Not Supported - Installer requires internet to download components
Workaround: Use manual installation (clone repo and copy files)

---

Manual Installation (No Internet)

If you can't use the installer:

# 1. Clone or download the repository
git clone https://github.com/darrenhinde/OpenAgentsControl.git
cd OpenAgentsControl

# 2a. Install locally (recommended - in your project directory):
bash install.sh developer

# 2b. Or install globally (available to all projects):
bash install.sh developer --install-dir ~/.config/opencode

# 2c. Or copy manually to global location:
mkdir -p ~/.config/opencode
cp -r .opencode/agent ~/.config/opencode/
cp -r .opencode/command ~/.config/opencode/
cp -r .opencode/context ~/.config/opencode/
cp -r .opencode/tool ~/.config/opencode/
cp -r .opencode/plugin ~/.config/opencode/

# 3. Configure environment
cp env.example .env
# Edit .env with your settings

---

Getting Help

If you encounter issues:

1. Run the compatibility test:

   curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/scripts/tests/test-compatibility.sh | bash
   

2. Check your bash version:

   bash --version
   

3. Verify dependencies:

   curl --version
   jq --version
   

4. Report issues:

   • GitHub Issues
   • Include: Platform, Bash version, Error message

---

Summary

✅ macOS - Works out of the box (bash 3.2+)
✅ Linux - Works on all major distributions
✅ Windows - Use Git Bash or WSL
✅ Bash 3.2+ - Fully compatible
✅ Cross-platform - Same commands everywhere

The installer is designed to "just work" on any modern system with bash 3.2+.