omarchy-mcp

Gib jeder MCP-kompatiblen LLM die volle Kontrolle über einen Omarchy Linux-Desktop.

omarchy-mcp verwandelt KI-Codierungsagenten in echte Desktop-Operatoren. Über einen einzigen MCP-Server kann ein Agent Themes und Erscheinungsbild verwalten, Apps starten, Screenshots und Aufnahmen machen, Audio und Netzwerk steuern, den Systemzustand auslesen, Hyprland-Fenster und Kachel-Layouts steuern und ganze Multi-Agent-Arbeitsbereiche orchestrieren – 108 Tools in 15 Modulen.

Das Projekt basiert auf einer Regel: Eine Desktop-Änderung ist nicht allein deshalb erfolgreich, weil ein Befehl ausgeführt wurde. Jede Aktion wird anhand des gemessenen Desktop-Zustands bestätigt – Geometrie, Fokus, Servicestatus –, damit Agenten autonom handeln können, ohne stillschweigend zu scheitern.

Status

Siehe COMMANDS.md für den Verifizierungsstatus pro Tool und ROADMAP.md für geplante Meilensteine.

Related MCP server: linux-computer-use

Warum es das gibt

Desktop-Steuerungstools melden oft, dass eine Aktion ausgelöst wurde, ohne zu prüfen, ob sie funktioniert hat. Das ist besonders unzuverlässig bei Kachel-Fenstermanagern, wo Fokus, Floating-Regeln, Vollbildstatus, Workspace-Regeln und die Maus das Ziel verändern können.

Dieser Server fügt die fehlende Rückkopplungsschleife hinzu:

• Fenstermutationen melden den gemessenen Vorher/Nachher-Zustand und ein klares Urteil.

• Explizite Adress- und Match-Selektoren reduzieren fokusbedingte Fehler.

• Ein PID-Abstammungs-Schutz verhindert, dass der Agent sein eigenes Host-Fenster schließt.

• Destruktive Systemoperationen erfordern eine explizite Konfigurationsfreigabe.

• health_check diagnostiziert fehlende Befehle, Layout-Installation und Desktop-Konnektivität.

• agent_grid verwandelt eine gesamte Multi-Agent-Workspace-Anfrage in eine verifizierte MCP-Operation.

Schnellstart

Anforderungen

• Ein installierter Omarchy-Desktop

• Hyprland mit Omarchys Lua-Konfigurationsbrücke

• Node.js 20 oder neuer

• npm

Einzelne Funktionen können auch wtype, nmcli, bluetoothctl, wpctl, grim und wl-copy verwenden. health_check meldet, welche optionalen Befehle verfügbar sind.

Build

git clone https://github.com/hlsitechio/Omarchy-MCP.git
cd Omarchy-MCP
npm ci
npm run build
npm test

Der MCP-Einstiegspunkt ist:

node /absolute/path/to/Omarchy-MCP/build/index.js

Installieren des nativen Raster-Layouts

Die regulären Desktop-Tools können ohne das benutzerdefinierte Layout ausgeführt werden, aber deterministisches Raster-/Master-Tiling und agent_grid erfordern es.

install -Dm644 hypr/layouts.lua ~/.config/hypr/layouts.lua

Stellen Sie sicher, dass die Benutzer-Hyprland-Konfiguration es lädt:

require("hypr.layouts")

Laden Sie dann neu und überprüfen Sie die Konfiguration:

hyprctl reload
hyprctl configerrors

Omarchy-Paketdateien unter /usr/share/omarchy sollten unberührt bleiben; das Layout gehört in die Benutzerkonfiguration unter ~/.config/hypr.

Einen MCP-Client verbinden

Jeder Client, der lokale stdio-MCP-Server unterstützt, kann build/index.js starten.

OpenCode

Fügen Sie dies zu ~/.config/opencode/opencode.json hinzu und ersetzen Sie den Pfad durch den absoluten Pfad des Repositorys:

{
  "mcp": {
    "omarchy": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/Omarchy-MCP/build/index.js"
      ],
      "enabled": true
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "omarchy": {
      "command": "node",
      "args": ["/absolute/path/to/Omarchy-MCP/build/index.js"]
    }
  }
}

Starten Sie nach dem Neubauen einen vorhandenen MCP-Client neu oder verbinden Sie ihn erneut, damit er das Tool-Schema neu lädt.

Erste Prompts zum Ausprobieren

