Troubleshooting
Solutions to common issues and how to get help.
Quick Diagnostics
Start with broski doctor, then run a focused profile if needed:
bash
# Full diagnostic run
broski doctor
# Focused diagnostics
broski doctor --profile pairing
broski doctor --profile network
broski doctor --profile agents
broski doctor --profile daemon
# Apply safe fixes + export bundle
broski doctor --fix
broski doctor --exportWhat Doctor Checks
| Category | Examples | Useful Command |
|---|---|---|
| Pairing | Token validity, TLS cert/fingerprint, QR readiness | broski doctor --profile pairing |
| Network | Local IP, port conflicts, Tailscale status | broski doctor --profile network |
| Agents | OpenCode / Claude / Codex availability | broski doctor --profile agents |
| Daemon | Background service state and config | broski doctor --profile daemon |
Reading the Output
| Symbol | Status | Meaning |
|---|---|---|
✓ | Passed | Check passed, no action needed |
! | Warning | Works but may degrade reliability |
✗ | Error | Needs fixing before reliable use |
ℹ | Info | Informational context |
Health Check Commands
Run these commands for fast targeted checks:
bash
# Pairing + auth path
broski doctor --profile pairing
# Network path
broski doctor --profile network
# Backend path
broski doctor --profile agents
# Daemon/service path
broski doctor --profile daemon
# Live logs + exportable bundle
broski logs --follow
broski logs --exportCommon Issues
Emergency Quick Fixes
| Problem | Quick Fix |
|---|---|
| Can't connect | Restart bridge, re-scan QR |
| Port in use | lsof -nP -iTCP:18274 (macOS/Linux) or netstat -ano | findstr :18274 (Windows) then kill the PID |
| Auth failed | broski --new-token |
| OpenCode missing | curl -fsSL https://opencode.ai/install | bash |
| Everything broken | rm -rf ~/.broski/ and restart |
Nuclear Options
When nothing else works, try these complete reset procedures:
Warning
These steps delete data and require reconfiguration. Use as a last resort.
Reset Mobile App
iOS
- Delete the Broski app
- Restart your device
- Reinstall from App Store
- Re-scan QR code to connect
Android
- Settings → Apps → Broski → Clear Data (not just cache)
- Force Stop
- Uninstall
- Reinstall from Play Store
- Re-scan QR code to connect
Reset Bridge
bash
# Stop the bridge (Ctrl+C in the terminal running it)
# Remove all Broski data
rm -rf ~/.broski/
# Start fresh (generates new token)
broskiComplete Reinstall
1
Remove bridge
bash
rm -rf ~/.broski/2
Reinstall bridge
Download and install the bridge again for your platform.
3
Remove and reinstall mobile app
Delete and reinstall from your app store
4
Restart your computer and phone
5
Start fresh
bash
broski doctor # Verify setup
broski # Start bridge6
Scan new QR code
Open the app and scan the QR code displayed in your terminal
Getting Help
Collecting Debug Information
Before reporting an issue, collect this information:
bash
# Bridge version
broski --version
# Focused diagnostics + safe fixes
broski doctor --profile pairing
broski doctor --fix
# Export support bundle (redacted)
broski doctor --export
# or
broski logs --export
# Interactive troubleshooter
broski troubleshootLog Locations
| Component | Location |
|---|---|
| Bridge logs | broski logs (or check ~/.broski/logs/bridge.log) |
| Auth token | ~/.broski/token.json |
| OpenCode logs | Terminal output |
| Claude Code sessions | ~/.claude/projects/ |
| iOS app logs | Xcode Console or Analytics Data |
| Android app logs | adb logcat |
Contact Support
If you couldn't find a solution, we're here to help:
- Email Support: broskiappp@gmail.com
We typically respond within 24 hours
Include: App version (Settings → About), iOS/Android version, bridge version, and the debug info collected above.
Status Indicators
Understanding connection status in the app:
| Indicator | Meaning |
|---|---|
| Green dot | Connected and healthy |
| Yellow dot | Connected with issues (high latency) |
| Red dot | Disconnected |
| Spinner | Reconnecting |
| "Busy" badge | AI is processing |