macspanso
Editing match/base.yml shouldn't require a text editor.
A native macOS menu bar app for managing
espanso
text expansions — no YAML required.
brew install --cask jeffcaldwellca/tap/macspanso
Homebrew automatically installs espanso if it isn't already present.
How it works
From zero to your first text expansion in about two minutes.
-
1
Install
Run a single
brew installcommand — Homebrew pulls in espanso too. -
2
Open the manager
macspanso lives in the menu bar. Click its icon and choose Open Match Manager.
-
3
Add a match
Type a trigger and its replacement, hit save, and espanso expands it everywhere.
What it does
macspanso is a free, open-source, native macOS menu bar app for managing espanso text expansions — a focused GUI for the parts of espanso you actually touch every day.
Create matches
Type a trigger, type the replacement, save. No YAML, no terminal.
Form matches
Add [[placeholders]] and espanso will show a fill-in popup before expanding.
Variables
Attach date, shell, clipboard, random, and other variable types to any match.
Multi-trigger & regex
One match, many triggers — or match by regular expression for maximum flexibility.
File tree view
Browse matches by YAML file or as a flat list. See exactly where each match lives.
External edit detection
A banner appears when a file changes outside the app, with reload or keep options.
Menu bar controls
Enable, disable, or restart espanso without leaving the keyboard.
Search
Filter matches instantly by trigger, replacement preview, or label.
Installation
Currently on v1.4.0 — see the changelog for what's new.
Homebrew recommended
brew install --cask jeffcaldwellca/tap/macspanso
Direct download
Download the latest .dmg from the Releases page, open it, and drag macspanso to your Applications folder.
Frequently asked
What is macspanso?
macspanso is a free, open-source macOS menu bar app that gives espanso a native graphical interface. It reads and writes the same YAML match files espanso uses, so you can create, edit, search, and organise text-expansion matches without touching a text editor or the terminal.
Is macspanso free?
Yes. macspanso is completely free and open source under the MIT license. There is no paid tier, no account, and no telemetry.
Where are my matches stored?
macspanso edits the same YAML files espanso reads — typically ~/Library/Application Support/espanso/match/. Nothing is moved, copied, or duplicated; we just give you a nicer way to edit those files.
Will macspanso conflict with editing config files directly?
No. macspanso watches the espanso config directory and detects external edits. If a file changes while macspanso has it open, a banner gives you the choice to reload from disk or keep your in-app changes.
Does it work with espanso's iCloud / Dropbox sync?
Yes — macspanso operates on whatever path espanso is configured to use. If you've moved your match folder into iCloud Drive or another sync provider, macspanso will edit the synced files in place.
Does macspanso send anything over the network?
No. The app reads and writes local YAML files and controls the local espanso process. There is no telemetry, no analytics, and no network calls.
How do I uninstall macspanso?
If you installed via Homebrew: brew uninstall --cask jeffcaldwellca/tap/macspanso.
If you installed via .dmg: drag macspanso from /Applications to the Trash. Your espanso matches are not affected — they live in espanso's config directory and stay put.
Is macspanso open source?
Yes — MIT licensed. View the source on GitHub, file an issue, or open a PR.