Skip to content

Historical archive

This page records a dated plan, audit, or research context, not a current product contract. Project status distinguishes current source behavior, published releases, and unfinished acceptance gates.

Plan: Summon, the Omarchy experience on macOS, built around one agent

Partly superseded (2026-10-18): projects live in ~/Summon, and Summon is designed as its own thing, not an Omarchy port. Current truth: incubator/summon/README.md and docs/features.md.

Status: v2 (2026-10-17), rewritten after researching Omarchy 4.0. Nothing is built yet. Name: Summon (chosen by Rohi 2026-10-17); repos mac-summon-dev / mac-summon, CLI summon. Decided by Rohi: (1) a Claude Code plugin for agents plus a native Summon Menu app; (2) third-party tools via Homebrew are allowed.

1. What I learned from Omarchy (source: omacom/omarchy 4.0.0.alpha, manual, release coverage)

Omarchy 4.0 "Quattro" (beta since Aug 2026) is no longer just a themed Arch setup. It is built so that one default coding agent can be summoned from almost anywhere, sees the whole system through documented commands, and is handed problems automatically. The pieces:

# Omarchy piece How it works (verified in source)
A1 Default agent, agent-agnostic omarchy default agent <name> picks one of 14 CLIs (Claude Code, Codex, OpenCode, Grok, Copilot, Cursor, Hermes …). Picking one installs it (mise stubs). Nothing is preselected; a first-boot notification invites the choice.
A2 Summon anywhere Super+Shift+Ctrl+A opens the agent in its own terminal. A Quake-style drop-down console (scratchpad) is seeded with the agent the first time it opens. Shell alias a runs it inline. Right-click the bar's agent icon. Menu entries. omarchy agent prompt "<task>" starts it straight into a task.
A3 Unattended by default Every launch uses that agent's own "don't stop to ask" flag (claude --permission-mode auto, codex --approve-for-me …). Starts in ~/Work, never $HOME.
A4 System hands problems to the agent A crash watcher reads systemd-coredump, shows a "Process crashed" notification; clicking it starts the agent with the facts (PID, binary, signal, time) and the diagnose-crash skill, which investigates (backtrace, journal, OOM, recent updates, file mtimes) and offers to report upstream, checking for duplicates first. Per-program mute.
A5 Self-describing system One omarchy CLI routes to 500+ omarchy-* commands; each has metadata headers (summary, args, examples, requires-sudo, hidden). omarchy commands --json gives agents the whole catalog. --help never executes.
A6 Shipped skills, linked into every agent omarchy (customize Hyprland, bar, themes, hooks, capture; "never edit /usr/share/omarchy, edit ~/.config"), omarchy-app (build a native app the house way), diagnose-crash, contributing (file a bug with omarchy debug output). Symlinked into ~/.claude/skills, ~/.codex/skills, ~/.agents/skills ….
A7 Debug bundle omarchy debug: system info, kernel log, journal warnings+errors for this boot, installed packages → view, save, or upload for 24 h. omarchy update analyze logs checks the update log for known failures.
A8 Agents panel in the bar Usage and limits per subscription (5-hour and weekly meters), several accounts per provider with switch and autoswitch at a threshold, sign-in from the panel, and "Make something" starter prompts (new theme, plugin, app).
A9 Theme reaches the agents Theme switch also restyles Claude Code, OpenCode, Pi, Hermes.
A10 Safety rails Plan mode recommended for the skill; omarchy refresh <thing> resets a config to defaults (backs up first); omarchy reinstall configs; filesystem snapshots on every update; a timed passwordless-sudo grant with a red bar indicator while active (critics note it grants every process, not only the agent).
A11 Hooks ~/.config/omarchy/hooks/<event>.d/: theme-set, font-set, post-boot, post-update, battery-low.
A12 Omarchy Menu (Super+Space) One searchable tree, defined in JSONC with when / checked / disabled shell guards and omarchy menu summon <id>: Apps, Learn (keybindings, docs), Trigger (capture: screenshot, recording, OCR text, QR, color picker; toggles: stay awake, notifications, nightlight, screensaver, crash capture; emoji; clipboard history; reminders; share; speed test; hardware), Style (theme, background, font, screensaver, bar look), Setup (default agent/apps, keybindings, monitors, network, input, plugins, security), Install / Remove (AI apps, dev tools, editors, web apps, TUIs, gaming), Update, System (lock, sleep, restart …).
A13 Shell plugins Bar, panels, overlays, the menu, lock screen are all plugins with manifests; first-party vs user plugins in ~/.config/omarchy/plugins/; enable/disable/clone from the menu.
A14 Themes 25 stock themes (tokyo-night, catppuccin, gruvbox, nord, rose-pine, kanagawa, everforest …), each a folder of templates rendered to every app; omarchy theme set; make-your-own guide.
A15 Screensaver A terminal text-effect animation of the logo, set under Style, toggled in Trigger.

