Wordy User Guide

Wordy is a native macOS menu bar text expander that monitors your keystrokes and automatically expands trigger phrases into replacement text.

This guide covers Wordy 1.4.5. See the release notes for changes in this version.

Getting Started

Installation

  1. Download Wordy from getwordy.app
  2. Move Wordy to your Applications folder
  3. Launch Wordy

Granting Accessibility Permission

On first launch, Wordy will ask for Accessibility permission. This is required for Wordy to detect your typing across all applications, and to check that expanded text goes into the right place.

  1. Click Open System Settings when prompted
  2. Navigate to Privacy & Security → Accessibility
  3. Enable Wordy in the list
  4. Return to Wordy—you're ready to go!

Keychain Access

On first launch, you may see a macOS prompt asking Wordy to access your Keychain. This is how Wordy securely stores your license key using macOS's built-in encryption. Just click Always Allow so you won't be asked again.

No data leaves your Mac — Keychain is the same secure storage that Safari uses for your passwords.


Creating Snippets

Basic Snippet Creation

Wordy app with snippet list and folders
  1. Click the Wordy icon in your menu bar and select Add New Snippet... (or press ⌘⇧N), or click New Snippet in the main window
  2. In the editor header, fill in:
    • Title: A descriptive name (e.g., "Email Signature")
    • Trigger: The text you'll type to expand (e.g., ;sig)
  3. Type the text the snippet should insert in the large writing area. Use the Insert menu to add fill-in fields, dates, the clipboard and other placeholders where your cursor is
  4. Check the Result preview on the right to see exactly what will be typed
  5. Click Save (or press ⌘↩). Wordy saves the snippet and returns to your list

See The Snippet Editor for a full tour of the editor.

Tip: To try a snippet before saving, choose Test snippet from the … menu in the editor header. See Testing a Snippet.

Tips for Triggers

  • Use a prefix like ; or // to avoid accidental expansions
  • Keep triggers short but memorable
  • Minimum 2 characters recommended
  • Wordy warns you if a trigger is already in use

Organizing with Folders

Create folders to organize related snippets:

  1. Click the folder + button in the toolbar
  2. Name your folder
  3. To move a snippet into a folder, open it, click the gear button in the editor header, and pick a folder under Where it lives

Right-click folders to rename, change color, or delete them.

Tip: Snippets in a folder named Code, or whose text looks like code, are shown in a monospace font in the editor.


The Snippet Editor

Wordy 1.4.4 introduced a visual snippet editor. The snippet is shown as one piece of text, and every placeholder appears as a readable chip inside it: a date reads as "Tomorrow" or "Date (long)", a fill-in field shows its name, and a long script is shortened. On the right, the editor shows the fill-in form your snippet will ask for and a live preview of the result.

The placeholder syntax itself has not changed. Every placeholder in this guide still works, and you can edit the raw syntax at any time in Source mode.

An interactive example: type into the fill-in form to see the result update, just as it does in Wordy.

Header & Settings

The bar across the top of the editor holds:

  • Back (the arrow on the left) — returns to your snippet list. Esc does the same.
  • Title and Trigger — the snippet's name and the text you type to expand it. If the trigger is already used by another snippet, a warning appears under the header and Save is unavailable until you change it.
  • … (More actions) — Test snippet, Version history, and Delete snippet.
  • Gear (Folder, trigger options, apps) — opens the snippet's settings.
  • Save — shows Saved until you change something. Press ⌘↩ to save and return to the list.

Careful: Delete snippet removes the snippet straight away, without asking first.

The settings popover

Click the gear button to open the snippet's settings:

  • Where it lives — the Folder the snippet belongs to.
  • How it fires — the Trigger is a regular expression switch (see Regex Triggers) and App Scope, which controls which apps the snippet works in (see App Scope).
  • Different text per app — Add app version… lets you write different text for a specific app (see Per-App Variants).

Leaving without saving

If you go back to the list with unsaved changes, Wordy asks Discard changes to this snippet? Choose Keep editing to return to the editor, or Discard to throw the changes away. Discarding a new snippet that has never been saved removes it.

Writing & Inserting

Type your text, place the caret where the placeholder should go, then open + Insert. Builder and Source share the same groups:

Menu itemWhat it contains
Nested Snippet…Search snippets by title, shortcut or content
Ask for inputText field, Multi-line text, Dropdown, Date
Reuse inputExisting inputs, when available
Date & timeDates, times, custom formats and offsets
ClipboardCurrent clipboard content
Saved variableYour global variables
CounterA named number sequence
Transform textUPPERCASE, lowercase, Title Case
Structure & actionsCursor lands here, Optional part, Open a link after, Note to self
AdvancedJavaScript, Shell command

In Builder, a new fill-in field is inserted with a free name such as Field or Field 2 and its form row takes focus for editing. A dropdown starts with two example choices. Click a chip to open its editing controls. Regex captures appear as green From trigger chips. The nested-snippet option opens a searchable picker.

Drag a chip to move that occurrence. Hold Option while dragging to copy it. A move is one undoable edit, Move Placeholder, and a copy is Copy Placeholder. Moving one occurrence does not move other identical placeholders. Canceling a drag leaves the original intact; dragging between editors copies it.

The compact Insert controls inside link fields omit the full Structure & actions and Advanced groups.

Fill-in Form Pane

The right side of the editor is headed Fill-in form and shows what Wordy will ask when the snippet fires. If the snippet asks nothing, it says so — the snippet expands the moment you type the trigger.

Each fill-in field has its own row, where you can:

  • Rename the field. Every use of it in the text, including inside links, is updated.
  • Change its type between Text, Multiline, Dropdown and Date picker. Any type can switch to any other; a date switched to a dropdown starts with two example choices.
  • Set a default value, or a date format for date pickers.
  • List a dropdown's choices, separated by commas.
  • Tick Required.
  • Type into Try a value to see it in the Result preview below.

The row also shows how often the field is used, such as "used ×2" or "used in 1 link". If a name is invalid (for example, it contains a colon or is already taken), the row explains what to fix.

Other sections in the pane

  • Optional parts — a checkbox for each optional section, so you can preview the snippet with it included or left out.
  • From the trigger — a Try a value box for each regex capture group.
  • Clipboard — when the snippet uses {{clipboard}}, type sample text into Try some clipboard text.
  • Other placeholders — one row for each date, note, optional section, counter, nested snippet or inline link, showing its raw placeholder syntax so you can edit it in place. If the syntax isn't a single valid placeholder, Wordy shows an error instead of applying it.

Then Open (Links)

Links, apps and files your snippet opens after typing (see Open URL / App / File) are listed in a numbered Then open section under the text, in the order they will open. Add the first one from + Insert → Structure & actions → Open a link after.

Click a link to expand it:

  • Edit the Address. Use the small Insert menu beside it to add a fill-in field, date or other value into the address.
  • For web links, each URL parameter has its own key = value row. Use Add parameter to add one, and the minus button to remove one.
  • Use the link's … menu to Move up, Move down or Remove link.
  • Click Add link to add another.

If there are blank lines between your links, Wordy warns that they will be typed as text and offers Remove them. Links you don't edit keep their exact original text.

Result Preview

Under the fill-in form, Result shows the text the snippet will type:

  • Values you haven't tried yet are dimmed; values you typed are highlighted.
  • If the snippet opens links, they appear afterwards as numbered rows, with your values highlighted where they land. Open Full URLs to see each complete address.
  • Notes appear under Shown on the form.
  • Anything the preview can't show, or that won't work where it is, appears under Not shown here.

The preview resolves text transforms and nested snippet content, including planned links and inherited inputs. Try inherited sample values in the parent preview; edit their definitions in the nested snippet itself. Defaults appear initially, but explicitly clearing a sample leaves it empty. Switching an input type clears incompatible samples, and regex captures have separate samples even when their names match fill-in fields.

Counters show their expected values without advancing the saved count. Scripts display [JavaScript result] or [Shell result] because they run only during Test or expansion. Unresolved syntax remains visible with a diagnostic. Notes remain on the form even when their optional section is unchecked. The preview does not run commands or open links.

Try a preview sample

