espanso control

espanso-control

Espanso is a text expander configured entirely through YAML and driven by a CLI whose subcommands have shifted across the 2.x releases. Worse, it fails silently: if the daemon is not running, the service is not registered, or macOS has not granted Accessibility permission, expansions simply do not fire. No error, no log line, nothing to search for.

This plugin teaches Claude the CLI properly and adds a read-only preflight that tells you which of those it is.

Setup

/plugin marketplace add roypadina/padina-claude-code-plugins
/plugin install espanso-control@padina

Requires macOS and Espanso (brew install --cask espanso), with the Accessibility permission granted by hand — nothing in this plugin can grant it, and nothing outside System Settings can. bash and curl are used by the doctor script; both ship with macOS.

What you get

Feature	Mechanism
/espanso-doctor — six-check preflight	slash command → scripts/espanso-doctor.sh
The Espanso CLI and match/config YAML, for Claude	skill + references/yaml-patterns.md

No hooks, no agents, no MCP server. Nothing runs unless you ask for it.

/espanso-doctor

Six checks, each degrading independently — one failing does not abort the rest:

Check	How
On PATH	command -v espanso
Installed version vs. latest stable	espanso --version against the latest GitHub release
Daemon actually running	espanso status
Service registered (survives reboot)	espanso service check
Accessibility permission	reported as unverifiable — see below
Config path	espanso path

The version check calls GitHub with a 5-second timeout and degrades to an informational line when you are offline, rather than failing the run.

It only reports. The script never restarts the daemon, registers the service, edits YAML, or installs anything. Fixes are printed as commands for you to run.

Why Accessibility is reported as "unverifiable"

Because it genuinely cannot be checked from an unprivileged shell. Querying TCC.db returns zero rows whether or not the grant exists, so a script that read that as "not granted" would be wrong exactly when it mattered most — a working setup reported as broken. The doctor says it does not know, and tells you where to look: System Settings → Privacy & Security → Accessibility.

--selftest

/espanso-doctor --selftest

Runs 15 offline assertions against the script's own parsing functions (parse_version_output, parse_status_output, parse_service_check_output, parse_config_path, extract_tag_name, strip_v, version_compare) using canned strings. No network, no espanso binary needed — so you can check the doctor itself is sound even on a machine without Espanso installed.

The skill

Verified against Espanso 2.4.0:

• A quick-command table — status, restart, service registration, espanso path, package management.
• The config-path layout: where match/ and config/ live, and which file a snippet belongs in.
• A YAML editing workflow with a safe-editing checklist, in references/yaml-patterns.md: trigger/replace shapes, multi-trigger matches, date and shell variables.
• Hub package management (espanso install, list, uninstall, package update).

When something looks wrong, the skill tells Claude to run /espanso-doctor first rather than guessing at a fix.

The skill flags its own limits honestly: keys under config/default.yml were not re-verified in the 2.4.0 pass and are marked as such, rather than presented as checked.

Uninstalling

/plugin uninstall espanso-control@padina

Your Espanso install and config are untouched — this plugin never wrote to them.