Installation¶

Desktop App (macOS)¶

Option 1: Download Release (Recommended)¶

Download the latest release from GitHub Releases: PlexusOneDesktop-X.Y.Z-macos-arm64.dmg for Apple Silicon, -x86_64.dmg for Intel, or -universal.dmg for either
Open the .dmg and drag PlexusOne Desktop to Applications
Open PlexusOne Desktop from Applications. The first time, macOS blocks it (see App Won't Open)

Upgrading¶

Quit PlexusOne Desktop (⌘Q) before opening a new version. Only one copy of the app runs at a time: opening a second copy brings the running one forward and quits, so a new version opened while the old one runs never starts.

Then install the new version as above, replacing the old app. Windows, layouts, and the Claude session log are kept in ~/.plexusone/, so they carry over. If you installed the Claude Code hook and the app is in the same place, it keeps working; if you moved the app, click Update Hook in Settings > Sessions.

Option 2: Build from Source¶

Prerequisites¶

Xcode Command Line Tools
Swift 5.9+
tmux installed via Homebrew

Build Steps¶

# Clone the repository
git clone https://github.com/plexusone/plexusone-app.git
cd plexusone-app/apps/desktop

# Build the app
swift build -c release

# Copy to Applications (optional)
cp -r "PlexusOne Desktop.app" /Applications/

Run Without Installing¶

# Build and run directly
swift build
open "PlexusOne Desktop.app"

# Or run the binary
.build/debug/PlexusOneDesktop

TUI Parser (For Mobile Support)¶

The TUI Parser is a Go service that bridges tmux sessions to the mobile app over WebSocket.

Build¶

cd plexusone-app/services/tuiparser

# Build the binary
go build -o bin/tuiparser ./cmd/tuiparser

Run¶

# Start on 127.0.0.1:9600 (this machine only)
./bin/tuiparser

# Or specify a different port
./bin/tuiparser --port 8080

# Listen on the network for the mobile app; a token is required
export TUIPARSER_TOKEN=$(openssl rand -hex 32)
./bin/tuiparser --host 0.0.0.0

See Connecting to Desktop for security guidance.

Verify¶

Open http://localhost:9600 in your browser to see the debug console.

Mobile App¶

iOS¶

Coming Soon

iOS app will be available on TestFlight and the App Store.

For now, build from source:

cd plexusone-app/apps/mobile
flutter pub get
flutter run --device-id <your-iphone-id>

Android¶

Coming Soon

Android APK will be available on GitHub Releases.

For now, build from source:

cd plexusone-app/apps/mobile
flutter pub get
flutter build apk --release

Install the APK from build/app/outputs/flutter-apk/app-release.apk.

Verify Installation¶

Desktop App¶

Open PlexusOne Desktop
You should see the main window with "Loading..." then an empty 2×1 grid
Create a test tmux session:
```
tmux new-session -d -s test
```
Click the session dropdown in any pane and select "test"
You should see the terminal output

TUI Parser¶

Start the TUI Parser: ./bin/tuiparser
Open http://localhost:9600
Enter a session name and click "Subscribe"
You should see terminal output streaming

Troubleshooting¶

"tmux not found"¶

Ensure tmux is installed and in your PATH:

which tmux
# Should output: /opt/homebrew/bin/tmux or /usr/local/bin/tmux

If not found, install via Homebrew:

brew install tmux

"Cannot connect to WebSocket"¶

Ensure TUI Parser is running: ./bin/tuiparser
Check the port is not in use: lsof -i :9600
Verify firewall allows connections on port 9600
For connections from another device, start TUI Parser with --host and a token, and enter the same token in the app

App Won't Open (macOS Security)¶

Release builds are ad-hoc signed but not notarized, so on first launch macOS says it could not verify the app. Open System Settings > Privacy & Security, scroll to the message about PlexusOne Desktop, and click Open Anyway. The prompt does not appear again for that copy.

From Terminal instead:

xattr -dr com.apple.quarantine "/Applications/PlexusOne Desktop.app"