✦ Cantrip

A keyboard-first launcher with an AI agent built in.

Open apps, calculate, ask questions, or give an agent a task. Cantrip connects to Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, or an OpenAI-compatible model server on macOS. AI access is separate: bring an authenticated backend or your own model server. Provider charges and usage limits still apply.

User Guide · Mac setup · Windows setup

Platforms

Platform	Requirements	Status
macOS	macOS 14+, Xcode Command Line Tools	Full Swift app; open with Option+Space
Windows	Windows 10/11 x64; Node.js 20.19+ for source builds	Electron app; open with Alt+Space

Mac builds are Universal (arm64 + x86_64): Cantrip runs natively on Apple silicon without Rosetta and retains Intel Mac support. Packaging rejects native bundled components missing either architecture or requiring a newer macOS than the app declares. The minimum remains macOS 14; it is not a maximum version. macOS 26 is supported, and builds with Xcode 27 retain that same minimum for macOS 27 readiness. macOS 27 runtime compatibility still needs confirmation on that OS; see macOS version support. Separately installed AI CLIs, their runtimes, MCP tools, and local model servers must also support your Mac; see Rosetta compatibility.

Windows supports app launching, math, Claude/Copilot/Codex, screen capture, and plugins. It does not yet support local models, persistent session tabs, memory, voice, council, or Cantrip Remote. See the feature comparison.

What it does

The macOS app includes:

• Launcher and terminal: open apps, search files through Spotlight, calculate, convert units, and run explicit shell commands.
• AI workspace: streaming answers, file/screenshot attachments, voice, renameable, lockable, reorderable session tabs, recoverable runs, and a terminal per session. Names, close-protection locks, and tab order sync to Cantrip Remote and AgentGateway. Drag a session tab onto another to move it, or use Move Tab Left/Right in its right-click menu. The Remote connection tab stays pinned first. Order survives restarts without switching conversations or interrupting work.
• Automatic sending: a separate, tool-free model call interprets busy-run messages as context, corrections, or follow-ups. Uncertain decisions queue safely; manual Queue/Redirect/Inject overrides remain available.
• Live context: local Copilot and Claude Code can accept Inject messages without stopping their current work, including from AgentGateway and Mac/browser Remote. Copilot uses a persistent native SDK session per tab; accepted context is never blindly resent if its acknowledgement is lost. Requires Node.js and a recent Copilot CLI with its matching bundled SDK/runtime.
• Agent actions: commands and file edits with backend-specific permissions; inspect tool activity and file diffs.
• Memory and council: editable Markdown memory and multi-model answers. AgentGateway's Cantrip Memory menu browses saved facts, preferences, notes, and session logs read-only, with search and paged file contents.
• Copilot usage: account-wide AI credits used / total, reset date, and additional usage in the Mac's Usage panel and AgentGateway's header beside the lane picker. Reads your existing Copilot login without sending a prompt; credentials stay on the Mac.
• Long prompts: compact, plain-text previews with Read full prompt, paged reading, and full-text copy/download in Mac and Remote. The submitted text stays intact. Memory retrieval uses bounded, deduplicated query terms and runs off the UI thread; large Remote responses are encoded off-thread.
• Remote control: use the Mac's sessions from AgentGateway on iPhone/iPad, another Mac, or a browser. Recent messages load with full text and tool details; scrolling up automatically pages back through ten earlier prompt-response groups, counting those already loaded. Beyond that, Load more messages retrieves earlier history. Opening a tab or polling never prefetches history; failed automatic loads pause for manual retry. Page and cache boundaries retain the prompt before its responses, even when a large answer exceeds the soft page limits. Mac Remote uses an expanded, vertically scrollable tab list on the left; main Cantrip and ordinary browser tabs stay across the top. Remote tab lists keep their scroll position during refreshes. Mac Remote and browser tabs support drag reordering, move buttons in tab settings, and Option/Alt + arrow keys (up/down in the sidebar, left/right in the top strip). AgentGateway's drawer/sidebar provides drag handles and Move Tab Up/Down actions. Reordering requires the updated host's supportsTabReordering capability; private tabs remain hidden from Remote. Native Mac tab labels use dedicated mouse handling, so dragging a tab does not move the launcher window; dragging the window background still works. Mac Remote shows a pulsing brain, live activity and queued counts in the sidebar, with the selected session's status pinned near the message box. AgentGateway includes tappable uploaded-image thumbnails and full-screen viewing. Native clients support paired LAN connections; a saved Tailscale Serve URL is preferred even on the local network. Automatic routing uses LAN if Tailscale is unavailable and restores Tailscale with two confirmed read-only probes. Bounded reads and coalesced web refreshes avoid stalled request backlogs, without switching healthy Tailscale connections to LAN or replaying sends; Tailscale-only mode is also available. AgentGateway can display and remove queued prompts. Host diagnostics separate lightweight /health liveness from authenticated session readiness, with content-free request timings and bounded response writes.
• Durable runs: journal encoding, writes, and synchronization use an ordered background writer. Run completion and Remote mutation acknowledgements wait for saved events; storage failures are surfaced instead of reporting success.
• Extensions: dashboards, MCP tools, custom slash commands, and a cantrip command for asking questions from Terminal.