The rule behind all of it (quoted in coverage): agents can improve what they can inspect. Readable state, invocable actions, observable results, reliable reversal.

2. The idea for the Mac

Summon = one agent you can summon anywhere on the Mac, which can see and change the whole machine through macctl and our skills, and which the Mac itself calls when something breaks. Making menu bar apps, full apps, screensavers, themes and icons (v1 of this plan) are now things that agent does, not the product itself.

            ┌───────────── summon points ─────────────┐
 hotkey drop-down console · menu bar icon · Summon Menu · Finder/Services "Ask agent"
 · notification "Diagnose" buttons · `a` in any terminal · Shortcuts action
            └───────────────────┬──────────────────────┘
                                ▼
                 summon agent [--prompt …] [--context …]
           (default agent: Claude Code, or Codex, OpenCode … )
                                │ reads skills, calls tools
        ┌───────────────┬───────┴────────┬──────────────────┐
        ▼               ▼                ▼                  ▼
   macctl (settings,  summon CLI    summon-watch     skills: summon,
   profiles, undo,    (commands       (crash/log/health   mac-app, diagnose-
   MCP server)        --json, debug,  watcher → notifies) crash, mac-logs …
                      theme, icon,
                      menu summon)

3. Mapping, Omarchy → Mac

3.1 The agent core (new, the heart of the plan)