• „Prüfe, ob mein Omarchy MCP gesund ist.“

• „Zeige jedes Fenster mit seinem Workspace und seiner Geometrie.“

• „Öffne ein 2x2-Raster von OpenCode auf dem nächsten leeren Workspace.“

• „Platziere Claude oben rechts und Codex unten rechts.“

• „Verschiebe Firefox auf Workspace 4 und bestätige, wo es gelandet ist.“

• „Fange dieses Fenster oben links ein und sage mir seine endgültige Größe.“

• „Liste nahegelegene Wi-Fi-Netzwerke auf, aber verbinde dich mit nichts.“

Codierungsagent-Workspaces mit einem Befehl

agent_grid startet unabhängige Omarchy-TUI-Fenster, wendet das native Raster-Layout an, weist exakte oder spärliche Zellen zu und verifiziert die Anwendungsklasse, den Workspace, den Floating-Zustand und die beobachtete Geometrie jedes Fensters.

Für vier Anwendungen fragen Sie nach einem 2x2-Raster. Ein wörtliches 4x4-Raster enthält 16 Zellen und startet bei voller Belegung 16 Anwendungen.

Homogenes Raster

Prompt:

Öffne ein 2x2-Raster von OpenCode in diesem Repository.

Äquivalente Argumente:

{
  "agent": "opencode",
  "cols": 2,
  "rows": 2,
  "workspace": "next_empty",
  "cwd": "/path/to/project"
}

Gemischtes spärliches Raster

Prompt:

Öffne Claude oben rechts und Codex unten rechts.

Äquivalente Argumente:

{
  "cols": 2,
  "rows": 2,
  "placements": [
    { "agent": "claude", "position": "top_right" },
    { "agent": "codex", "position": "bottom_right" }
  ]
}

Unterstützte Agenten sind OpenCode, Claude, Codex, Gemini, Copilot, Crush, Grok, Oh My Pi (omp) und Pi. Verwenden Sie dry_run: true, um einen vollständigen Plan zu validieren, ohne Fenster zu öffnen.

Benannte Eckzuweisungen und explizite Zeilen-/Spaltenzuweisungen bleiben erhalten, wenn der Benutzer die Workspaces wechselt. Vor dem Start werden vorhandene gekachelte Fenster gezählt, und die Anfrage wird abgelehnt, wenn sie die Rasterkapazität überschreiten würde.

Tool-Gruppen

Die vollständige Liste und ihr Live-Test-Status werden in COMMANDS.md gepflegt.

Sicherheitsmodell

Keine Shell-Interpolation

Befehle werden mit Argument-Arrays über Node's execFile oder spawn ausgeführt; Benutzereingaben werden nicht in Shell-Befehle verkettet.

Destruktive Operationen sind optional

Herunterfahren, Neustart, Paketinstallation, Systemupdates und Konfigurationsaktualisierungen sind standardmäßig deaktiviert. Aktivieren Sie sie mit:

mkdir -p ~/.config/omarchy-mcp
printf '%s\n' '{"enableDangerous": true}' > ~/.config/omarchy-mcp/config.json

Oder setzen Sie die Prozessebenen-Überschreibung:

OMARCHY_MCP_ENABLE_DANGEROUS=1 node build/index.js

Verwenden Sie diese Einstellung nur für einen Client und eine Sitzung, denen Sie vertrauen.

Schutz des Host-Fensters

Fensterschließ- und andere risikoreiche Operationen lösen die PID-Abstammung des MCP-Hostprozesses auf und weigern sich, das eigene Terminalfenster anzusteuern. Explizite Fensteradressen werden für Mutationen bevorzugt, da der Hyprland-Fokus der Maus folgen kann.

Verifizierte Ergebnisse

Mutierende Fenster-Tools geben Status wie confirmed, split_confirmed, opened_but_not_split oder not_detected zurück, zusammen mit dem gemessenen Zustand und gegebenenfalls einem Wiederherstellungshinweis.

Architektur

MCP client
    │  JSON-RPC over stdio
    ▼
MCP tool + Zod input validation
    │
    ├── Omarchy CLI ───────────── themes, capture, power, applications
    ├── Hyprland Lua dispatcher ─ windows, workspaces, native layout
    └── System CLIs ───────────── nmcli, bluetoothctl, wpctl, upower
    │
    ▼
State reread + geometry/verdict engine
    │
    ▼
