Powered by caffeine and questionable life choices.
SummonOS is an experiment in what a Mac feels like when an agent is part of the system, not a guest in a browser tab. You summon one coding agent from anywhere. The Mac hands it crashes and hangs. It takes a checkpoint before each session, with recovery for supported settings and successfully captured config files. It changes system settings through a CLI that snapshots every change, and when you need a small tool, it builds a real native app in Swift that launches instantly and works offline.
It is an idea in progress, not a finished product. Parts of it work today; plenty does not. Read the security and recovery model before enabling unattended agents.
On a Mac with macOS 15+ and Xcode (or the Command Line Tools) with Swift 6:
curl -fsSL https://raw.githubusercontent.com/RohiRIK/SummonOS/main/install.sh | bash
Or let your agent do it. Paste this into Claude Code, Codex or any coding agent on your Mac:
Install SummonOS by following https://raw.githubusercontent.com/RohiRIK/SummonOS/main/docs/install-ai.md
The installer builds Summon and macctl from source, puts Summon.app in ~/Applications and summon and
macctl in ~/.local/bin, then runs summon doctor. Run it again to update. Then:
summon default agent claude # or codex, opencode, agy, pi, ...
summon agent prompt "summon, give my Mac a calm dark theme"
| | Summon | One coding agent you summon from anywhere (⌃⌥⌘A, or the Summon menu on ⌃⌥Space). Crashes and hangs are handed to it, every session starts with a checkpoint you can undo, recurring tasks run while you are away, and it builds apps, themes, wallpapers and icons from templates. |
| | macctl | The CLI agents use to read, set, diff, apply and undo macOS settings (Dock, Finder, keyboard, appearance, wallpaper), with a snapshot before every change. |
| | Agent skills | How agents here plan, design, build and verify native Mac apps: MacAppArchitecture ,MacUX ,LiquidGlass , five historical design styles,MacAppBuild ,PortLinuxWidget (which one when ). |
Every feature, command by command: docs/features.md.
Real apps, each in its own repo, built by agents with the SummonOS skills and Summon's templates.
| App | What it does | |
|---|---|---|
| mac-breathe | A breathing guide: a soft orb grows and shrinks with your breath, from the menu bar or as a full-screen focus window. | |
| mac-calendar | Menu bar calendar with your events, reminders, natural-language Add Event and Hebrew dates. | |
| mac-network | Wi-Fi, latency, throughput and IP settings from the menu bar. | |
| end-of-day | Closes your work apps when the workday ends: a schedule, a 30-second countdown you can snooze, and a streak. Made with summon project new . |
I spent a while living in Omarchy on Linux, where the whole desktop is one opinionated, keyboard-first experience you can reshape in minutes. SummonOS asks what that feels like on a Mac when the center of the experience is an agent, and what happens to "apps" when making a small one takes minutes. More on how it started: rohi-lab.org/blog/omarchy.
Each step names the skill or script that owns it: docs/workflow.md.
Issues, ideas and pull requests are welcome, from people and from agents. Start with
CONTRIBUTING.md; the rules every agent follows are in AGENTS.md.
Security problems go privately through SECURITY.md.
git clone https://github.com/RohiRIK/SummonOS && cd SummonOS
./install.sh # builds and installs this checkout
tools/check-workspace.sh # the checks a pull request must pass
| Path | What it is |
|---|---|
install.sh |
The one-line installer (Summon + macctl); agents use docs/install-ai.md |
incubator/summon/ |
Summon: the menu app, the summon CLI, themes, skills, app templates |
macctl/ |
The settings CLI, its profiles and tests |
.claude/skills/ |
Agent skills for building Mac apps |
docs/ |
An Open Knowledge Format bundle:features ,app lifecycle ,tools ,plans ,research ,update log |
tools/ |
Workspace scripts: checks, plugin registry ( mp ), publish, release, previews, README art, docs index (docs/tools.md ) |
examples/ |
menubar-starter , the skeleton new workspace apps start from |
plugins.json |
Registry of the workspace apps; plugins.md is generated from it |
AGENTS.md |
Rules for agents and people: stack, workflow, conventions, publishing. CLAUDE.md points to it. |
tasks/ |
todo.md (current plan only) andlessons.md (rules learned from corrections) |
Maintainer setup (publishing apps to their own repos) #
Each workspace app lives in its own pair of repos (private <name>-dev + public <name>), cloned into
plugins/<name>/, which is gitignored here.
- Xcode (with the Xcode MCP bridge,
.mcp.json) selected viaxcode-select, andghsigned in. - Bun and
jq, fortools/mp,tools/xcode-mcp.tsandtools/render-previews.sh. tools/mp clone --allclones each app's dev repo intoplugins/<name>/.- Optional:
.claude/skills/MacPluginPlaybookis a per-machine symlink to a private skills library (gitignored). - Create
tools/private-patterns.txt(gitignored): one regex per line for private values (email, home subnet, MAC addresses, hostnames).tools/publish-public.shrefuses to run without it, andtools/record-demos.shuses it to scrub demo transcripts.
Build caches go to ~/Library/Caches/macplugins/<name>, never .build/ inside a synced folder.
The art in docs/assets/ is generated, so it stays consistent and renders on GitHub's web and mobile apps:
python3 tools/readme-art.py # write docs/assets/*.svg (hero, wordmark, diagram, icons, pill, terminal cards)
python3 tools/readme-art.py --check # exit 1 if a committed SVG is stale
tools/record-demos.sh # on a Mac: re-record macctl's demo transcripts, cards and GIF
SummonOS uses Summon's ring mark and colors, shared through incubator/summon/design/brandkit.py;
Summon's PNG icon, banner and wordmark are made by incubator/summon/design/generate.py. The app screenshots
under "Built with SummonOS" come from each app's own repo.
MIT. The vendored skills swiftui-expert-skill and swift-concurrency-pro are MIT and keep their
own LICENSE files; upstream notices are in each app's THIRD_PARTY_NOTICES.md.