Getting started¶
Requirements¶
- macOS 15 or newer. Liquid Glass is used only on macOS 26 and later; older systems use native materials.
- An installed coding agent and any account/login that agent requires. SummonOS does not provide the model.
- Internet access for downloading releases, connecting to model services and installing tools. Local context, the panel and local settings operations do not require a cloud service.
- Source builds only: Git, Swift 6 and Python 3 for current staging. Use selected Xcode for the full build/test flow and App Intents metadata. The bundler can omit Siri/Shortcuts actions with Command Line Tools alone; that is not equivalent to a fully qualified app build. Packaged releases do not need Xcode.
Read the status page before treating development features as available in a downloaded release.
Install the preview¶
The remote installer selects the newest numbered GitHub release, including prereleases but excluding edge,
verifies the archive against SHA256SUMS, installs it, and runs summon doctor. If no release is selectable
(including when GitHub is unreachable), it attempts a source build instead. Review the installer before
executing it if your policy forbids piping downloads directly to a shell.
| Installed item | Location |
|---|---|
| Menu bar app | ~/Applications/Summon.app |
| Commands | ~/.local/bin/summon, ~/.local/bin/macctl |
| Themes and agent configuration | ~/.config/summon/ |
| Events, logs and recovery state | ~/.local/state/summon/ |
| Your private app projects | ~/Summon/Apps/ |
If summon is not found, add ~/.local/bin to your shell's PATH and open a new terminal:
export PATH="$HOME/.local/bin:$PATH"
summon version
summon doctor
open "$HOME/Applications/Summon.app"
The app's welcome flow helps you select an agent, check its login and configure Accessibility. You can reopen it from Settings. Preview releases are ad-hoc signed, not notarized. For a browser-downloaded archive, macOS may require System Settings › Privacy & Security › Open Anyway; see troubleshooting.
Choose and connect an agent¶
First inspect what is installed:
For example, if Claude Code is installed:
With no agent argument, summon connect considers all supported connection targets. It registers MCP where
supported and writes a marked instruction block; supported clients also receive session hooks. Existing files
are backed up. Restart or reload the agent so it reads the new configuration.
The launchable agent registry and the connection targets are different lists. Consult the agent reference and connection research, not an assumed one-to-one mapping. Pi uses instructions/skills rather than a native MCP registration.
To preview removal and then remove only Summon's integration:
Disconnecting is not uninstalling the app and does not undo work the agent performed.
Review authority and context¶
In Settings › General, review Agent execution. New installations retain the agent's own approval controls. Existing configured installations can retain unattended execution; inspect rather than assume.
In Settings › Agents, choose which context fields are shared. The CLI exposes the same visibility choices:
summon context fields
summon context hide selected-text
summon context hide browser-page
summon context
Selected text/window titles use Accessibility when already granted; browser and Finder integration can require Automation permission for each target app. Denied permissions omit those fields rather than granting them.
A checkpoint covers supported settings and successfully captured config, not every command an agent can run. The security and recovery model is the recovery contract.
First actions¶
- ⌃⌥Space opens the searchable panel; Escape dismisses it.
- ⌃⌥⌘A opens the default agent with permitted screen context and asks it to wait for your question.
- Settings… / ⌘, opens preferences separately from the panel.
- Activity shows sessions and recorded task outcomes.
- Updates opens the dedicated update window; installing is an explicit action.
For an inspection-only CLI tour:
Applying a theme changes the Mac and supported tool configuration. summon theme set <slug> prints its
checkpoint undo command. Review any checkpoint warnings; they indicate recovery coverage may be incomplete.
Installation options¶
Pass remote-installer options after bash -s --:
curl -fsSL https://raw.githubusercontent.com/RohiRIK/SummonOS/main/install.sh | bash -s -- --version v0.2.5
| Option | Behavior |
|---|---|
--version vX.Y.Z |
Install a particular numbered release. |
--channel stable |
Default remote selection: newest numbered release, including previews; not a production certification. |
--channel edge |
Install the separately published rolling edge artifact; not necessarily the newest branch or tag. |
--from-source |
Build source; a remote run uses SUMMONOS_HOME and SUMMONOS_REF (default main). |
--connect |
Run summon connect after installation without asking. |
--yes |
Disable prompts; does not imply --connect. |
--channel edge cannot be combined with --version or --from-source. Running ./install.sh inside a source
checkout builds that checkout, unless a release/edge option explicitly selects a package.
Update an existing installation¶
The app checks at launch and daily when enabled. Current builds open the Updates window for installation and relaunch the app afterward. A CLI install asks you to restart the app. In 0.2.0, use the CLI because the panel's update row does not work; on 0.1.x, rerun the installer once.
An explicit summon update --channel edge remembers that channel when installing. Adding --check only
checks it and does not change the saved channel. Switch back with summon update --channel stable.
Custom themes, projects and settings are preserved, but ad-hoc updates can require Accessibility reauthorization.
Next¶
Feature reference · macctl guide · Troubleshooting · Build native apps