A fast, native launcher for macOS — apps, files, the web, extensions and AI in one box.
spotcat.ai · English · 简体中文
Press ⌥Space, type, press ↩. Spotcat is a Spotlight / Raycast-style launcher written in Swift and AppKit: the search panel is native, fast and small, while extensions are plain HTML/JS so anyone can write one.
- Apps — fuzzy search with word-boundary and acronym matching (
vsc→ Visual Studio Code), pinyin for Chinese names (wyy→ 网易云音乐), frequently used apps rank first. - Files —
file reportsearches your home folder through the Spotlight index, grouped by folder; wildcards (file *.dmg,douchat*.dmg) and path browsing with Tab completion (file ~/Down⇥). Typing something that looks like a file name suggests a file search. - Web — type a URL (
github.com,localhost:3000) to open it; quicklinks such asgh spotcatorg weather; any text can be searched with your default engine. - AI chat — ask anything from the search box, or continue from an extension's result with its context attached. Streaming replies, Markdown; bring your own key for Anthropic or any OpenAI-compatible provider.
- Extensions — built with HTML/CSS/JS, triggered by keywords or by content (regex). Built-in: URL/Base64 codec and a multi-engine translator (system translation, Google, AI).
- Native feel — non-activating floating panel, global hotkey, light/dark themes, English and Simplified Chinese, launch at login, draggable window that remembers its position.
Download the latest Spotcat-x.y.z.dmg from Releases,
open it and drag Spotcat to Applications. Builds are universal (Apple silicon + Intel),
signed with a Developer ID and notarized by Apple.
Requires macOS 13 Ventura or later. System translation needs macOS 26.
| Key | Action |
|---|---|
| ⌥Space | Show / hide Spotcat (configurable) |
| ↑ ↓ ← → | Move the selection |
| ↩ | Open / run the selected item |
| ⌘↩ | Reveal the selected app or file in Finder |
| ⇥ | Complete a path, or switch folder in file search |
| Esc | Clear the query, leave an extension or chat, then hide |
| ⌘, | Settings |
| Type | Result |
|---|---|
cal |
Apps, extensions and commands |
file invoice · file *.pdf · file ~/Downloads/ |
File search / path browsing |
github.com · gh spotcat · wiki cats |
Open a URL or a quicklink |
%E4%BD%A0 · SGVsbG8= · any text |
Suggestions: decode, translate, Ask AI, web search |
settings / 设置 |
Open Spotcat settings |
Models — add providers (Anthropic or OpenAI-compatible: OpenAI, OpenRouter, DeepSeek, MiniMax,
GLM …) with their API keys and models in Settings › Models and pick a default model. Keys are stored locally in
~/Library/Application Support/Spotcat/models.json (file mode 600) and only sent to their provider.
An extension is a folder with a manifest.json and an index.html:
my-extension/
├── manifest.json features, keywords, content-match rules, permissions
├── index.html the page shown when a feature is opened (runs in WKWebView)
├── locales/ optional translations (en.json, zh-Hans.json …)
└── main.js / style.css
Pages talk to Spotcat through window.spotcat — clipboard, storage, CORS-free fetch
(network permission), language detection, system translation, text-to-speech, the user's AI
provider (ai permission) and spotcat.chat.open() to hand results to the built-in chat.
Extensions are installed on demand from the store in Settings › Extensions. Their source, the
developer docs, the spotcat.d.ts types and an agent skill for building extensions live in
thinkany-ai/spotcat-extensions. To debug your
own, put it in ~/Library/Application Support/Spotcat/Extensions/ (a symlink works) and reload it
from Settings › Extensions; open-source extensions can be submitted there for listing in the store.
Requirements: macOS 13+, Swift 5.9+ (Xcode or the Command Line Tools), and the macOS 26 SDK to compile the system-translation code path.
git clone https://github.com/thinkany-ai/spotcat.git
cd spotcat
make run # build → build/Spotcat Dev.app (ad-hoc signed) → launch| Command | What it does |
|---|---|
make build / make debug |
Build build/Spotcat Dev.app for this Mac |
make universal |
Universal (arm64 + x86_64) build |
make release |
Sign, notarize and package DMG + ZIP into dist/ (maintainers) |
make icons |
Regenerate icons from Resources/Icon/*.svg (needs brew install librsvg) |
SPOTCAT_CHANNEL=release make build |
Build the release flavor build/Spotcat.app locally (unsigned) |
Local builds are Spotcat Dev: a separate bundle ID (ai.thinkany.spotcat.dev), data folder
(~/Library/Application Support/Spotcat Dev), default hotkey (⌥⇧Space), an amber icon and a DEV badge in the panel, so
developing never touches an installed release and both can run side by side. make release
(and CI) build the regular Spotcat.
With only the Command Line Tools installed, SwiftUI macros are unavailable — use
ObservableObject instead of @State / @Observable.
Sources/Spotcat/
├── AppDelegate.swift entry point, menus, hotkey
├── LauncherController.swift search panel: queries, sections, navigation
├── ResultsGridView.swift icon grid FileTreeView.swift file results
├── AppIndex.swift · FileSearch.swift · Quicklinks.swift · FuzzyMatcher.swift
├── Extensions/ manifest model, loader, host view, native API
├── Chat/ · AIService.swift built-in AI chat and the OpenAI-compatible client
├── Web/ WKWebView bridge and the injected window.spotcat runtime
└── Settings/ settings window, store, shortcut recorder
Resources/ Info.plist, icons, chat page
scripts/ bundle, release, CDN publish, icons, release secrets
Maintainers release with one command:
./scripts/new-version.sh 0.3.0 # or 0.3.0-beta.1 for a pre-releaseIt bumps the version in Resources/Info.plist, commits, tags v0.3.0 and pushes.
release.yml then builds a universal binary, signs it with the
Developer ID certificate, notarizes and staples the app and DMG, and publishes a GitHub Release
with the DMG, ZIP and SHA-256 checksums. The same steps run locally with make release. Signing secrets are configured
once with scripts/setup-release-secrets.sh.
Stable releases are then mirrored to Cloudflare R2 (https://cdn.spotcat.ai): installers first, then
the latest.json feed the in-app updater reads; the website links to https://cdn.spotcat.ai/Spotcat.dmg.
This needs the CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY secrets, or run
./scripts/publish-cdn.sh locally with a logged-in wrangler.
Issues and pull requests are welcome — see CONTRIBUTING.md. Please report security problems privately as described in SECURITY.md.
Spotcat is licensed under AGPL-3.0 © 2026 ThinkAny, LLC. A commercial license without the AGPL's copyleft obligations is available — contact support@thinkany.ai.
The official extensions, extension docs and spotcat.d.ts in
spotcat-extensions are MIT-licensed, so
third-party extensions can use them under any license.