Capabilities depend on the backend. The current Local Model backend does not receive file/image attachments or screen captures; tool use requires a compatible model and action permissions.

Quick start

macOS

Install Xcode Command Line Tools and set up one AI backend, then run:

mkdir -p ~/Coding
git clone https://github.com/FlyingViet/cantrip.git ~/Coding/Cantrip
cd ~/Coding/Cantrip
./install.sh

The installer builds and signs Cantrip.app, installs the cantrip CLI, and opens the app. A signing-certificate password dialog may appear. Keep the checkout: rebuilds and updates use it.

1. Press Option+Space, then open the gear.
2. Select your Backend and review the permissions and context settings below.
3. Type a question and press Return. If an app suggestion is selected, Command+Return sends to the AI instead.

For prerequisites, sign-in, and launch-at-login instructions, see Mac setup. Already installed? Use the update guide.

Windows

Follow Windows setup to install a release that includes a Windows installer, or run from source. If Alt+Space is occupied, Cantrip falls back to Ctrl+Space and reports the conflict.

Permissions and privacy

On Mac, Act on my behalf is off by default. For your first question, leave it off, keep Claude Permissions at Safe, and leave Copilot Allow all tools off. These controls are separate; explicit shell commands also execute independently of the action toggle.

Memory, document search, calendar, and location context are enabled by default on Mac, subject to OS permissions where required. Review Settings before sharing sensitive work. Screen context and Remote hosting are off by default. Private mode suppresses Cantrip conversation persistence, but does not prevent tool writes, image caches, or backend/provider logging. Read permissions, privacy, and memory.

Learn more

Task	Guide
Choose a backend or local model	Backend setup
Launch apps, run commands, or use voice/CLI	Everyday tasks
Attach files, screenshots, or selected text	Files and screen context
Resume work or compare models	Sessions and council
Pair AgentGateway, send photos, or connect another Mac	Remote control
Add dashboards, tools, or slash commands	Extensions and skills
Find a shortcut or fix a problem	Keyboard reference / Troubleshooting

Development

Platform	Source	Build / test
macOS	Sources/Cantrip/	From the repo root: make build, make test
Windows	windows/	From windows/, run npm ci, then npm run build / npm test

See the plugin reference and Windows parity checklist for implementation details.

App artwork

The Cantrip mark is a pearl-violet C casting a warm golden spark: a small, useful spell on a midnight-amethyst background. The same mark is used by the Mac and Windows apps and the AgentGateway iOS companion.

Run make artwork on macOS to regenerate the artwork using native CoreGraphics and ImageIO, with no fonts, downloaded images, or extra dependencies. Edit Scripts/generate-artwork.swift, not the generated assets:

Asset	Use
Resources/Cantrip.svg	Scalable full-color artwork
Resources/CantripIcon.png	Opaque, full-bleed 1024px iOS master; let iOS apply its own corner mask
Resources/AppIcon.png / AppIcon.icns	Mac icon with rounded tile and transparent desktop padding
windows/assets/Cantrip.ico	Windows app/installer icon at 16, 24, 32, 48, 64, 128, and 256px

To sync the companion in a sibling checkout, run cp Resources/CantripIcon.png ../Hermes/Sources/Assets.xcassets/AppIcon.appiconset/Icon-1024.png. Normal app builds use the checked-in PNG/ICO assets; make app regenerates the ignored ICNS as needed without requiring artwork regeneration.