Hello {{field:Name:Jamie}}!
{{uppercase:{{field:Name:Jamie}}}}

Try Ada for Name to preview Hello Ada! and ADA. Clearing the sample keeps it empty rather than restoring Jamie.

Warnings

The preview warns you about placeholders that won't work where they are, for example:

  • A custom date, counter or script inside a text transform
  • A script inside a link, or a script containing }}
  • A link with no address
  • Time syntax Wordy doesn't understand
  • More than one cursor position (only the first is used)
  • A fill-in field that is first used inside an optional section — it stays empty everywhere else when that section is left out

Narrow windows

When the editor is narrow, the preview moves behind Write and Preview tabs instead of disappearing. In wider windows, you can show or hide the preview with the eye button in the header, and drag the divider to resize it.

Source Mode

Prefer raw syntax? Click Source above the text to edit the snippet's placeholders directly, such as {{field:Name}}. Click Done with Source to return to the visual editor.

  • Source uses the same grouped + Insert menu as Builder, including reusable inputs and the searchable nested-snippet picker. Input and advanced placeholders retain configuration forms. Clicking a fill-in placeholder opens its editor for the name, default and options. Invalid definitions are rejected before insertion.
  • The AI tools are available in Source mode.
  • If a fill-in field is defined in two different ways, the visual editor shows a warning with Fix in Source.

Testing a Snippet

Choose Test snippet from the … menu, or click Test in the Fill-in form heading, to run your snippet for real inside Wordy:

  • If the snippet has fill-in fields, the real fill-in window opens.
  • The result appears in a Test Result window with a Copy button. Nothing is typed into another app, and links are not opened.
  • Regex capture groups are filled with their names, such as <name>.

Note: Because the test is real, it reads your clipboard, advances counters, and runs JavaScript and shell commands. Use the Result preview if you just want to check the text.


Context-Aware Snippets

Snippets can adapt to the app you're typing in. Use App Scope to control where a snippet fires, and Per-App Variants to change what it expands into for each app — all from one snippet in your library.

App Scope

Every snippet can be restricted to fire only in selected apps, or blocked in selected apps. Open a snippet, click the gear button in the editor header, and find App Scope under How it fires. You get three modes:

  • Everywhere — the default. The snippet fires in any app.
  • Only in these apps… — the snippet fires only in the apps you pick.
  • Except in these apps… — the snippet fires everywhere except the apps you pick.

Picking apps

Click Add App… to open the app picker. It shows:

  • Apps currently running on your Mac
  • Your 10 most recently picked apps
  • A Browse… button to pick any .app from your Applications folder

The search field is focused automatically, so you can start typing right away.

Right-click shortcuts

Right-click any snippet in the list and open the Scope submenu for quick actions:

  • Restrict to Current App — only fire in the app you were just using
  • Block in Current App — fire everywhere except the app you were just using
  • Reset to Everywhere — clear the scope

"Current app" is the last non-Wordy app you had focused, so the action targets the app you actually care about.

Note: Wordy never fires triggers inside its own editor, so you can safely type triggers while editing a snippet without triggering an expansion.

Reading scope in the snippet list

The snippet list has a dedicated Scope column (between Trigger and Folder) that summarizes scope at a glance — for example:

  • Mail only — restricted to Mail
  • Mail +2 — restricted to Mail plus two more apps (hover to see the full list)
  • Except Terminal — blocked in Terminal, fires everywhere else
  • Blank — fires everywhere

Per-App Variants

A single snippet can expand to different replacement text depending on which app is frontmost. Type ;hi in Mail and get "Hey there, thank you for your email." Type the same ;hi in Slack and get "Hey Team." One snippet, one trigger — many tones.

Adding a variant

  1. Open the snippet and click the gear button in the editor header
  2. Under Different text per app, click Add app version…
  3. Pick an app from the picker
  4. The new version starts with your Default text — tweak it for that app
  5. Save as usual

Once a snippet has app versions, a switcher appears above the text. Use it to move between Default and each app's version, add another with Add app version…, or remove the one you're viewing with Remove [app] version.

Graceful fallback

If you type the trigger in an app that doesn't have its own variant, Wordy uses the Default text. You only need variants for apps where the text should differ.

Version history

Edits to any variant are captured in snippet version history, so you can always roll back to an earlier version of any app's text. See Snippet Version History for details.

iCloud sync

Variants ride on the same iCloud sync as the rest of your snippets — configure once, they propagate to all your Macs. Variants for apps you don't have installed on a given Mac simply sit dormant until that app is present.

Using Scope and Variants Together

Scope and variants compose naturally. You can limit where a snippet fires and customize its text per app at the same time — for example, allow ;sig only in Mail and Slack, with a different signature in each.

When both are configured, the Scope column in the snippet list shows a combined summary, like Mail only · 2 variants.

Backwards-compatible: Existing snippets keep working exactly as before. Scope is blank by default (fires everywhere), and variants are opt-in per snippet. Nothing to migrate.


Regex Triggers

For power users, Wordy supports regular expressions as triggers. This lets you create dynamic triggers that capture parts of what you type and use them in the replacement.

Overview

Regular expression (regex) triggers let you create powerful, flexible shortcuts. Instead of a fixed trigger like ;sig, you can match patterns like ;hi(Alice) where "Alice" is captured and inserted into your replacement.

How to enable

  1. Create or edit a snippet
  2. Click the gear button in the editor header and turn on Trigger is a regular expression under How it fires
  3. Type your pattern in the Trigger field, which now shows Pattern, using named capture groups like (?<name>\w+)
  4. The settings popover shows an Example of what you'll type (e.g., ;jira<project>-<number>[space])
  5. Reference captures as {{name}} in your text. In the visual editor they appear as green From trigger chips

Each capture group also gets a Try a value box under From the trigger in the editor's right pane, so you can preview the result with sample input.

Terminators

Patterns ending with + or * (like \d+ or \w+) fire as soon as the minimum match is found. To let you type the full value, add a terminator at the end:

Examples with space terminator

PatternTriggerType thisGet this
;jira(?<project>[A-Z]+)-(?<number>\d+)\s;jira<project>-<number>[space];jiraPROJ-1234 (with space)Jira link
;gh(?<user>\w+)/(?<repo>\w+)\s;gh<user>/<repo>[space];ghapple/swift GitHub link
;mail(?<user>\w+)\s;mail<user>[space];mailjohn [email protected]

Common terminators

  • \s (space) — most natural, displays as [space] in the hint
  • Parentheses ) — when input is wrapped, e.g., ;hi\((?<name>\w+)\)
  • Semicolon ; or period . — when space wouldn't be natural

Important: Always add a terminator when your pattern ends with + or * — otherwise it fires too early.

Examples

Delimiter terminators

These patterns use parentheses, brackets, or other delimiters as natural terminators:

Type thisGet this
;hi(Sarah)→Hello Sarah!
Trigger ;hi\((?<name>\w+)\)
Template Hello {{name}}!
;tel(1-5551234)→+1 5551234
Trigger ;tel\((?<code>\d+)-(?<num>\d+)\)
Template +{{code}} {{num}}
;yt(dQw4w9WgXcQ)→Full YouTube URL
Trigger ;yt\((?<id>[a-zA-Z0-9_-]+)\)
Template https://youtube.com/watch?v={{id}}
;img(800x600)→<img width="800" height="600">
Trigger ;img\((?<w>\d+)x(?<h>\d+)\)
Template <img width="{{w}}" height="{{h}}">
;rgb(255,128,0)→rgb(255, 128, 0)
Trigger ;rgb\((?<r>\d+),(?<g>\d+),(?<b>\d+)\)
Template rgb({{r}}, {{g}}, {{b}})
;wrap(div)→<div>|</div> (cursor inside)
Trigger ;wrap\((?<tag>\w+)\)
Template <{{tag}}>{{cursor}}</{{tag}}>
;calc(5+3)→5 + 3 = 8
Trigger ;calc\((?<a>\d+)\+(?<b>\d+)\)
Template {{a}} + {{b}} = {{js:{{a}}+{{b}}}}

