SnipExpand

Fast, config-based text expansion for Linux and Wayland. First-class support for Omarchy and Hyprland.

Features

• System-wide, clipboard-free expansion
• Immediate or terminator-based expansion
• Plain text and multiline replacements
• Cursor placement with $|$
• Recursive YAML configuration with automatic reload
• Multiple triggers for one replacement
• Regex triggers with named captures
• Reusable nested snippets and date variables
• Configurable word boundaries and case propagation
• Search labels and terms for picker integrations
• Immediate Backspace undo for simple expansions
• Application exclusions and per-application profiles
• Pause and resume controls through the CLI, IPC, and Omarchy plugin
• Deliberate duplicate-trigger selection by source
• Persistent Wayland injection with a uinput fallback
• Strict validation and diagnostics

Why SnipExpand?

Text expansion on Omarchy and Hyprland is still unreliable or awkward. Compare SnipExpand with the alternatives below.

Alternatives

Requirements

Omarchy includes everything SnipExpand needs by default. On other Wayland systems, you need:

• libxkbcommon and Wayland client libraries
• Read access to /dev/input/event*, usually through the system input group
• wtype for the Unicode fallback path

Install

Install from crates.io:

cargo install snipexpand

Prebuilt x86_64 and aarch64 binaries are available from GitHub Releases.

Set up

snipexpand install

This creates any missing starter files without overwriting your config, then starts the service and enables it for future sessions. Run snipexpand doctor if setup or expansion does not work.

AI agents

SnipExpand installs an AI skill at ~/.config/snipexpand/SKILL.md. Point your coding agent at it and describe what you want:

Read ~/.config/snipexpand/SKILL.md, then set up my SnipExpand snippets.

The skill teaches agents how to scaffold and edit match files, change settings, use the CLI, validate changes, and check the running service. You can manage your entire setup this way without learning the commands below.

Add your first snippet

Add an expansion from the command line:

snipexpand add --label 'Email address' --search-term contact ';mail' 'user@example.com'

Match files

For more control, create or edit a YAML file below ~/.config/snipexpand/match/. SnipExpand offers best-effort compatibility with Espanso's YAML match format:

# Match files reload when saved.
global_vars:
  - name: today
    type: date
    params:
      format: "%Y-%m-%d"

matches:
  # Multiple triggers, one replacement
  - triggers: [";mail", ";email"]
    label: "Email address"
    search_terms: [email, contact]
    replace: "user@example.com"

  # Whole-word matching and multiline text
  - trigger: ";sig"
    label: "Email signature"
    word: true
    replace: |
      Best regards,
      Your Name

  # $|$ marks the cursor position after expansion.
  - trigger: ";function"
    replace: |
      fn example() {
          $|$
      }

  # Insert a formatted date
  - trigger: ";today"
    replace: "{{today}}"

  # Named regex captures become replacement variables.
  - regex: "issue-(?P<number>\\d{3})"
    replace: "Issue #{{number}}"

  # Reuse another snippet without running commands.
  - trigger: ";name"
    replace: "Your Name"

  - trigger: ";greeting"
    replace: "Hello from {{name}}"
    vars:
      - name: name
        type: match
        params:
          trigger: ";name"

Settings

Edit ~/.config/snipexpand/config.yml:

# Choose when expansion happens.
trigger_mode: space        # immediate | space
terminators: [space]       # any of: space, enter, tab

# Optional. Override which characters delimit word-boundary matches.
# word_separators: [" ", ".", ",", "!", "?"]

# Maximum characters retained while evaluating regex triggers.
regex_max_buffer: 256

# Prefer native Wayland injection and fall back to uinput.
injection_backend: auto    # auto | wayland | uinput

# Tune these only if an application drops or reorders characters.
injection_delay_ms: 1
wayland_injection_delay_ms: 0
uinput_injection_delay_ms: 1
injection_settle_ms: 10

# Backspace immediately after a simple expansion to restore its trigger.
undo_enabled: true         # true | false

# Optional. Disable expansion in matching applications. Default: []
app_exclusions:
  - class: "^1Password$"
  - class: "^org\\.keepassxc\\.KeePassXC$"

# Optional. The first matching profile overrides behavior for that application.
app_profiles:
  - name: Browser
    filter:
      class: "^(firefox|chromium)$"
    include_match_files: [browser.yml]
    trigger_mode: space
    injection_delay_ms: 1

Run snipexpand detect while an application is focused to find the title, class, and executable values needed for an exclusion or profile.

Commands

snipexpand [COMMAND]
sxp [COMMAND]                    Short form

(no command)                     Run the daemon in the foreground
init                             Explicitly create starter configuration
add TRIGGER TEXT                 Add or replace a generated expansion
remove TRIGGER                   Remove a generated expansion
list                             List triggers and source files
check                            Validate configuration
detect                           Inspect the focused application
reload                           Reload the running daemon
enable                           Enable automatic expansion
disable                          Pause automatic expansion
toggle                           Toggle automatic expansion
paste [--source PATH] [--delay-ms N] TRIGGER
                                Insert a configured expansion
status [--json]                  Show daemon and configuration status
doctor                           Diagnose setup and runtime requirements
install                          Install and start the user service
uninstall                        Remove the service; preserve configuration

Duplicate triggers may coexist for picker use. Automatic typing expands only when the active app profile leaves one matching snippet. A picker can select an exact duplicate with paste --source PATH TRIGGER, using the source returned by list --json.

Limitations

• Hyprland is the only supported and tested compositor. Other Wayland compositors may work but are not yet part of the test matrix.
• Undo works only immediately after a plain, single-line expansion. Multiline and cursor-positioned expansions cannot be undone back to their trigger.
• SnipExpand does not run scripts or shell commands, display forms, insert rich text or images, or provide a package registry.
• Regex triggers use a bounded rolling buffer and support named captures, but do not implement Espanso's full regex behavior.
• Variables are limited to formatted dates, regex captures, and safe nested snippet references. Shell, script, and form variables are intentionally unsupported.
• Application exclusions operate at the application level. Wayland does not expose a browser's focused field type, so SnipExpand cannot automatically identify password fields inside an allowed browser.
• SnipExpand reads global keyboard events, including sensitive input. Application exclusions stop expansion but do not stop the daemon from receiving those events. Install only binaries you trust.

SnipExpand does not execute snippets, access the clipboard, or contact online services.

See the compatibility matrix for the complete supported configuration surface.

Documentation

• Prioritized tasks
• Espanso compatibility
• Espanso-informed design notes

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

License

GNU General Public License v3.0 or later.

Other platforms offer polished text expansion built in or through expensive software. Linux users should not have to settle for less or pay a costly subscription for basic infrastructure. SnipExpand is free and open source so anyone can use it, study it, improve it, and share it.

Anyone who distributes a modified version must make its source available under compatible terms. The project cannot be repackaged and distributed as closed-source software. Private use and private modifications remain private.