Structured MCP result with STATUS, evidence, and HINT

Quellstruktur:

src/index.ts              server and tool registration
src/exec.ts               shell-free process execution
src/hypr.ts               desktop introspection and verification helpers
src/result.ts             consistent MCP success/error results
src/config.ts             safety configuration
src/tools/                 tool domains
hypr/layouts.lua          native deterministic grid/master layout
test/                      automated and manual live tests

Hyprland-Fensterdispatches verwenden die Omarchy-Lua-API, zum Beispiel:

hl.dsp.window.resize({ window = "address:0x...", x = 900, y = 700, relative = false })

Das native Layout unterstützt grid- und master-Modi sowie Laufzeitnachrichten für erzwungene Abmessungen, Reihenfolge, Tausche, spärliche Zellen und den Zustand pro Workspace.

Entwicklung und Verifizierung

npm run build      # TypeScript compilation
npm test           # compilation + deterministic planner tests
npm run smoke      # live local MCP/Omarchy smoke test

Der Smoke-Test ist bewusst desktop-bewusst. Er prüft die Tool-Registrierung, den Gesundheitsbericht, den schreibgeschützten Omarchy/Hyprland-Zugriff, das Tor für destruktive Operationen und einen agent_grid-Trockenlauf. Visuelle Mutationen werden manuell in einer echten Omarchy-Sitzung verifiziert und in COMMANDS.md festgehalten.

Für eine Live-Übung mit Agent-Raster:

node test/live-agent-grid.mjs

Dieser Befehl öffnet echte Fenster und ändert den aktiven Workspace; er ist nicht Teil von npm test.

Fehlerbehebung

Das neue Tool erscheint nicht

Führen Sie npm run build aus und starten Sie dann den MCP-Client neu oder verbinden Sie ihn erneut. MCP-Clients speichern die Tool-Liste normalerweise für die Lebensdauer des Serverprozesses zwischen.

health_check meldet, dass das Raster-Layout nicht vollständig installiert ist

Bestätigen Sie, dass ~/.config/hypr/layouts.lua existiert, dass die Benutzer-Hyprland-Konfiguration require("hypr.layouts") enthält und dass hyprctl configerrors leer ist.

Ein Fensterbefehl hat das falsche Ziel ausgewählt

Rufen Sie window_list auf und versuchen Sie es dann mit der zurückgegebenen Adresse erneut, anstatt sich auf das fokussierte Fenster zu verlassen. Dies vermeidet input:follow_mouse-Fokusänderungen.

Ein gefährliches Tool meldet, dass es deaktiviert ist

Das ist die sichere Standardeinstellung. Aktivieren Sie es nur explizit, nachdem Sie das Sicherheitsmodell überprüft haben.

Ein Layout-Befehl meldet eine Hyprland-Warnung

Einige Compositor-No-Ops sind zu erwarten – zum Beispiel das Tauschen eines Vollbildfensters oder das Tauschen in eine leere Zelle. Das MCP-Ergebnis unterscheidet diese Warnungen von bestätigten Mutationen.

Mitwirken

Beiträge sind willkommen in den Bereichen Implementierung, Live-Verifizierung, Dokumentation, Tests, Barrierefreiheit und Release-Engineering. Das Repository bietet strukturierte Issue-Formulare für Fehler, Tool-Vorschläge und Verifizierungsberichte sowie eine Pull-Request-Checkliste, die auf das Sicherheitsmodell des Projekts abgestimmt ist.

Beginnen Sie mit CONTRIBUTING.md und wählen Sie dann einen Beitragsbereich aus ROADMAP.md. Umfangreiche oder risikoreiche Änderungen sollten mit einem Issue beginnen, damit Umfang, Nachweise und Wiederherstellungsverhalten vor dem Codieren vereinbart werden können.

Projektdokumente

• COMMANDS.md — Implementierungs- und Live-Verifizierungsprotokoll

• ROADMAP.md — Meilensteine, Prioritäten und Release-Gates

• CONTRIBUTING.md — Beitrags- und Testworkflow

• GOVERNANCE.md — Rollen, Entscheidungen, Reviews und Releases

• SECURITY.md — private Meldung und Sicherheitsgrenzen

• CODE_OF_CONDUCT.md — Standards für die Teilnahme an der Community

• AGENTS.md — technischer Kontext für Codierungsagenten, die am Repository arbeiten

Lizenz

MIT