SummonOS: the agentic layer for the Mac

SummonOS gives coding agents live Mac context, a native menu bar interface, and recoverable changes to supported macOS settings. It works with the agents you already use; it does not replace or sandbox them.

Documentation and wiki · Get started · Features · Troubleshooting · Status

SummonOS is a preview, not a production-qualified recovery system. The latest numbered release checked for this documentation is v0.2.5, published as a prerelease on November 11, 2026; see status and verification limits.

What it does

• Live context: summon context reports hardware, power, storage, network, displays, appearance, permissions, running apps, installed agents and recent crashes. Choose which sensitive fields agents receive.

• Agent integration: summon connect installs supported MCP registrations, instruction blocks and session hooks. summon mcp exposes read tools and journaled settings/checkpoint actions to connected agents.

• Ask from anywhere: ⌃⌥⌘A opens your default agent with the frontmost app, window and permitted selection, browser and Finder context. ⌃⌥Space opens the searchable Summon panel.

• Settings recovery: macctl snapshots supported changes; Summon checkpoints combine those settings with successfully captured configuration. Undo is not a backup of arbitrary files or external actions.

• Whole-Mac themes: one command coordinates wallpaper, appearance, native accent, terminal and supported editor configuration. Theme application records a checkpoint and tracks the files it creates for undo.

• Native app tools: private local projects, nine starter templates, scheduled tasks, crash diagnosis, an Activity window, an Updates window, and Siri/Shortcuts actions.

The feature reference describes the exact scope. Read the security and recovery model before granting unattended agent execution.

Related MCP server: mcp-macos-toolkit

Install

On macOS 15 or newer:

curl -fsSL https://raw.githubusercontent.com/RohiRIK/SummonOS/main/install.sh | bash

The remote installer downloads the newest numbered release, including previews but excluding the rolling edge release, verifies SHA256SUMS, and installs Summon.app in ~/Applications and the commands in ~/.local/bin. A packaged release needs no Xcode. If no release can be selected, the installer attempts a source build, which requires Git and Swift 6; current staging also uses Python 3. Xcode supplies App Intents metadata.

Preview builds are ad-hoc signed and not notarized. Browser-downloaded archives may need System Settings › Privacy & Security › Open Anyway. Accessibility can need reauthorization after an update.

summon doctor
summon connect --dry-run
summon connect
open "$HOME/Applications/Summon.app"

Connecting changes agent configuration and instructions; review the dry run first. Files are backed up. To let an agent install SummonOS, give it the installation playbook.

Update

summon update --check
summon update

Self-update starts with 0.2.0. In 0.2.0 the panel's update row was broken: use the CLI once; 0.2.1 fixes that row. Current builds use a dedicated Updates window. On 0.1.x, rerun the installer. Themes, projects and settings are preserved. Installation options and channels cover pinned versions, opt-in edge builds and source checkouts.

Try it

summon context                         # read this Mac's context
summon agents                          # discover agents and installation methods
summon default agent claude             # choose an installed agent
summon panel                           # open the native searchable panel
summon agent prompt "Explain this project"
summon checkpoint list                 # inspect recovery points
summon commands --json                 # machine-readable command catalog

Agent prompts can start an agent that runs commands. Review the execution policy in Settings › General; new installations use the agent's own approval controls. No command above is a claim that arbitrary agent work can be rolled back.

Project map

Plugin implementations are separate repositories; the registry records their status, not a fresh audit of those apps. Summon-created apps live privately in ~/Summon/Apps, not in the workspace registry.

Build and contribute

git clone https://github.com/RohiRIK/SummonOS
cd SummonOS
./install.sh                    # builds and installs this checkout, not the latest release
tools/check-workspace.sh        # workspace hygiene and generated documentation indexes

Use selected Xcode with Swift 6 for the full build/test flow and Siri/Shortcuts metadata. The bundler can omit those actions with Command Line Tools alone. Build caches belong in ~/Library/Caches/macplugins, outside the synced checkout. The widget template has a small Xcode project for its extension; the rest of the app/template packages use SwiftPM.

See Contributing for targeted tests and CI, documentation maintenance for the wiki build/preview, and Security for private vulnerability reporting. Agents follow AGENTS.md.

Workspace plugins use private <name>-dev repositories for full development history and public <name> repositories for clean snapshots. tools/mp clone --all populates the gitignored plugins/ directory.

• Select Xcode and authenticate gh.

• Install Bun and jq for workspace/Xcode MCP tooling.

• Configure the gitignored tools/private-patterns.txt before publication or demo recording.

• tools/publish-public.sh scans snapshots before publishing; never make a dev repository public.

• README art is generated by python3 tools/readme-art.py; use --check to detect stale artwork.

Publishing an application release and deploying the wiki to Vercel are separate maintainer actions. The documentation domain is sumonos.rohi-lab.org.

License and credits

MIT. Omarchy is research and inspiration for an agent-centered desktop, not a source to copy wholesale: background. Community palettes and adapted material are credited in third-party notices. Vendored SwiftUI/concurrency skills retain their MIT licenses.