Omarchy Summon Notes / macOS facts to verify on the Mac
A1 default agent summon default agent <claude\|codex\|opencode\|…>, stored in ~/.config/summon/defaults/agent. Picking one installs it (Homebrew or npm), Claude Code first. First run: a notification and a menu entry invite the choice; nothing is preselected.
A2 summon Drop-down console: global hotkey (default ⌃⌥⌘`) slides a terminal down from the top; a in it summons the agent (M0 checks whether Ghostty can seed it with the agent directly). ⌃⌥⌘A opens the agent in its own terminal window. Built on Ghostty's macOS quick terminal (keybind = global:…=toggle_quick_terminal) when Ghostty is installed; our own non-activating NSPanel + terminal view as the fallback. Plus: menu bar icon (click = agents panel, right-click = launch), Summon Menu entry, a shell alias, summon agent prompt "<task>". Global hotkeys need no permission with RegisterEventHotKey; Ghostty's global keybind needs Accessibility.
(new) context summon Finder Quick Action / Services menu "Ask agent about this" for files, folders and selected text; a Shortcuts action "Ask Summon agent"; "Fix with agent" buttons inside our own plugins' error states (e.g. mac-network can't reach the router). Quick Actions via an app extension or Automator workflow; Services via NSServices in Info.plist.
A3 unattended Launches use the agent's auto mode, start in ~/Work. Before every summoned session, a checkpoint: macctl snapshot + a git commit of ~/.config (dotfiles repo) so summon checkpoint undo reverts what the agent changed. Question for Rohi below.
A4 auto handoff summon-watch (launchd user agent) watches: ~/Library/Logs/DiagnosticReports and /Library/Logs/DiagnosticReports for .ips crash/hang reports (FSEvents); panics after reboot; brew / summon update failures; launchd jobs that keep exiting non-zero; disk nearly full; battery health. Each → notification with Diagnose (starts the agent with the facts + the matching skill) and Mute this app. .ips files are JSON with a header line; no TCC needed for the user folder, the system folder is readable by admins. UNUserNotificationCenter actions need a signed app bundle (the Menu app owns them).
A5 self-describing summon commands --json lists every command of summon and macctl (macctl list --json already planned) with summary, args, risk, examples. One router, metadata in code. —
A6 skills everywhere Ship skills and link them into ~/.claude/skills, ~/.codex/skills, ~/.agents/skills: summon (customize this Mac: use macctl, never raw defaults; edit ~/.config; hooks; themes; keybindings), mac-app (our existing MacAppArchitecture + MacAppBuild + MacUX, i.e. menu bar app, full app, screensaver templates), diagnose-crash-mac (read .ips, symbolicate with atos, correlate with log show, recent updates, memory pressure), mac-logs (log show/stream predicates for an app, subsystem or time window; Console-level detail), contributing (file an issue on our plugin repos with summon debug). Claude Code also gets the plugin form (commands + MCP).
A7 debug bundle summon debug [--print] [--since 1h]: sw_vers, hardware (system_profiler SPHardwareDataType), log show --last <window> --predicate 'messageType == error', recent .ips list, brew list --versions, login items, macctl doctor + profile drift. View, save, or (opt-in) attach to a GitHub issue. Unified log is huge: always time-boxed and filtered.
A8 agents panel Menu bar panel: default agent, Claude/Codex usage and limits if the CLI exposes them, accounts with switch, and "Make something" starters: new menu bar app, new app, new screensaver, new theme, new icon, fix my Mac. Usage sources differ per CLI; start with what Claude Code and Codex write locally.
A9 theme reaches agents Theme compiler writes a Claude Code theme and Codex/Ghostty colors. —
A10 safety macctl snapshots + undo; dotfiles git checkpoint per session; summon refresh <app> resets one config from defaults (backup first); local APFS snapshot (tmutil localsnapshot) before summon update. No passwordless sudo by default. Offer Touch ID for sudo (pam_tid in /etc/pam.d/sudo_local) instead, so admin steps stay one tap and stay attributable. sudo_local survives macOS updates on 14+.
A11 hooks ~/.config/summon/hooks/<event>.d/: theme-set, post-boot (login), post-update, battery-low, wake, display-change, network-change. Run by summon-watch. Wake/display/network via NSWorkspace and SCDynamicStore notifications.

3.2 The menu and the desktop (Omarchy A12–A15)

Summon Menu (native app, hotkey default ⌃⌥Space, configurable): a searchable keyboard-first tree defined in ~/.config/summon/menu.jsonc (same idea as Omarchy: when / checked guards, summon menu summon <id>), shown as a centered NSPanel with a list. Following our Panel vs Settings rule: the menu bar panel shows live state and actions; app preferences live in the Settings window.

Omarchy section Summon section (first cut)
Apps launch apps (Spotlight index via NSMetadataQuery)
Agent (new top level) Ask agent, Ask about current app/file/selection, Diagnose last crash, Debug bundle, Undo last agent session, Default agent ▸
Learn keybindings overlay (AeroSpace + ours), Summon manual, Apple shortcuts
Trigger Capture: screenshot, recording (screencapture), text OCR (Vision), QR, color picker (NSColorSampler); Toggles: stay awake (caffeinate/IOPMAssertion), Do Not Disturb (Shortcuts), Night Shift, screensaver, crash capture; emoji; clipboard history (our plugin); reminders; share (AirDrop)
Style Theme ▸ (all ported themes), Wallpaper, Font, Screensaver ▸, Icons ▸, Dock and menu bar look
Setup Default agent / browser / terminal / editor, Keybindings, Displays, Network (mac-network), Input, Plugins (enable/disable our menu bar plugins), Security (Touch ID sudo, FileVault status), Profile apply/diff/undo
Install / Remove curated Homebrew catalog: AI (Claude desktop, ChatGPT, LM Studio, Ollama), dev, editors, terminals, browsers, web apps (a site as its own Dock app)
Update summon update: brew upgrade, our plugins, skills, migrations; checkpoint first
System lock, sleep, restart, log out, shut down

Other desktop pieces: AeroSpace tiling with an Omarchy-like ⌥ keymap, JankyBorders, Ghostty, Nerd Font, themed via one theme file (unchanged from v1); our menu bar plugins as the "bar" (mac-network, mac-calendar, plus new ones the agent writes); screensavers as .saver bundles (the Omarchy-style text-effect logo saver is a good first one).

3.3 Creation (v1 scope, now agent jobs)

Kept from v1, done by the agent through the mac-app skill and commands: new menu bar app, new full app, new screensaver (.saver via ScreenSaverView; legacyScreenSaver quirks on 14+ to verify first), theme (theme JSON → macOS, wallpaper, our plugins via ThemeKit, Ghostty, AeroSpace, borders, agents), icon (generate → .icns via iconutil / Icon Composer .icon; place on files, folders, apps, Dock; menu bar order only for our own items, since macOS has no API for other apps').

4. Milestones (re-ordered: agent first)

# Goal Done when
M0 De-risk on Rohi's Mac macctl M1 builds and passes (PR #6). Spike: Ghostty quick terminal seeded with claude on a global hotkey; parse one real .ips; a notification action launches a command from an ad-hoc-signed app.
M1 Summonable agent summon agent, agent prompt, default agent; drop-down console on a hotkey; a alias; per-session checkpoint + summon checkpoint undo; summon skill linked into Claude/Codex.
M2 The Mac calls the agent summon-watch: crash/hang reports → notification → Diagnose with diagnose-crash-mac; mute per app; summon debug; mac-logs skill; hooks runner.
M3 Summon Menu menu bar app + hotkey menu over JSONC tree, Agent + Style + Setup + System sections first; Settings window.
M4 Desktop layer Brewfile apps section, AeroSpace/Ghostty/borders configs with keymap, themes v1 (6 ports) across macOS, our plugins, terminals, agents.
M5 Creation mac-app skill + templates for menu bar app, full app, screensaver; icon make + place. "Make something" starters in the agents panel.
M6 Trigger & Install capture/OCR/QR/color, toggles, web apps, curated install catalog, summon update with checkpoint.
M7 Agents panel + Finder/Services/Shortcuts summon points usage/limits where available, accounts, context "Ask agent about this".
M8 Fresh-Mac profile one command takes a new Mac to Rohi's full setup.

5. Repos and pieces

  • mac-summon-dev / mac-summon: Claude Code plugin (skills, commands, MCP config), summon CLI + summon-watch (Swift), Summon Menu app, themes, templates. Bundle ids local.macplugins.summon*.
  • macctl stays separate (per the "macOS agent CLI plan" thread) and is the only path for Mac settings; Summon depends on it.
  • Our workspace skills become the mac-app skill's source; one copy.

6. Defaults I picked (cheap to change)

  • Claude Code as the first default agent fully wired; Codex and OpenCode next; the launcher table is data so more can be added.
  • Ghostty quick terminal for the drop-down console when present; our own panel only as a fallback.
  • Touch ID for sudo instead of passwordless sudo.
  • Watcher and notifications are owned by the signed Menu app (notifications need a bundle).
  • Everything is built and checked on Rohi's Mac; cloud sessions are Linux without Swift.

7. Decisions

  1. Decided 2026-10-17: auto + undo. Summoned agents run in their auto mode, Omarchy-style, with a checkpoint (macctl snapshot + dotfiles git commit) before each session and summon checkpoint undo. Admin steps still go through Touch ID; destructive macctl actions still need confirmation.

Sources