Wordy bounds regex matching time and stops using patterns that exceed the execution budget. If a complex pattern stops matching, simplify it and test with representative input. This limit is automatic and has no user-adjustable setting.

Common Patterns

PatternMatches
\w+Letters, numbers, underscores
\d+Numbers
[a-zA-Z]+Letters only
[a-zA-Z0-9_-]+URL-safe characters
.+Any characters
\sWhitespace (space, tab, newline)

Tips

  • Escape special characters with \ (parentheses, brackets, etc.)
  • The pattern field uses syntax highlighting to help you read complex patterns:
    • Yellow — capture group names (ticket in (?<ticket>...))
    • Teal — capture group syntax ((?<...> and ))
    • Cyan — escape sequences (\s, \d, \w, etc.)
    • Orange — character classes ([A-Z], [0-9])
    • Pink — quantifiers (+, *, ?)
  • An invalid pattern shows an Invalid regex warning under the header, and you can't save until it's fixed
  • Regex triggers work with all other features (fill-ins, cursor, etc.)
  • Use Try a value under From the trigger to preview the result with sample input, or Test snippet in the … menu, which fills each capture group with its name
  • Always add a terminator when your pattern ends with + or * — otherwise it fires too early

Global Variables

Global variables let you define values once (like your name, company, or email) and use them across all your snippets. Unlike fill-in fields, global variables expand automatically—no popup form needed.

Setting Up Global Variables

  1. Click Global Variables in the sidebar (or from the menu bar)
  2. Click the + button to add a new variable
  3. Enter a Name (e.g., Name, Company, Email)
  4. Enter the Value (e.g., John Smith, Acme Corp, [email protected])

Variables are saved automatically as you type.

Using Global Variables in Snippets

