{"id":46869113,"url":"https://github.com/jaynguyen-vn/gen-snippets","last_synced_at":"2026-06-17T07:01:20.044Z","repository":{"id":313000418,"uuid":"1049621433","full_name":"jaynguyen-vn/gen-snippets","owner":"jaynguyen-vn","description":"A privacy-focused macOS text expander that works system-wide. Type short commands, get instant text replacement. 100% offline, native SwiftUI. Your productivity booster that respects your data.","archived":false,"fork":false,"pushed_at":"2026-05-28T04:15:43.000Z","size":628,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T06:22:51.065Z","etag":null,"topics":["developer-tools","macos","open-source","productivity","swift","text-expander"],"latest_commit_sha":null,"homepage":"http://gensnippets.com/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaynguyen-vn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-03T08:50:50.000Z","updated_at":"2026-05-28T04:15:47.000Z","dependencies_parsed_at":"2025-09-03T10:27:14.161Z","dependency_job_id":"bf925911-6745-48f7-98e4-ef97a556e7bc","html_url":"https://github.com/jaynguyen-vn/gen-snippets","commit_stats":null,"previous_names":["jaynguyen-vn/gen-snippets"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/jaynguyen-vn/gen-snippets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaynguyen-vn%2Fgen-snippets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaynguyen-vn%2Fgen-snippets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaynguyen-vn%2Fgen-snippets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaynguyen-vn%2Fgen-snippets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaynguyen-vn","download_url":"https://codeload.github.com/jaynguyen-vn/gen-snippets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaynguyen-vn%2Fgen-snippets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34437451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","macos","open-source","productivity","swift","text-expander"],"created_at":"2026-03-10T19:32:51.829Z","updated_at":"2026-06-17T07:01:20.032Z","avatar_url":"https://github.com/jaynguyen-vn.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GenSnippets\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-macOS%2011.5%2B-blue\" alt=\"macOS 11.5+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Swift-5.5%2B-orange\" alt=\"Swift 5.5+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green\" alt=\"MIT License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Version-2.9.8-purple\" alt=\"Version 2.9.8\"\u003e\n\u003c/div\u003e\n\n## Overview\n\nGenSnippets is a lightweight macOS application for system-wide text expansion. It runs quietly in your menu bar, monitoring keyboard input and instantly replacing custom trigger commands with pre-defined text snippets across all applications.\n\n## Features\n\n### Core Functionality\n- **System-wide Text Replacement** - Works in any application across macOS using CGEvent monitoring\n- **Category Management** - Organize snippets into custom categories with alphabetical sorting\n- **Smart Command Matching** - Trie data structure provides O(m) lookup performance\n- **Priority Matching** - Longer commands take precedence for accurate replacements\n- **Auto-cleanup** - Automatically removes typed commands after replacement\n- **Dynamic Content** - Insert clipboard content, current date, or position cursor with special keywords\n- **Security Buffer** - 15-second timeout prevents accidental replacements of old inputs\n- **Browser Compatibility** - Specialized timing adjustments for Discord, Chrome, and other web browsers\n\n### User Interface\n- **Three-Column Layout** - Intuitive category list, snippet list, and detail view\n- **Menu Bar Integration** - Quick access from the system menu bar with snippet count\n- **Native macOS Design** - Built with SwiftUI for a seamless experience\n- **Flexible Visibility** - Toggle between dock and menu bar visibility\n- **Quick Search** - Global hotkey (default: Cmd+Ctrl+S) opens instant snippet search\n- **Customizable Shortcuts** - Configure your preferred keyboard shortcuts\n\n### Data Management\n- **100% Offline** - All data stored locally in UserDefaults with batch saving\n- **Export/Import** - Backup and share your snippet collections as JSON\n- **Privacy-First** - Your data never leaves your device\n- **Optimized Storage** - Caching layer with batch operations for performance\n\n### Advanced Features\n- **Auto-Update** - Built-in Sparkle integration checks for updates automatically\n- **Usage Tracking** - Command-based usage tracking for accurate statistics\n- **Insights Dashboard** - Monitor snippet usage patterns and analytics\n- **Multi-language Support** - Localization infrastructure ready for expansion\n- **Accessibility Integration** - Full macOS accessibility permission handling\n- **Performance Optimized** - Trie-based matching with memory-efficient caching\n- **Smart Keywords** - Dynamic content insertion with multiple placeholders:\n  - `{clipboard}` - Current clipboard content\n  - `{cursor}` - Cursor positioning after insertion\n  - `{timestamp}` - Unix timestamp\n  - `{random-number}` - Random number (1-1000)\n  - `{dd/mm}` - Current date (day/month format)\n  - `{dd/mm/yyyy}` - Full date format\n  - `{time}` - Current time (HH:mm:ss)\n  - `{uuid}` - Unique identifier\n- **Metafields (Dynamic Fields)** - Custom placeholders that prompt for input:\n  - `{{field}}` - Prompts for a value before insertion\n  - `{{field:default}}` - Prompts with a pre-filled default value\n  - Live preview shows the result as you type\n  - Perfect for templates with variable content\n- **Batch Operations** - Efficient batch saving and loading for large snippet collections\n\n## Installation\n\n### Download\n\n1. Download the latest DMG from [Releases](https://github.com/jaynguyen-vn/gen-snippets/releases)\n2. Open the DMG and drag **GenSnippets** to your Applications folder\n3. Since the app is not notarized with Apple, macOS Gatekeeper will block it on first launch. To allow it, use **one** of these methods:\n\n   **Option A — GUI (recommended):**\n   - Double-click GenSnippets — you'll see a warning dialog, click **Done** (or **Cancel**)\n   - Open **System Settings → Privacy \u0026 Security**\n   - Scroll down to the **Security** section — you'll see *\"GenSnippets\" was blocked from use because it is not from an identified developer*\n   - Click **Open Anyway** and confirm\n\n   **Option B — Terminal:**\n   ```bash\n   xattr -cr /Applications/GenSnippets.app\n   ```\n\n4. Open GenSnippets — it will ask for **Accessibility** permission\n5. Grant permission in **System Settings → Privacy \u0026 Security → Accessibility**\n6. **Quit and reopen** GenSnippets for the permission to take effect\n\n### Requirements\n- macOS 11.5 (Big Sur) or later\n- Xcode 13.0+ (for building from source)\n\n### Building from Source\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/jaynguyen-vn/gen-snippets\ncd gen-snippets/GenSnippets\n```\n\n2. Open in Xcode:\n```bash\nopen GenSnippets.xcodeproj\n```\n\n3. Build and run:\n   - Select the \"GenSnippets\" scheme\n   - Press `⌘R` to build and run\n\nOr build from command line:\n```bash\n# Debug build\nxcodebuild -project GenSnippets.xcodeproj -scheme \"GenSnippets\" -configuration Debug build\n\n# Release build\nxcodebuild -project GenSnippets.xcodeproj -scheme \"GenSnippets\" -configuration Release build\n\n# Run the app (path may vary based on build settings)\nopen ~/Library/Developer/Xcode/DerivedData/GenSnippets-*/Build/Products/Debug/GenSnippets.app\n```\n\n## Getting Started\n\n### First Launch\n\n1. **Create Your First Snippet**:\n   - Click the \"+\" button in the snippet list\n   - Enter a command trigger (e.g., `!email`)\n   - Enter the replacement text (e.g., `john.doe@example.com`)\n   - Click \"Save\"\n\n2. **Test It Out**:\n   - Open any application (TextEdit, Safari, etc.)\n   - Type your command trigger\n   - Watch it instantly replace with your snippet!\n\n### Organizing Snippets\n\nCategories help you organize related snippets:\n- Create categories for different contexts (Work, Personal, Code, etc.)\n- The \"Uncategory\" is always available for miscellaneous snippets\n- Deleted categories automatically move their snippets to Uncategory\n\n## Usage Examples\n\n### Email Templates\n- Command: `!sig` → Your full email signature\n- Command: `!thanks` → \"Thank you for your time and consideration.\"\n\n### Code Snippets\n- Command: `!lorem` → Lorem ipsum placeholder text\n- Command: `!copyright` → Copyright notice with current year\n\n### Frequent Phrases\n- Command: `!addr` → Your full address\n- Command: `!phone` → Your phone number\n\n### Dynamic Content\n- Command: `!timestamp` → \"Log entry {timestamp}\" (inserts Unix timestamp)\n- Command: `!template` → \"Dear {cursor},\" (positions cursor after insertion)\n- Command: `!paste` → \"{clipboard}\" (inserts current clipboard content)\n- Command: `!log` → \"[{time}] {uuid}: \" (inserts time and unique ID)\n- Command: `!today` → \"Date: {dd/mm/yyyy}\" (inserts today's date)\n\n### Metafields (Dynamic Input)\n- Command: `!hello` → \"Hello {{name}}, welcome to {{company}}!\"\n  - Prompts for \"name\" and \"company\" values before insertion\n- Command: `!email` → \"Hi {{name:John}}, ...\"\n  - Prompts with \"John\" as the default value for \"name\"\n- Command: `!meeting` → \"Meeting with {{client}} on {{date}} at {{time:10:00 AM}}\"\n  - Mix of required and default-value fields\n\n## Configuration\n\n### Settings Options\n\n- **Automatic Updates** - Enable/disable automatic update checks\n- **Check for Updates** - Manually check for new versions\n- **Menu Bar Icon** - Show/hide the menu bar icon with snippet count\n- **Dock Icon** - Show/hide the dock icon\n- **Launch at Login** - Automatically start GenSnippets when you log in\n- **Global Hotkey** - Customize the keyboard shortcut (default: Cmd+Ctrl+S)\n- **Search View** - Quick access to snippet search with customizable shortcut\n\n### Data Storage\n\nLocal data is stored in:\n```\n~/Library/Preferences/Jay8448.Gen-Snippets.plist    # Snippets, categories, settings\n~/Library/Application Support/GenSnippets/RichContent/  # Images, files (since v2.8.0)\n```\n\n## Architecture\n\n### Technology Stack\n- **Language**: Swift 5.5+\n- **UI Framework**: SwiftUI\n- **Platform**: macOS 11.5+\n- **Storage**: UserDefaults (local only, JSON format)\n- **Dependencies**: [Sparkle 2.x](https://sparkle-project.org/) for auto-updates\n\n### MVVM + Service Layer Design\n\n**Services** handle business logic (singletons, thread-safe):\n- **TextReplacementService**: Core engine with Trie for O(m) matching\n- **LocalStorageService**: Batch-optimized UserDefaults with caching\n- **MetafieldService**: Dynamic placeholder parsing and input dialog\n- **RichContentService**: Sequential image/file/URL insertion (file-based storage)\n- **EdgeCaseHandler**: App-specific timing (Discord, browsers, IDEs, terminals, Ghostty)\n- **ShareService**: Import/export with conflict resolution\n- **SandboxMigrationService**: Handles transition from sandboxed to non-sandboxed environment\n\n**ViewModels** manage UI state (@Published, reactive):\n- **LocalSnippetsViewModel**: Snippet CRUD + batch operations\n- **CategoryViewModel**: Category management with alphabetical sorting\n\n**Views** use SwiftUI with Design System tokens (DS*):\n- ThreeColumnView, SnippetDetailView, AddSnippetSheet, etc.\n\nFor detailed architecture: see [docs/system-architecture.md](docs/system-architecture.md)\n\n## Documentation\n\nComplete developer documentation in `docs/`:\n\n- **[Project Overview \u0026 PDR](docs/project-overview-pdr.md)** - Vision, features, requirements, roadmap\n- **[Codebase Summary](docs/codebase-summary.md)** - Directory structure, 48 Swift files, LOC breakdown\n- **[Code Standards](docs/code-standards.md)** - Swift conventions, naming, patterns, design system usage\n- **[System Architecture](docs/system-architecture.md)** - MVVM design, data flow, threading, event system\n- **[Project Roadmap](docs/project-roadmap.md)** - Version history, upcoming plans, technical debt\n- **[Deployment Guide](docs/deployment-guide.md)** - Build, code signing, DMG creation, release process\n\n## Contributing\n\nContributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- Code of conduct\n- Development setup (see docs/)\n- Pull request process\n- Reporting issues\n\n**Before Contributing:**\n1. Read [Code Standards](docs/code-standards.md)\n2. Read [System Architecture](docs/system-architecture.md)\n3. Follow MVVM + Service Layer patterns\n4. Keep files \u003c400 LOC, views \u003c300 LOC\n\n## License\n\nGenSnippets is released under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built for the macOS community\n- Thanks to all contributors and users\n- Special thanks to the SwiftUI team for the amazing framework\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/jaynguyen-vn/gen-snippets/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/jaynguyen-vn/gen-snippets/discussions)\n- **Email**: truongnd0001@gmail.com\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  Made for productivity enthusiasts\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaynguyen-vn%2Fgen-snippets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaynguyen-vn%2Fgen-snippets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaynguyen-vn%2Fgen-snippets/lists"}