Setup Guide
Get Broski running in under 5 minutes.
Prerequisites
- ✓A computer (macOS 12+, Windows 10+, or Linux)
- ✓A smartphone (iOS 15+ or Android 8+)
- ✓At least one AI coding agent installed (Claude Code, OpenCode, or Codex CLI)
Step 1: Install the Bridge
The bridge is a lightweight server that runs on your computer and connects your phone to your AI coding agents. Choose your platform below.
Download and install the Broski bridge for your platform, then run it from your terminal:
macOS
broskiWindows
broskiLinux
broskiStep 2: Verify Installation
Run diagnostics to verify setup, then apply safe fixes if needed:
broski doctor
broski doctor --fixCommon focused checks:
# Pairing readiness (token + TLS + QR)
broski doctor --profile pairing
# Backend readiness (OpenCode/Claude/Codex)
broski doctor --profile agentsbroski doctor --fix, then export diagnostics if still stuck:broski doctor --exportStep 3: Start the Bridge
When you run the bridge, you'll see a QR code in your terminal:
Keep this terminal window open. The bridge needs to be running for Broski to work.
Step 4: Download Broski
Download Broski for your mobile device:
| Platform | Download | Requirements |
|---|---|---|
| iOS | App Store (coming soon) | iOS 15.0+ |
| Android | Coming soon | In development |
Step 5: Connect
- 1Open Broski on your phone
- 2Tap "Scan QR Code"
- 3Point your camera at the QR code in your terminal
- ✓Done! You're now connected to your computer
Common Issues
"Port already in use"
Another process is using port 18274. Find and kill it, or use a different port:
# Find what's using the port
lsof -nP -iTCP:18274 -sTCP:LISTEN
# Or use a different port
broski --port 8080"Can't scan QR code"
Make sure your phone and computer are on the same WiFi network. If scanning fails, tap "Enter manually" and type the IP address shown in your terminal.
"Connection failed"
Run focused diagnostics first, then apply firewall rules if needed:
broski doctor --profile pairing
broski doctor --profile network
# macOS: allow incoming connections
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which broski)
# Linux (UFW)
sudo ufw allow 18274/tcp"No AI agents found"
Make sure you have at least one AI coding agent installed:
# Check installed agents
which claude # Claude Code
which opencode # OpenCode
which codex # Codex CLI"broski: command not found"
Make sure the Broski bin directory is in your PATH:
# Add to your shell profile (~/.bashrc or ~/.zshrc)
export PATH="$HOME/.broski/bin:$PATH"
# Then reload
source ~/.bashrc # or source ~/.zshrc