Erste Schritte

Installation

Installationsoptionen — npx, global, native macOS-App oder aus dem Quellcode.

Wenn dir npx purplemux aus dem Schnellstart gereicht hat, bist du fertig. Diese Seite ist für alle, die persistent installieren, eine Desktop-App haben oder aus dem Quellcode bauen wollen.

Voraussetzungen

  • macOS 13+ oder Linux — Windows wird nicht unterstützt. WSL2 funktioniert meistens, ist aber außerhalb unserer Test-Matrix.
  • Node.js 20 oder neuer — prüfe mit node -v.
  • tmux — beliebige Version ab 3.0.

Installationsmethoden

npx (ohne Installation)

npx purplemux

Lädt purplemux beim ersten Lauf herunter und cached es unter ~/.npm/_npx/. Am besten zum Ausprobieren oder für ad-hoc-Läufe auf Remote-Maschinen geeignet. Jeder Lauf nutzt die neueste veröffentlichte Version.

Globale Installation

npm install -g purplemux
purplemux

pnpm und yarn funktionieren analog (pnpm add -g purplemux / yarn global add purplemux). Folgeläufe starten schneller, weil nichts mehr aufgelöst werden muss. Update mit npm update -g purplemux.

Das Binary ist außerdem als pmux verfügbar — kürzer.

Native macOS-App

Lade die aktuelle .dmg von Releases — Builds für Apple Silicon und Intel sind verfügbar. Auto-Update ist eingebaut.

Die App enthält Node, tmux und den purplemux-Server und ergänzt:

  • Ein Menüleisten-Symbol mit Server-Status
  • Native Benachrichtigungen (getrennt von Web Push)
  • Automatischer Start beim Login (Toggle in Einstellungen → Allgemein)

Aus dem Quellcode

git clone https://github.com/subicura/purplemux.git
cd purplemux
pnpm install
pnpm start

Für Entwicklung (Hot Reload):

pnpm dev

Port und Umgebungsvariablen

purplemux lauscht auf 8022 (web + ssh, als kleines Wortspiel). Override mit PORT:

PORT=9000 purplemux

Logging steuerst du über LOG_LEVEL (Default info) und LOG_LEVELS für Pro-Modul-Overrides:

LOG_LEVEL=debug purplemux
# nur das Claude-Hook-Modul debuggen
LOG_LEVELS=hooks=debug purplemux
# mehrere Module gleichzeitig
LOG_LEVELS=hooks=debug,status=warn purplemux

Verfügbare Levels: trace · debug · info · warn · error · fatal. Module, die nicht in LOG_LEVELS stehen, fallen auf LOG_LEVEL zurück.

Siehe Ports & Umgebungsvariablen für die vollständige Liste.

Beim Booten starten

Einfachste Option
Wenn du die macOS-App nutzt, aktiviere **Einstellungen → Allgemein → Beim Login starten**. Keine Skripte nötig.

Bei einer CLI-Installation packst du den Start in launchd (macOS) oder systemd (Linux). Eine minimale systemd-Unit sieht so aus:

# ~/.config/systemd/user/purplemux.service
[Unit]
Description=purplemux

[Service]
ExecStart=/usr/local/bin/purplemux
Restart=on-failure

[Install]
WantedBy=default.target

systemctl --user enable --now purplemux

Updates

Methode Befehl
npx automatisch (neueste bei jedem Lauf)
Global npm npm update -g purplemux
macOS-App automatisch (App aktualisiert beim Start)
Aus dem Quellcode git pull && pnpm install && pnpm start

Deinstallation

npm uninstall -g purplemux          # oder pnpm remove -g / yarn global remove
rm -rf ~/.purplemux                 # löscht Einstellungen und Session-Daten

Die native App ziehst du wie gewohnt in den Papierkorb. Siehe Daten-Verzeichnis für eine genaue Übersicht, was unter ~/.purplemux/ liegt.