Use the {{#VariableName}} syntax in your snippets:

PlaceholderOutput
{{#Name}}John Smith
{{#Company}}Acme Corp
{{#Email}}[email protected]

Example: Email Signature

Best regards,
{{#Name}}
{{#Title}} | {{#Company}}
{{#Email}} | {{#Phone}}

Expands instantly to:

Best regards,
John Smith
Product Manager | Acme Corp
[email protected] | (555) 123-4567

Tips & Common Use Cases

  • Variable names are case-insensitive ({{#name}} = {{#Name}})
  • Undefined variables show as [#VariableName?] to help you spot typos
  • Global variables sync with iCloud (if enabled)

Recommended Variables

VariableExample Value
NameYour full name
FirstNameYour first name
CompanyYour company name
EmailYour email address
PhoneYour phone number
TitleYour job title
AddressYour mailing address
WebsiteYour website URL

Placeholders

Placeholders add dynamic content to your snippets. In the snippet editor, add them from the Insert menu, where they appear as readable chips in your text, and fine-tune them in the editor's right pane (see Writing & Inserting). This section lists the syntax behind each one, which you can also type directly in Source mode.

Tip: For values like your name, email, and company that you use everywhere, see Global Variables — they auto-expand without any popup.

Date & Time

PlaceholderOutput
{{date:short}}1/26/26
{{date:medium}}Jan 26, 2026
{{date:long}}January 26, 2026
{{time}}3:30 PM

Date Math

Add or subtract time:

PlaceholderOutput
{{date:+1d}}Tomorrow's date
{{date:-1d}}Yesterday's date
{{date:+1w}}One week from now
{{date:+1m}}One month from now
{{date:-1y}}One year ago
{{date:+1d:long}}Tomorrow in long format

Time Math

PlaceholderOutput
{{time:+1h}}One hour from now
{{time:-30M}}30 minutes ago

Units: d (days), w (weeks), m (months), y (years), h (hours), M (minutes)

Custom Date Formats

Use Unicode date format patterns for full control over date output:

PlaceholderOutput
{{date:yyyy-MM-dd}}2026-01-29
{{date:HH:mm:ss}}14:30:45
{{date:yyyy-MM-dd'T'HH:mm:ss}}2026-01-29T14:30:45
{{date:EEEE}}Wednesday
{{date:MMMM d, yyyy}}January 29, 2026
{{date:MMM yyyy}}Jan 2026
{{date:E, d MMM}}Wed, 29 Jan

Combining with date math

PlaceholderOutput
{{date:+1d:yyyy-MM-dd}}Tomorrow in ISO format
{{date:-1w:EEEE, MMMM d}}Last week's day and date
{{date:+1m:MMM yyyy}}Next month

Common format tokens

TokenMeaningExample
yyyyYear (4 digits)2026
yyYear (2 digits)26
MMMMMonth name (full)January
MMMMonth name (short)Jan
MMMonth (2 digits)01
ddDay (2 digits)29
dDay29
EEEEWeekday (full)Wednesday
EEEWeekday (short)Wed
HHHour 24h (2 digits)14
hhHour 12h (2 digits)02
mmMinute30
ssSecond45
aAM/PMPM

Uses Unicode Date Format Patterns.

Clipboard

PlaceholderOutput
{{clipboard}}Current clipboard contents

Text Transforms

PlaceholderOutput
{{uppercase:hello}}HELLO
{{lowercase:HELLO}}hello
{{titlecase:hello world}}Hello World

Cursor Positioning

PlaceholderEffect
{{cursor}}Places your cursor here after expansion

Only the first {{cursor}} is used if multiple are present.

Counters

Auto-incrementing numbers that persist across sessions:

PlaceholderOutput
{{counter:invoice}}1, 2, 3... (increments each use)
{{counter:ticket:100}}Starts at 100 if new
{{counter:invoice:reset}}Resets to 1

Each counter name is independent—use different names for different sequences.

Identical counter tokens resolve once per expansion. For example, Reference {{counter:invoice}} / {{counter:invoice}} uses the same number in both positions. Opening the Result preview does not advance it. Counter values are local to this Mac and are not included in portable exports or library sync.

Nested Snippets

Reuse other snippets inside your snippets:

PlaceholderEffect
{{snippet:sig}}Inserts the snippet with trigger "sig"

Supports up to 10 levels of nesting. Circular references are detected and prevented.

Place the caret in Builder or Source and choose + Insert > Nested Snippet…. In Insert Nested Snippet, use Search by title, shortcut or content, review the title, shortcut and content excerpt, then press Up/Down and Return or choose Insert Snippet. Escape or Cancel closes without inserting.

Search ignores case and accents, accepts multiple words and ranks exact title or shortcut matches first. Snippets with an empty shortcut, a regex trigger or a closing brace in the shortcut are excluded. The picker never executes scripts.

For example, {{snippet:;signature}} references the snippet with shortcut ;signature. It does not copy the source into the parent. When sharing the parent folder, include dependencies so the recipient receives the referenced snippet too.

JavaScript Expressions

Run JavaScript code in your snippets:

PlaceholderOutput
{{js:1+1}}2
{{js:Math.PI.toFixed(2)}}3.14
{{js:random(1,100)}}Random number 1-100
{{js:uuid()}}Generated UUID

Available helpers

  • now() — Current date and time
  • today() — Current date
  • time() — Current time
  • random(min, max) — Random integer
  • uuid() — Generate UUID

Shell Commands

Run shell commands and insert their output:

PlaceholderOutput
{{shell:whoami}}Your username
{{shell:date +%s}}Unix timestamp
{{shell:git branch --show-current}}Current git branch
{{shell:echo "Hello, World!"}}Hello, World!
{{shell:python3 -c "print(2**10)"}}1024
{{shell:hostname}}Your Mac's hostname
{{shell:sw_vers -productVersion}}macOS version

Details

  • Commands run via /bin/zsh as the current user
  • 5-second timeout — commands that take longer return [Shell Timeout]
  • Failed commands return [Shell Error] or [Shell Error: message]
  • Trailing newlines are automatically trimmed from output

Execution limits

JavaScript has a one-second timeout and a fresh context for each evaluation, so global state does not carry between calls. Shell commands run through /bin/zsh with a five-second timeout. Wordy terminates timed-out workers and shell descendants, and drains output while a command runs.

Captured output is limited to 1 MiB, including combined standard output and error for shell commands. A timeout returns [JS Timeout] or [Shell Timeout]; oversized output returns [JS Error: Output exceeds 1 MB] or [Shell Error: Output exceeds 1 MB]. Reduce the work or output and try again.

The shell command blocklist can return [Shell Error: Potentially dangerous command blocked], but it is not a security sandbox. Review shared scripts before Test or expansion. Preview never executes them. Scripts containing the }} terminator, scripts inside link targets, and some custom dates, counters or scripts nested in transforms remain unsupported; follow the preview diagnostics.

Open URL / App / File

Open URLs, launch apps, or open files as a side effect of snippet expansion. The placeholder resolves to an empty string — it performs the action without inserting any text.

PlaceholderEffect
{{open:https://google.com}}Opens a URL in your default browser
{{open:/Applications/Calculator.app}}Launches an app
{{open:~/Documents/report.pdf}}Opens a file in its default app

Dynamic URLs with nested placeholders

Combine with other placeholders to build URLs dynamically:

{{open:https://jira.com/browse/{{clipboard}}}}

This opens a Jira ticket based on your clipboard contents.

Details

  • Opens via macOS — works with https:// URLs, file paths, and .app bundles
  • Resolves to an empty string — combine with text insertion or use standalone
  • Multiple {{open:...}} per snippet allowed
  • Tilde paths (~/Documents/...) are expanded automatically
  • Works with fill-in forms, quick search, and direct expansion
  • Add one from + Insert → Structure & actions → Open a link after in the visual editor, or Insert Placeholder → Advanced → Open URL / Path... in Source mode

Editing links in the editor

Links that open after the text appear in the editor's numbered Then open section, where you can edit each address, add or remove URL parameters one by one, insert fill-in fields or other values into an address, and reorder links. See Then Open (Links).

The Result preview lists each link the snippet will open, with your sample values highlighted where they land. Nothing is opened while you preview.

Example: Open a URL and insert text

Ticket {{clipboard}} opened in browser.
{{open:https://jira.com/browse/{{clipboard}}}}

This inserts a confirmation message and opens the Jira ticket — all from a single snippet.


Fill-in Fields

Fill-in fields create an interactive form that appears when you expand the snippet, letting you customize the output each time.

Adding and editing fields

  1. In the snippet editor, place your cursor where the value should go
  2. Choose Insert → Text field, Multi-line text, Dropdown or Date
  3. The field appears in your text as a chip, and its row in the Fill-in form pane is selected — type a name for it
  4. In the same row, change the type, add a default value or dropdown choices, and tick Required if needed

To use the same field again, choose it from the top of the Insert menu. Renaming a field updates every place it's used. See Fill-in Form Pane for details.

The examples below show the syntax behind each field type, which you can also type directly in Source mode.

Input names cannot contain colons, braces or surrounding whitespace. Defaults and date formats cannot contain colons or braces. Dropdown choices cannot contain commas or braces, and reserved required forms are restricted. The editor explains invalid definitions before inserting them.

Text Field

{{field:Name}}
{{field:Name:John}}           // With default value
{{field:Name::required}}      // Required field
{{field:Name:John:required}}  // Default + required

Multiline Text Field

{{textarea:Notes}}
{{textarea:Notes:Enter details here}}
{{textarea:Notes::required}}
{{dropdown:Priority:High,Medium,Low}}
{{dropdown:Status:Draft,Review,Published:required}}

Options are comma-separated. The first option is selected by default.

Optional Sections

Include or exclude content based on a checkbox:

{{?:Include Greeting}}Hello {{field:Name}},

{{/?}}Here is the information you requested...

When expanded, you'll see a checkbox. Uncheck it to remove that section entirely.

Date Picker

Show a graphical calendar in the fill-in form for date selection:

{{datepicker:Due Date}}
{{datepicker:Birthday:yyyy-MM-dd}}              // Custom date format
{{datepicker:Start Date::required}}              // Required field
{{datepicker:Deadline:MMMM d, yyyy:required}}    // Format + required

When expanded, the form shows a native macOS calendar picker instead of a text field. The selected date is formatted according to the specified format (or medium date style like "Feb 15, 2026" if no format is given).

Tips

  • Use any Unicode date format pattern (same as Custom Date Formats above)
  • The date picker defaults to today's date
  • Great for meeting notes, invoices, contracts, and any snippet that references a specific date

An explicitly cleared date input stays empty; Wordy does not substitute today. Use a required field if the snippet must have a date before expansion.

Notes

Display read-only information in the fill-in form that won't appear in the final output:

{{note:Send to: [email protected] (sales), [email protected] (support)}}

Notes are useful for:

  • Reference information you might want to copy (email addresses, phone numbers)
  • Instructions or reminders when filling out the form
  • Context that helps you fill in the other fields

How notes work

  • Displayed in the fill-in form with an info icon
  • Text is selectable so you can copy it
  • Completely stripped from the final expanded output
  • Listed under Shown on the form in the editor's Result preview

Example

{{note:Contacts: [email protected] (urgent), [email protected] (general)}}

Dear {{field:Recipient}},

Thank you for contacting {{dropdown:Department:Sales,Support,Billing}}.

{{textarea:Message}}

Best regards

When expanded, the form shows the email addresses for reference at the top, but the final output contains only the filled-in message.

The Fill-in Window

When you expand a snippet with fill-in fields, the fill-in window opens with your fields on the left and a live Preview on the right.

  • The preview shows the text that will be typed, with values you haven't filled in yet dimmed and your answers highlighted as you type.
  • If the snippet opens links, they're listed after the text as numbered rows, with your answers highlighted where they land.
  • If the snippet uses {{clipboard}}, your current clipboard content is shown and highlighted. Wordy only reads the clipboard for this while the window is open, and never changes it.
  • Press Return or click Expand to insert the result. Press Esc to cancel.

The window can be resized from any edge or from the grip in its bottom-right corner, and you can drag the divider between the fields and the preview. Wordy keeps the new size for the next form until you quit.

Remembering Field Values

Each fill-in field has a Memorize toggle. When it's on, Wordy saves that field's value for next time.

How it works

  1. Expand a snippet with fill-in fields
  2. Enter your values
  3. Turn on Memorize next to fields you want to save
  4. Click Expand

Next time you use that snippet (or any snippet with the same field name), the field will be pre-filled with your remembered value.

Tips

  • Remembered values are per-field name, not per-snippet (so {{field:Email}} shares its value across all snippets)
  • Turn off "Memorize" and expand with a new value to update the saved default
  • Use this feature for values that change occasionally but not every time (e.g., project names, client names)

Combining Global Variables and Fill-in Fields

Global variables and fill-in fields work great together. Use global variables for values that never change, and fill-in fields for values you customize each time.

Example: Sales Outreach Email

Hi {{field:Recipient}},

Thank you for your interest in {{#Company}}.

{{?:Include meeting request}}I'd love to schedule a call to discuss further.
You can reach me at {{#Email}} or {{#Phone}}.

{{/?}}Best regards,
{{#Name}}
{{#Title}}

When expanded:

  • {{#Company}}, {{#Email}}, {{#Phone}}, {{#Name}}, and {{#Title}} auto-fill from your global variables
  • Only the {{field:Recipient}} field and the checkbox appear in the form

Example: Meeting Follow-up

Hi {{field:Name}},

Thank you for meeting with me {{dropdown:When:today,yesterday,last week}}.

{{?:Action Items}}Action items:
{{textarea:Items}}

{{/?}}{{?:Schedule Follow-up}}Let's schedule a follow-up for {{date:+1w:long}}.

{{/?}}Best regards,
{{#Name}}

AI Snippet Generation

Wordy can use Claude AI to create new snippets or improve existing ones. Describe what you need in plain English and Wordy generates the trigger, replacement text, and placeholders automatically.

Setup

To enable AI features, you'll need an Anthropic API key:

  1. Go to Settings → AI & Translation
  2. Enter your Anthropic API key (get one at console.anthropic.com)
  3. Choose a model:
    • Claude Sonnet 4.6 (default) - best quality, recommended for most users
    • Claude Haiku 4.5 — faster responses, lower cost
  4. The AI tools appear in the snippet editor's Source mode once a key is saved

To remove AI features entirely, click the trash icon next to your API key in Settings. The AI tools will disappear.

Where to find the AI tools: In Wordy 1.4.4 and later, the AI tools live in the snippet editor's Source mode. Open a snippet and click Source above the text. Then click the AI button in the bottom-right corner of the text, or right-click the text and choose Create with AI... or Improve with AI...

Create with AI

Use this to generate a new snippet from a natural language description.

  1. Open a new or existing snippet in the editor and click Source above the text
  2. Click the AI button in the bottom-right corner of the text while it's empty, or right-click the text and choose Create with AI...
  3. Describe what you want in the prompt field
  4. Click Generate
  5. Review the suggestion — title, trigger, replacement, and regex status are all shown
  6. Click Apply to use it, Refine to edit your prompt and regenerate, or Discard to cancel

Example prompts

PromptWhat Claude generates
"Email signature with fill-in fields for name, title, and phone"A snippet with {{field:Name}}, {{field:Title}}, {{field:Phone}}, and {{cursor}}
"Polite follow-up email with an optional action items section"A snippet using {{field:Recipient}}, {{dropdown:When:today,yesterday,last week}}, and {{?:Action Items}}
"Insert today's date in ISO format"A simple snippet with trigger ;iso and replacement {{date:yyyy-MM-dd}}
"Git commit message with type dropdown and scope field"A snippet with {{dropdown:Type:feat,fix,docs,refactor,test}}, {{field:Scope}}, and {{field:Description::required}}
"Generate a UUID"A snippet with trigger ;uuid and replacement {{js:uuid()}}
"Invoice number that auto-increments, starting from 1000"A snippet using {{counter:invoice:1000}}
"Jira ticket link where I type the ticket number"A regex trigger like ;jira\((?<num>\d+)\) with replacement https://jira.company.com/browse/PROJ-{{num}}
"Current git branch name"A snippet with trigger ;branch and replacement {{shell:git branch --show-current}}

Improve with AI

Use this to enhance an existing snippet — the AI sees the current title, trigger, and replacement and suggests improvements.

  1. Open a snippet that has content and click Source above the text
  2. Click the AI button in the bottom-right corner of the text, or right-click the text and choose Improve with AI...
  3. Describe what you'd like to improve
  4. Review and apply, refine, or discard
Improve with AI dialog in Wordy

Example improvement prompts

PromptWhat happens
"Add a fill-in field for the recipient name"Adds {{field:Recipient}} where appropriate
"Make the greeting optional"Wraps the greeting in {{?:Include Greeting}}...{{/?}}
"Use date math for next Friday"Replaces hardcoded dates with {{date:+...}}
"Add cursor positioning after the greeting"Adds {{cursor}} at the logical editing point
"Make the trigger shorter"Suggests a more concise trigger
"Add a dropdown for tone: formal, casual, friendly"Adds {{dropdown:Tone:Formal,Casual,Friendly}} and adjusts the text
"Replace the hardcoded company name with a fill-in field"Swaps static text for {{field:Company:Acme Corp}} with a sensible default
"Add an auto-incrementing reference number"Adds {{counter:ref}} to the snippet

Tips

  • Be specific: "Add a required dropdown for priority with options High, Medium, Low" works better than "add some options"
  • You can specify placeholders: Tell Claude exactly which placeholder to use and where — e.g., "put {{cursor}} after the signature" or "use {{date:+1d:long}} for the deadline"
  • Refine iteratively: Click Refine to go back and adjust your prompt if the first result isn't quite right. Claude remembers the previous suggestion and tries something different
  • Regex triggers: You can ask for regex triggers — e.g., "create a regex trigger that captures a name from the trigger text"
  • AI knows all placeholders: Claude is aware of every Wordy feature — dates, fill-ins, counters, JavaScript, shell commands, nested snippets, optional sections, and regex triggers

Privacy

  • Your API key is stored in the macOS Keychain — it's never written to disk as plaintext
  • Snippet content is sent to Anthropic's API only when you click Generate
  • No data is stored on Anthropic's servers beyond the API request (see Anthropic's API data policy)
  • Remove your API key at any time to fully disable AI features

AI Translation

Translate selected text instantly from any app using Claude AI — without switching windows or opening a browser.

Wordy AI Translation panel showing original text and Italian translation

Setup

AI Translation uses the same Anthropic API key as AI Snippet Generation. If you've already set up your key in Settings → AI & Translation, translation is ready to use.

Translate supports up to 5,000 characters and requires an accessible selection. See Selection & Replacement Safety for replacement checks and clipboard behavior.

How to Translate

  1. Select text in any application
  2. Press ⌥T (Option+T) to open the translation panel
  3. Choose your target language from the dropdown (28 languages available)
  4. Click Translate (or press Return)
  5. Choose an action:
    • Replace — Pastes the translation over your original selection
    • Copy — Copies the translation to your clipboard
    • Escape — Dismisses the panel without any changes

The Translation Panel

A floating Spotlight-style panel appears in the center of your screen showing:

  • Original text — The text you selected (read-only)
  • Language picker — Choose from 28 languages including Spanish, French, German, Japanese, Chinese, Korean, Arabic, and more
  • Translate button — Starts the translation (also triggered by pressing Return)
  • Translation result — The translated text appears here
  • Replace / Copy buttons — Insert or copy the result

The panel auto-dismisses when you click outside it or press Escape.

Changing the Language

Select a different language from the dropdown and click Translate again. Your preferred language is remembered across sessions.

Customizing the Hotkey

The default shortcut is ⌥T (Option+T). To change it:

  1. Open Settings (⌘,)
  2. Find the Keyboard Shortcuts section
  3. Click Record Shortcut next to "Translate Selection"
  4. Press your preferred key combination
  5. Click Reset to Default to restore ⌥T

Requirements

  • An Anthropic API key must be configured in Settings → AI & Translation
  • If no API key is set, the translation hotkey is silently ignored
  • Uses the same Claude model selected for AI Snippet Generation

Available Languages

Arabic, Chinese (Simplified), Chinese (Traditional), Czech, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese.


AI Rewrite

Rewrite any selected text in any app using Claude. Fix grammar, change tone, simplify, or apply any custom instruction — all without leaving the app you're working in.

Setup

AI Rewrite uses the same Anthropic API key as AI Snippet Generation and AI Translation. If you've already set up your key in Settings → AI & Translation, rewriting is ready to use.

If you haven't configured a key yet, see AI Snippet Generation → Setup.

How to Rewrite

  1. Select the text you want to rewrite in any app
  2. Press Ctrl+Shift+R (or your custom hotkey)
  3. Type a custom instruction or pick a saved prompt from the dropdown
  4. Review the result in the panel
  5. Click Replace to paste the rewritten text back into the app, or Copy to copy it to your clipboard

The Rewrite Panel

The floating panel shows:

  • The source app in the header (e.g., "Rewrite → Safari")
  • Your original selected text
  • A text field for your custom instruction
  • A dropdown of saved prompts
  • The rewritten result

The panel stays visible even if you click on another app — dismiss it with ESC or the close button.

Custom Prompts

Create and manage rewrite prompts that appear in the dropdown:

  • Click the gear icon in the rewrite panel to open the prompt manager
  • Add new prompts, edit existing ones, reorder them, or delete prompts you no longer need
  • Prompts sync across devices via iCloud alongside your snippets and folders

Six presets are included out of the box:

  • Fix Grammar — correct spelling and grammar
  • Make Concise — shorten without losing meaning
  • Make Professional — formal, business-appropriate tone
  • Make Casual — relaxed, conversational tone
  • Simplify — use simpler words and shorter sentences
  • Summarize — condense into key points

All presets are fully editable — modify them to fit your needs.

Iterative Refinement

Not quite right? Click Refine after a rewrite to rewrite the result again with a different instruction. Chain multiple refinements without starting over — for example, first "Make Concise", then "Make Professional".

Customizing the Hotkey

The default shortcut is Ctrl+Shift+R. To change it:

  1. Open Settings (⌘,)
  2. Go to the Keyboard Shortcuts section
  3. Click Record Shortcut next to "Rewrite Selection"
  4. Press your preferred key combination

Selection & Replacement Safety

Rewrite and Translate accept selections of up to 5,000 characters. Larger selections show an explanation instead of silently processing only the beginning. Select a smaller passage and try again.

Wordy reads the selection through Accessibility. If the app cannot expose it, Selection unavailable is shown; opening or dismissing the panel does not borrow or change your clipboard.

Before replacing text, Wordy must still be able to verify the original field, text and selection. Editing the document or changing the selection can stop replacement. Copy the result and paste it yourself when the destination cannot be verified. The same-app fallback for fill-in snippets and Quick Search does not apply to AI replacement.

Replacement preserves rich and multiple-item clipboard contents. If you copy something newer while it runs, Wordy keeps that newer copy. The API key stays in this Mac's Keychain, outside JSON exports and iCloud library sync. If saving a replacement key fails, the previous saved key is retained and Settings > AI & Translation shows the error.

Requirements

  • An Anthropic API key must be configured in Settings → AI & Translation
  • If no API key is set, the rewrite hotkey is silently ignored
  • Uses the same Claude model selected for AI Snippet Generation
  • Text must be selected in the source app before triggering the hotkey

Import & Export

Move Your Library to Another Mac

Wordy 1.4.5 can move your library in a portable JSON file, including between Macs using different iCloud accounts. This is a snapshot of your library, so the accounts remain independent after the transfer.

  1. On the first Mac, open Settings > Library & Sync. If you use iCloud, check that recent changes have arrived before exporting. Export uses the library currently loaded on this Mac.
  2. Choose Export Library… under Back up or move your Wordy library, or use File > Export Library….
  3. Save the suggested Wordy Library YYYY-MM-DD.json file. Export complete shows counts for snippets, folders, variables and rewrite prompts. Use Show in Finder to locate it.
  4. Transfer the file to the other Mac, then choose File > Import… or Settings > Library & Sync > Import Wordy File….
  5. Select the JSON file and review Import into Wordy. New items are selected; changed or previously deleted items need an explicit choice.
  6. Choose Import N items. Wait for Saving… to finish, check Import complete, then choose Done.

The second Mac keeps its own preferences, shortcuts, API key, license and sync setting. If iCloud sync is enabled there, imported content subsequently syncs to Macs on that account. The completion message distinguishes a successful local save from background iCloud delivery.

Exporting Snippets

Choose the format that matches what you want to move:

PurposeActionContents
Move or back up a Wordy libraryFile > Export Library…Snippets, folders, saved variables and rewrite prompts
Share one folderRight-click the folder > Export Folder…Folder contents, with optional dependencies
Save basic snippet text for another appSettings > Library & Sync > Export CSV…, inside Transfer with TextExpander or CSVTrigger, replacement text and title

CSV leaves out folders, variables, rewrite prompts, app rules and ordering. Wordy placeholders are not converted into another app's syntax on export.

What a Wordy JSON file preserves

Whole-library export includes titles, shortcuts, complete snippet source, folder assignments, creation and modification dates, manual ordering, regex-trigger settings, app inclusion/exclusion rules and app-specific replacement text. It also includes folder names, colors and order, all saved variable names and values, and rewrite prompts. Stable item identifiers are preserved so repeat imports can recognize matching items. Folders are flat.

What stays on the original Mac

Exports do not include app settings, keyboard shortcuts, AI model or translation-language preferences, Keychain API keys, license or trial state, offline entitlement, counter values, remembered fill-in values, snippet version history, usage statistics, CSV import history or sync deletion records. External files referenced by a snippet are not packaged into the export.

Private text you put inside a snippet or saved variable is included as content. Review those values before sharing a file.

Sharing a Folder

  1. Right-click a folder in Wordy's library sidebar and choose Export Folder….
  2. If it uses outside snippets or saved variables, review Include this folder's dependencies?.
  3. Choose Include dependencies to carry those references with the folder, Folder only to leave them out, or Cancel.
  4. If Wordy reports Some dependencies are missing, resolve the references first or choose Export anyway with that limitation in mind.
  5. Save the JSON file. The recipient opens it with File > Import… and reviews the import preview.

Dependency inclusion follows nested snippets recursively, including references in app-specific replacement text. It includes the required snippets, their folder records and referenced saved variable values. It does not export every other snippet in those folders. Folder exports do not include the separate rewrite-prompts collection.

For example, if a Support folder uses a signature from another folder and a saved Company variable, Include dependencies carries the signature and Company value too. Folder only leaves those references unresolved unless the recipient already has them. Check the content and variable values before sharing.

Importing a Wordy JSON File

Choose File > Import… and select a Wordy JSON export, or use Settings > Library & Sync > Import Wordy File…. Reading export… appears while Wordy prepares the preview. Reading or canceling a preview does not change your library or run imported scripts.

Wordy accepts its older version 1 exports, containing snippets and folders, and current version 2 exports, containing all four collections. The limit shown in the app is 20 MB (20 MiB). Unsupported future formats ask you to update Wordy. Malformed files, duplicate identifiers, missing folder references and invalid regex syntax are rejected.

Use a file created by Export Library… or Export Folder…. An internal file such as snippets.json from Application Support is not a portable export. JSON from other apps is not supported by this importer.

Reviewing the Import Preview

The Import into Wordy sheet counts new, already-present, and different or previously deleted items. Counts include folders, saved variables and rewrite prompts as well as snippets. Expand rows to compare Existing and Imported content, then use the checkboxes to choose what changes.

StatusInitially selected?What happens
NewYesAdds the item if left checked.
Already presentNo, disabledSkips the matching item.
Different versionNoCheck it to replace the whole item with the imported version. Leave it unchecked to keep yours.
Previously deletedNoCheck it explicitly to restore the item.
Conflicting shortcut or nameNo, disabledCannot be imported. Rename the conflict in the source library and export again.

Matching uses stable item identifiers. Reimporting an unchanged file skips identical items. If you edited an imported item locally, an older copy appears as Different version and stays unchecked. Selecting it deliberately replaces your edit; it does not merge individual fields. Items absent from the file are left alone.

Shortcut conflicts consider exact shortcut text and app scopes. Variable-name conflicts ignore letter case. Folders with the same name but different identifiers can remain separate folders. Regex shortcuts need review because overlapping patterns cannot all be detected in advance.

Check dependencies before applying

Missing nested snippets and variables produce warnings. Wordy does not automatically select or invent dependencies. If you uncheck a new folder but import its snippet, and that folder does not already exist, the snippet becomes unfiled.

Choose Import N items when the selection is ready. There is no Keep both choice or destination-folder selector for native JSON. Those controls should not be confused with the separate CSV importer.

If an edit or sync changes the library while you review, Wordy refreshes the preview and asks you to review again. During Saving…, the sheet cannot be dismissed. The import is applied in memory only after the complete local save succeeds; a failed save is not reported as a successful import or sent to iCloud as a partial library.

Import Backups & Recovery

Before applying a JSON import, Wordy creates a uniquely named pre-import recovery folder in ~/Library/Application Support/Wordy/Backups/. It contains the native library files and deletion records, a portable library.json, and RESTORE.txt with instructions.

To recover selected content, import that backup's library.json and review which items to restore or replace. This does not remove every item added by the later import. There is no one-click Undo for JSON imports.

For a complete local restore, follow that backup's RESTORE.txt: disable sync, quit Wordy, preserve the current files, replace the specified library files, then reopen and review. Re-enabling sync merges with current cloud content; restoring local files does not roll back iCloud or other Macs.

Import Troubleshooting

Message or problemWhat to do
This is not a Wordy exportSelect an exported Wordy library or folder, rather than an internal JSON file or another app's export.
This file needs a newer Wordy versionUpdate Wordy before importing the file.
File exceeds the size limitUse smaller folder exports.
Conflicting shortcut or variable nameRename it in the source library and export again. The conflicting row cannot be selected.
Snippet imported without a folderCheck whether its new folder was unchecked in the preview.
Missing nested snippet or variableExport again with dependencies, or make sure the destination already contains them.
Preview changed before importReview the refreshed preview before confirming.
Imported content has not reached another MacCheck Library & Sync, the iCloud account and sync status. A local save is separate from cloud delivery.

Importing and previewing a shared snippet does not execute its commands. Review JavaScript and shell commands before using Test or expanding the snippet.

Importing from TextExpander

Wordy can import your TextExpander snippets:

  1. Export your snippets from TextExpander as CSV
  2. In Wordy, go to Settings → Library & Sync → Transfer with TextExpander or CSV → Import TextExpander CSV…
  3. Select your CSV file
  4. Review the import preview:
    • Choose a destination folder (or create a new one)
    • Handle duplicates: Skip, Replace, or Import as new
    • Review any conversion warnings
  5. Click Import

Automatic placeholder conversion

TextExpanderWordy
%clipboard%{{clipboard}}
%filltext:name=X%{{field:X}}
%fillarea:name=X%{{textarea:X}}
%fillpopup:name=X:a:b:c%{{dropdown:X:a,b,c}}
%snippet:trigger%{{snippet:trigger}}

Undo Import

Changed your mind? Go to Settings → Library & Sync → Recent TextExpander imports and click Undo next to the CSV import batch. These controls do not undo native JSON imports; see Import Backups & Recovery.


Snippet Version History

Wordy automatically saves a snapshot of your snippet each time you edit it, so you can recover previous versions if needed.

How It Works

  • When you save a change to a snippet's title, trigger, text, regex setting or app versions, Wordy stores the previous version
  • Changing only the folder or app scope doesn't create a new version
  • Up to 5 versions are kept per snippet (oldest are pruned automatically)
  • History is persisted across app restarts

Restoring a Previous Version

  1. Open a snippet in the editor
  2. Click the … menu in the editor header and choose Version history
  3. Browse the list of previous versions (newest first)
  4. Each entry shows the date/time, trigger, and a preview of the text
  5. Click Restore to load that version into the editor
  6. Review the restored content and click Save to keep it (or go back and choose Discard to throw it away)

Note: Restoring brings back the title, trigger, text and regex setting. The snippet's folder, app scope and app versions stay as they are. Version history is dimmed if no previous versions exist for the snippet. Versions are only created when you edit an existing snippet, not when creating a new one.


Snippet Suggestions

Wordy can detect phrases you type repeatedly and suggest turning them into snippets — saving you even more time.

How It Works

  1. As you type, Wordy analyzes your typing patterns in the background
  2. When the same multi-word phrase (3+ words) appears 3 or more times, it becomes a suggestion
  3. The menu bar icon changes to a lightbulb to let you know suggestions are available
  4. Click Suggestions in the menu bar dropdown to view them

Viewing and Acting on Suggestions

The Suggestions sheet shows each detected phrase with:

  • The repeated phrase
  • How many times you've typed it
  • A Create Snippet button to turn it into a snippet instantly
  • A dismiss button (×) to remove suggestions you don't want

Clicking Create Snippet opens the snippet editor with:

  • The phrase as the replacement text
  • An auto-generated trigger (; + first letters of each word)
  • You can customize the trigger and title before saving

Settings

Toggle snippet suggestions on or off in Settings → General → Suggest snippets.

Privacy & Performance

  • Detection runs entirely in-memory — no typing data is saved to disk or sent anywhere
  • Suggestions reset when you quit the app
  • The detection runs in a separate, isolated process from snippet expansion — it cannot interfere with your typing or trigger detection
  • Minimal memory footprint: stores up to 50 recent text segments and 500 phrase candidates

Settings

Open Settings from the menu bar or press ⌘,. In 1.4.5, a persistent sidebar has six sections. Changes apply automatically.

SectionWhat you will find
GeneralStartup, Dock visibility, expansion sound and suggestions
Keyboard ShortcutsQuick Search, Translate Selection and Rewrite Selection
Library & SynciCloud, Wordy library import/export, Transfer with TextExpander or CSV
AI & TranslationAnthropic API key, AI model and Translate into
LicenseStatus, offline deadline, activation and recovery
UpdatesInstalled version/build and update checks

General

SettingPurposeDefault for a new installation
Launch at loginStart Wordy when you sign inOff
Show Wordy in the DockKeep Wordy visible in the Dock as well as the menu barOn
Play a sound after expansionAudio feedback after expandingOn
Suggest snippetsSuggest snippets from repeated phrasesOn

Keyboard Shortcut Settings

Choose Keyboard Shortcuts, then Record Shortcut beside Quick Search, Translate Selection or Rewrite Selection. Press a combination containing Command, Control or Option and a key. Escape or Cancel stops recording; leaving the section or window also stops it. Use Reset to Default to restore an action's shortcut.

Defaults are Option+Space for Quick Search, Option+T for Translate Selection and Control+Shift+R for Rewrite Selection.

AI & Translation Settings

Save your Anthropic API key here and choose the model and Translate into language. The default model in 1.4.5 is Claude Sonnet 4.6; Claude Haiku 4.5 is also available. The default translation target is English. These preferences stay on this Mac. API-key save errors appear here without discarding an existing saved key.

License & Offline Access

After a successful online license check, an activated copy can work offline for up to seven days, or until its license expires if sooner. This changes the 30-day allowance in 1.4.4. Failed checks and restarting Wordy do not extend the deadline. At expiry, expansion pauses until verification succeeds; a license rejection can stop access sooner. The seven-day free trial is separate from licensed offline access.

After upgrading an existing activation, connect once to verify it and establish protected offline access:

  1. Open Settings > License.
  2. Choose Check License while online.
  3. Check the status and offline deadline shown on that page.

Wordy reuses the existing activation. It also checks automatically while running and after waking. Successful verification can resume expansion without restarting. Activate License…, Check License and Deactivate License are the normal controls; the page also shows the masked key and customer email.

Interrupted activation or deactivation

If protected storage is unavailable, use Retry License Storage. If activation needs confirmation, contact support with the displayed reference. Use Recover Activation and Activation ID provided by support when support supplies the ID. Use Support removed this activation… and Yes, allow a new activation only after support confirms removal. Repeated activation attempts can consume slots, so follow the recovery flow.

Deactivation requires internet access. If interrupted, expansion remains paused while deactivation is pending, including after a restart. Reconnect and choose Retry Deactivation. License state is protected in this Mac's non-synchronizing Keychain and is not transferred in a library export.

Updates

The Updates section shows the installed version and build. Use Check for updates automatically for periodic checks, or Check for Updates Now to check manually. You can also choose Check for Updates... from the menu bar. When an update is offered, review its release notes and follow the download and install controls.

iCloud Sync

Open Settings > Library & Sync > Keep your Macs in sync and enable Sync with iCloud. It defaults to off for new settings; existing preferences are retained. Use the same iCloud account on each Mac with iCloud Drive available. Update every Mac to 1.4.5 to use the same library and sync behavior.

Sync includes snippets, folders, saved variables and rewrite prompts, including their deletions. Device preferences, keyboard shortcuts, credentials, counters, remembered values, history and statistics are not part of library sync. To move content between different iCloud accounts, export and import a Wordy file.

Sync Now starts a manual sync. Status can show Ready to sync, Syncing…, Library synced, Last synced … ago, iCloud unavailable, or an error. Local saves continue while iCloud is busy or offline. Unreadable cloud data is reported as an error rather than treated as an empty library.

If a sync would remove many snippets, Wordy pauses it and shows a warning. Review the change, use Reveal in Finder to inspect the saved snapshot, choose Apply this sync only if it is the version you want, or Cancel to keep the current library and leave sync paused.


Quick Search lets you find and expand any snippet instantly from any app, without needing to remember its trigger.

Overview

Press ⌥Space (Option+Space) from any application to open the Quick Search panel. A floating search bar appears in the center of your screen.

Using Quick Search

  1. Start typing to filter snippets by title or trigger
  2. Use ↑↓ arrow keys to navigate results
  3. Press Return to expand the selected snippet into the app you were working in
  4. Press Escape to close without expanding

The search ranks results by relevance: exact matches appear first, then prefix matches, then partial matches.

How Expansion Works

When you open Quick Search, Wordy remembers the app, text field and cursor position you were working in. When you select a snippet:

  • The Quick Search panel closes
  • The app you were previously working in regains focus
  • The snippet text is inserted at your cursor position. If you had text selected, the snippet replaces it — even if the snippet produces no text
  • If the snippet has fill-in fields, the fill-in form appears as usual

If a different app is in front by the time the text is ready, or a password field or secure input is now active, Wordy doesn't type anything. Instead it shows an Insertion stopped alert with a Copy Result button. Closing Quick Search without choosing a snippet cancels the insertion.

Customizing the Hotkey

The default shortcut is ⌥Space. To change it:

  1. Open Settings (⌘,)
  2. Choose Keyboard Shortcuts, then find Quick Search
  3. Click Record Shortcut and press your preferred key combination
  4. The shortcut must include Command, Option or Control with a key; Shift alone is not enough
  5. Click Reset to Default to restore ⌥Space

Keyboard Shortcuts

ShortcutAction
⌥SpaceOpen Quick Search
⌘⇧NNew snippet
⌘,Open Settings
⌘⇧PPause/Resume expansion
⌘QQuit Wordy
⌘↩Save snippet and return to the list (in editor)
⎋ (Escape)Cancel/close; in the snippet editor, go back to the list (asks first if you have unsaved changes)
↩ (Return)Expand (in the fill-in window)
⌫ (Delete)Delete selected snippet(s)

Statistics

Track your productivity in Menu Bar → Statistics:

Statistics view in Wordy

Lifetime Stats

  • Total expansions
  • Characters saved
  • Time saved
  • First expansion date

Last 7 Days

  • Daily expansion chart
  • Hourly usage distribution
  • Top 5 most-used snippets

Pause/Resume

Need to type a trigger literally without expansion? Pause Wordy temporarily:

  • Menu Bar → Pause Expansion
  • Or press ⌘⇧P

Resume the same way when you're ready.

Pausing also cancels any insertion that is still waiting — for example, a snippet whose shell command is still running — so nothing is typed after you pause. Starting another expansion cancels an older waiting one in the same way.


Secure Input Detection

macOS enables "secure input" mode when focus is in password fields, blocking keyboard monitoring for security. Wordy detects this and provides visual feedback so you know when expansions are temporarily unavailable.

How it works

  • Menu bar icon changes to a lock icon when secure input is active
  • Dropdown menu shows "Blocked by [AppName]" to identify which app enabled secure input
  • Uses ioreg command to read kCGSSessionSecureInputPID from I/O Registry, then resolves to app name
  • Falls back to frontmost app if I/O Registry doesn't provide the PID
  • Automatic detection — Wordy checks every 0.5 seconds while running

Note: There's a known macOS bug where if an app enables secure input while in the background, the reported PID may be wrong. For the typical case (clicking in a password field), it works correctly.

When does secure input activate?

Secure input is typically enabled when you're typing in:

  • Password fields in browsers and apps
  • Keychain and security dialogs
  • Some banking and payment apps
  • Any field marked as secure by the app developer

This is a macOS security feature—Wordy automatically resumes normal operation once you leave the secure field.

Secure input during an insertion

Wordy also checks for secure input and password fields just before it types. If you expanded a snippet from the fill-in window or Quick Search, or a slow snippet was still running, and secure input or a password field is now active, Wordy stops instead of typing. An Insertion stopped alert lets you copy the result instead.


Troubleshooting

Snippets not expanding

  1. Check accessibility permission: System Settings → Privacy & Security → Accessibility → Wordy (enabled)
  2. Check if paused: Look for "Resume Expansion" in the menu bar menu
  3. Test in different apps: Some apps handle input differently

Fill-in form not appearing

  • Ensure your snippet contains fill-in placeholders ({{field:...}}, {{textarea:...}}, {{dropdown:...}}, {{datepicker:...}}, {{?:...}}, or {{note:...}})
  • The form only appears when there are fields to fill (or notes to display)

iCloud not syncing

  1. Ensure you're signed into iCloud on your Mac
  2. Check that iCloud Drive is enabled
  3. Try Sync Now in Settings
  4. Check the sync status indicator for errors

Sync paused warning

If Wordy shows a yellow warning in the menu bar, it means iCloud sync was paused because the incoming sync data would remove a large number of snippets.

  • Choose Apply this sync only if the incoming iCloud version is the version you want to keep
  • Choose Reveal in Finder if you want to inspect the saved copy first
  • Choose Cancel if you want to keep your current snippets

iCloud unavailable warning

If Wordy cannot reach iCloud for several minutes after launch, macOS may show a notification that sync is paused. Check your internet connection, iCloud Drive status, and available iCloud storage. Wordy will try again the next time it launches.

Library Loading & Saving Problems

If Wordy shows Library unavailable, editing pauses until the library can be loaded. Choose Retry Loading or Show Library Files to inspect the preserved files. Do not edit an incompletely loaded library.

Wordy finishes pending local library, settings, API-key and auxiliary saves before quitting. If it shows Wordy could not finish saving, the app stays open so you can resolve the reported error and retry. Let an active import finish before quitting.

For import errors, see Import Troubleshooting. For expired offline access or interrupted activation, see License & Offline Access.

Insertion stopped

Before typing, Wordy checks that the text is still going to the place you expanded it from. This matters when there's a delay: when you fill in a form, use Quick Search, or expand a snippet that runs JavaScript or a shell command. If the destination has changed, Wordy stops instead of typing into the wrong place and shows an Insertion stopped alert:

  • Copy Result copies the finished text to your clipboard, so you can paste it where you need it
  • Dismiss closes the alert

The alert shows the reason for this insertion stopping:

Reason shownWhat it meansWhat to do
Another app is in front, the app didn't come to the front, or the target app changedYou switched apps before the text was readyStay in the original app until the text appears, or paste the copied result
A different text field is focused, the caret moved, the field's text changed, or the trigger is no longer just before the caretYou clicked into another field or kept typing while a slow snippet (JavaScript or shell) was runningWait for slow snippets to finish before moving the cursor. Stopping here is deliberate, so the text never lands in the wrong spot
Secure input is enabled, or the focused field is a password fieldmacOS is protecting a password field, or an app like Terminal has secure keyboard entry onLeave the password field, or turn off secure keyboard entry in the app. See Secure Input Detection
Accessibility permission is not granted to this copy of WordyWordy can't check where the text is goingEnable Wordy in System Settings → Privacy & Security → Accessibility. If it's already on, remove it and add it again
The text field, insertion point or trigger could not be identified or verifiedThe app didn't tell Wordy enough about where you were typingTry again. If it keeps happening in one app, paste the copied result

In 1.4.5, fill-in and Quick Search insertion can continue in the original app when a browser recreates its field while the trigger is removed. Wordy still checks the frontmost app, Accessibility permission, secure input, password fields and cancellation. Slow typed expansions and AI replacements keep stricter destination checks. The alert retains the reason from that specific insertion, even if another insertion finishes. If a particular website still fails, copy the result and include the displayed reason when contacting support.

Global variable shows [#Name?]

This means the variable isn't defined:

  1. Open the Global Variables window from the sidebar
  2. Check if the variable exists (use search to find it)
  3. Verify the spelling matches exactly (names are case-insensitive)
  4. Create the variable if it doesn't exist

Data Storage

Local data: ~/Library/Application Support/Wordy/

iCloud data (if enabled): ~/Library/Mobile Documents/com~apple~CloudDocs/Wordy/

Use Export Library… for a portable content backup rather than copying individual internal JSON files. API keys and license state are stored separately in this Mac's Keychain and are excluded from library export and sync.

Wordy keeps rolling backups under ~/Library/Application Support/Wordy/Backups/ and creates a separate recovery folder before each JSON import. Follow the backup's RESTORE.txt for complete local recovery, or import its library.json to recover selected content. Preserve current files first and disable sync before a manual restore. Re-enabling sync merges cloud content rather than rolling back other Macs.

With iCloud enabled, Wordy also keeps snapshots before uploading new sync data. Rapid saves retain separate recovery snapshots. See Import Backups & Recovery for the limits of restoration.


System Requirements

  • macOS 14.0 (Sonoma) or later
  • Accessibility permission (required)
  • iCloud account (optional, for sync)