Installation

Systemvoraussetzungen

Anforderung	Wert
Betriebssystem	macOS 26.0 „Tahoe" oder neuer
Architektur	Apple Silicon (arm64) oder Intel
Toolchain	Xcode 26 bzw. Swift 6.2 – nur zum Bauen, nicht zum Benutzen
Berechtigung	Bedienungshilfen (Accessibility)
Speicherplatz	ca. 8 MB

Schritt 1 – Aus dem Quellcode bauen

cd ~/nextcloud/Projects/Kachelwerk
./Scripts/build-app.sh --install

Das Skript arbeitet sechs Schritte ab und meldet jeden einzeln:

▸ 1/6  Anleitung ins Bundle spiegeln
▸ 2/6  Icon erzeugen
▸ 3/6  Swift-Paket bauen (release)
▸ 4/6  Bundle zusammenbauen
▸ 5/6  Signieren (identity: -)
▸ 6/6  Fertig
       …/Kachelwerk/build/Kachelwerk.app
▸ Nach /Applications kopieren
       /Applications/Kachelwerk.app

Im Bundle liegt neben der App auch der MCP-Server: /Applications/Kachelwerk.app/Contents/MacOS/kachelwerk-mcp – siehe Fernsteuerung & MCP-Server.

Ohne Installation testen – das Bundle landet dann nur unter build/:

./Scripts/build-app.sh
open build/Kachelwerk.app

Schritt 2 – Bedienungshilfen freischalten (Pflicht)

Ohne diese Freigabe kann Kachelwerk weder Fenster bewegen noch Tastenkürzel empfangen. Die App startet zwar, tut aber nichts – das Menüleistensymbol zeigt dann ein Pause-Zeichen.

Systemeinstellungen öffnen
Datenschutz & Sicherheit → Bedienungshilfen
Schalter bei Kachelwerk aktivieren

Ein Neustart der App ist nicht nötig: Kachelwerk bemerkt die Freigabe innerhalb von etwa 700 ms selbst und aktiviert sich.

Der Knopf „Systemeinstellungen öffnen" im Hinweisfenster und im Menüleisten-Menü springt direkt in den richtigen Bereich.

⚠️ Wichtig bei jedem Neubau

Die Berechtigung hängt an der Code-Signatur. Ein ad-hoc signiertes Bundle bekommt bei jedem Neubau eine neue Signatur – macOS widerruft die Freigabe daraufhin und der Haken muss erneut gesetzt werden. Manchmal muss der alte Eintrag vorher mit „−" entfernt werden.

Wer regelmäßig neu baut, setzt deshalb ein echtes Zertifikat:

export KACHELWERK_SIGN_IDENTITY="Developer ID Application: … (TEAMID)"
./Scripts/build-app.sh --install

Schritt 3 – Starten

Aktion	Weg
Starten	`open -a Kachelwerk` oder Doppelklick im Programme-Ordner
Beim Anmelden starten	Einstellungen → Allgemein → „Kachelwerk bei der Anmeldung starten"
Kacheln pausieren	Menüleistensymbol → Schalter Kacheln aktiv
Beenden	Menüleistensymbol → Kachelwerk beenden

Kachelwerk hat kein Dock-Symbol und kein Hauptfenster – es lebt ausschließlich in der Menüleiste.

Beim Beenden stellt Kachelwerk alle geparkten Fenster wieder her. Es bleiben keine unsichtbaren Fenster außerhalb des Bildschirms zurück.

Selbst entwickeln

swift build              # Debug-Build
swift test               # 702 Tests
./Scripts/run-tests.sh   # Tests mit Zusammenfassung
open Package.swift       # in Xcode öffnen

Der Kern liegt in KachelwerkCore und importiert kein AppKit, kein AXUIElement, keinen WindowServer. Deshalb laufen alle 702 Tests headless in Millisekunden – ohne Bedienungshilfen-Freigabe, ohne Bildschirm, ohne App-Bundle.

Signierung, Gatekeeper und App Store

Zum Selbstbauen ist Signieren optional. Das Skript signiert ad hoc (identity: -), was für den eigenen Rechner genügt.

Für die Weitergabe ist es zwingend: ein Developer-ID-Zertifikat plus Notarisierung, sonst blockt Gatekeeper das Bundle auf fremden Rechnern.

Ein Vertrieb über den Mac App Store ist nicht möglich. Die dort verpflichtende Sandbox erlaubt keinen Accessibility-Zugriff auf fremde Prozesse, und ein Entitlement dafür existiert nicht. Aus genau diesem Grund liegen auch Rectangle, Amethyst, yabai, Loop und AeroSpace alle außerhalb des Stores.

Fehlersuche

Beobachtung	Ursache und Abhilfe
Menüleistensymbol zeigt ein Pause-Zeichen	Bedienungshilfen-Freigabe fehlt oder wurde nach einem Neubau widerrufen – Haken neu setzen
Nichts passiert nach einem Neubau	Signatur hat sich geändert; alten Eintrag in den Bedienungshilfen mit „−" entfernen und neu hinzufügen
Eine App wird nicht gekachelt	Sie erzwingt ihre Größe selbst oder steht in `ignore_apps`; mit `windowrule = tile, <App>` erzwingen
Ein Kürzel greift nicht	Kollision mit einem macOS-Kürzel – anderen `mod_key` wählen
`⚠︎ n Konfigurationswarnung(en)` im Menü	Fehlerhafte Zeilen in der Konfigurationsdatei; der Menüeintrag nennt Zeilennummer und Grund
Fenster sind nach einem Absturz verschwunden	Sie wurden außerhalb des Bildschirms geparkt – Kachelwerk neu starten holt sie zurück, oder dauerhaft `hide_strategy = minimize` setzen

Deinstallation

./Scripts/uninstall.sh

Entfernt das Bundle aus /Applications. Die Konfigurationsdatei unter ~/Library/Application Support/Kachelwerk/ bleibt erhalten; ./Scripts/uninstall.sh --purge löscht sie mit.