Omarchy-4-AI-Agent-MCP: Instructions file for Codex

AGENTS.md — omarchy-mcp

Context for any LLM/agent resuming work on this project. Read this first.

Project status

Working MCP server (TypeScript + Node, stdio) exposing Omarchy desktop commands to any LLM. Built and smoke-tested (node smoke.mjs → SMOKE_OK).

• 108 tools implemented across src/tools/{theme,appearance,capture,desktop,windows,agents,network,local-system,defaults,device-controls,local-launchers,shell-ui,plugin-local,dangerous,health}.ts
  • src/hypr.ts (introspection & verdict engine)
• Verification layer: mutating window tools return measured before/after state with STATUS/HINT verdicts (split_confirmed / opened_but_not_split / not_detected)
• Self-guard: PID-ancestry lock prevents closing/tile-killing the host terminal (window_close refuses; self_window_info / self_window_snap target by address)
• Native Lua grid layout installed: ~/.config/hypr/layouts.lua -> lua:omarchy-grid with modes grid|master, runtime cmds set/cols/rows/auto/tomaster/swap/debug/show, and MCP wrappers: layout_mode, layout_grid, layout_order, layout_tomaster, layout_swap_windows
• One-call coding-agent orchestration: agent_grid launches homogeneous grids or mixed sparse placements (for example Claude top-right + Codex bottom-right), using per-agent app IDs and verified final geometry. The grid layout adds slot/slotlast/unslot/clearslots runtime messages for sparse cells.
• Destructive tools gated by enableDangerous (see src/config.ts)
• Full coverage table with per-command status lives in COMMANDS.md (markers: [x] tested, ... in progress, [!] failed, [ ] not started)

Critical environment quirks (do not rediscover these)

1. Hyprland 0.56 Lua config: raw IPC sockets are GONE ($XDG_RUNTIME_DIR/hypr/$SIG/.socket* does not exist). All dispatches must go through: hyprctl dispatch 'hl.dsp.<expr>' where the arg is a valid Lua expression, e.g.:
   • hl.dsp.window.swap({ direction = "l" })
   • hl.dsp.layout("preselect r") — next opened window lands in that split
   • hl.dsp.window.resize({ x = 100, y = 0, relative = true })
   • hl.dsp.window.float({ action = "toggle" })
   • hl.dsp.exec_cmd("some-command") API surface discovered from /usr/share/omarchy/default/hypr/bindings/*.lua.
2. sudo needs pkexec when run from an agent shell (no TTY). Use pkexec pacman -S --noconfirm <pkg> for installs.
3. dsp.window.resize is RELATIVE by default. Exact sizing needs relative = false. Without it, values act as deltas (caused a real bug: window collapsed to 116px). Window-address targeting works everywhere: window = "address:0x..." (discovered from omarchy-hyprland-window-pop).
4. float({ action = "off" }) TILES a floating window — never do this to the host terminal. action = "on" floats it.
5. Custom Lua layouts are native (no plugins): ~/.config/hypr/layouts.lua registers lua:omarchy-grid (deterministic grid, aspect-aware auto mode). Runtime commands go to the ACTIVE layout's handler: hyprctl dispatch 'hl.dsp.layout("set 3 2")' / "auto" / "show". Existing workspaces KEEP their old layout on reload; switch them with hyprctl eval 'hl.workspace_rule({ workspace = "1", layout = "lua:omarchy-grid" })'.
6. Visual verification works: capture_screenshot returns a PNG path; agent can Read image files directly (no external vision API needed).
7. Closing a sibling of the host terminal: siblings can share the host's PID (one ghostty process, many windows), so pid-based guards block them too. Safe close-by-address recipe (all MCP): hypr_dispatch("hl.dsp.window.cycle_next({ next = false })") to move focus off our window -> verify focused pid via desktop_status -> hypr_dispatch('hl.dsp.window.close({ window = "address:0x..." })') — address targeting works; the charset allow-list accepts it. Layout commands go through the ACTIVE layout: hl.dsp.layout("<msg>").
8. Requires: Hyprland 0.56+ with the Lua config bridge, omarchy CLI, wl-clipboard, and Node >= 20.
9. Mouse-focus hazard (input:follow_mouse=1): focus follows the user's cursor, so "focused window" ops can silently re-target mid-command. Mitigations now built in:
   • dispatchTracked() (src/tools/windows.ts) records which window was focused at dispatch + warns if focus moved (window_focus, window_swap, and all no-target fallbacks).
   • Destructive tools accept explicit address/match targets (resolveTarget() in src/hypr.ts): window_resize, window_float_toggle, window_fullscreen, window_close, window_to_workspace. PREFER explicit targeting in agent flows; isSelfClient() guards close on any target.
   • Address-targeted swap works too: hl.dsp.window.swap({ window = "address:0x...", direction = "u" }) (verified live; error "No window to swap with in that direction" when the slot is empty). NOTE: float-toggle off can re-tile a window into a DIFFERENT slot — verify geometry after and restore if needed.