English | 简体中文
SnipKey is a macOS menu bar text expansion tool. Type #trigger in any app to open a completion panel or expand directly into preconfigured text.
Project site: https://alohalt.github.io/SnipKey/. The content under site/ is deployed through GitHub Actions, and the repository Pages source should be set to GitHub Actions.
- Monitors keyboard input globally and captures triggers prefixed with
#across the system. - Shows a floating completion panel near the cursor with matching results, supporting arrow navigation,
TaborEnterto confirm,Escto cancel, plus mouse hover highlight and click-to-insert. - Cancels the current completion session immediately when clicking outside the panel, reducing the risk of inserting text into the wrong target.
- Runs from the menu bar and provides quick entry points for permission guidance, settings, and clipboard history.
- Includes a native three-column settings UI with grouping, search, create, edit, delete, and JSON import/export.
- Supports runtime UI language switching between English and Simplified Chinese. The default remains Simplified Chinese, and switching only affects UI copy, not existing Keys, groups, or clipboard data.
- Restricts triggers to letters, numbers, and underscores, with uniqueness validation enforced on save.
- Supports dynamic variables:
{date},{time},{clipboard}, and{cursor}. - Records clipboard history and suggests creating a new Key when content is copied repeatedly. The UI retains the latest 50 records while suggestion counters remain independent from the visible list.
- Sorts candidates by acceptance count so frequently used Keys appear earlier.
.
├── Sources/
│ ├── SnipKeyCore/ # Testable core logic: data models, matching, variable resolution, persistence
│ └── SnipKeyApp/ # macOS app layer: menu bar, permissions, keyboard monitoring, settings UI, completion panel
├── Tests/
│ └── SnipKeyCoreTests/ # Unit tests for the core layer
├── Resources/ # Info.plist, entitlements, app icon resources
├── Scripts/ # Helper scripts
└── docs/ # Design notes, signing flow, and requirement history
- macOS 13+
- Swift 5.9+
- Xcode, recommended for signing and more stable permission behavior
- Accessibility permission
Running the signed development app bundle is recommended over swift run. This keeps macOS permissions attached to a stable app identity instead of a frequently rebuilt executable path.
make signing-help
make bootstrap-personal-team
make runIf an Apple Development certificate is already available on the machine, these two commands are usually enough:
make test
make runCommon commands:
make build # Build with SwiftPM
make test # Run unit tests
make run # Install and launch the signed development app
make run-swift # Run the Swift executable directly; not recommended for permission debugging
make verify-dev # Inspect the signed development bundle
make package-dmg # Build a distributable DMGFor the full signing workflow, see docs/development-signing.md.
- Launch the app and open Settings from the menu bar.
- Create a new Key. For example, use
accountas the trigger and enter the text that should be inserted. Triggers support only letters, numbers, and underscores, and they must be unique. - Return to any text input field and type
#account. - Use
Tab,Enter, or a mouse click on the candidate item to confirm expansion. Clicking outside the hint panel cancels the current completion session.
The settings sidebar includes a language switcher for English and Simplified Chinese.
When expansion is confirmed, SnipKey deletes the typed trigger content and inserts the resolved replacement text.
If existing local data contains Chinese, invalid, or duplicate triggers, the app normalizes them during load or import into legal, unique triggers automatically.
- Key data:
~/Library/Application Support/SnipKey/snippets.json - Clipboard history:
~/Library/Application Support/SnipKey/clipboard-history.json— the UI keeps the latest 50 records, and clearing history also resets suggestion counters - UI language preference:
SnipKey.appLanguageinUserDefaults, stored separately from Key and clipboard JSON data
The repository currently focuses test coverage on SnipKeyCore:
SnippetStoreTestsSnippetEngineTestsVariableResolverTestsClipboardHistoryStoreTestsModelsTests
AppKit and system-permission-related behavior is still validated primarily through manual testing.