{"id":50990178,"url":"https://github.com/ruanwenjun/quick-thoughts","last_synced_at":"2026-06-20T01:30:43.570Z","repository":{"id":356678408,"uuid":"1233618851","full_name":"ruanwenjun/quick-thoughts","owner":"ruanwenjun","description":"💭 一个轻量的 macOS 菜单栏小工具，按 ⌥⌘T 弹窗输入、回车保存，让一闪而过的想法不再溜走。","archived":false,"fork":false,"pushed_at":"2026-05-09T07:02:11.000Z","size":177,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T08:40:15.511Z","etag":null,"topics":["macos","note-taking","quick-capture","spotlight"],"latest_commit_sha":null,"homepage":"","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/ruanwenjun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2026-05-09T06:43:08.000Z","updated_at":"2026-05-09T07:13:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ruanwenjun/quick-thoughts","commit_stats":null,"previous_names":["ruanwenjun/quick-thoughts"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ruanwenjun/quick-thoughts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruanwenjun%2Fquick-thoughts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruanwenjun%2Fquick-thoughts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruanwenjun%2Fquick-thoughts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruanwenjun%2Fquick-thoughts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruanwenjun","download_url":"https://codeload.github.com/ruanwenjun/quick-thoughts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruanwenjun%2Fquick-thoughts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34554511,"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-19T02:00:06.005Z","response_time":61,"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":["macos","note-taking","quick-capture","spotlight"],"created_at":"2026-06-20T01:30:39.523Z","updated_at":"2026-06-20T01:30:43.557Z","avatar_url":"https://github.com/ruanwenjun.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 💭 Quick Thoughts\n\n**Catch fleeting thoughts before they slip away.**\n\nA menu bar–resident macOS app for capturing thoughts: hit a global shortcut, type, press return.\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![macOS](https://img.shields.io/badge/macOS-13%2B-blue)](https://www.apple.com/macos)\n[![Swift](https://img.shields.io/badge/Swift-5.9%2B-orange?logo=swift\u0026logoColor=white)](https://swift.org)\n[![SwiftUI](https://img.shields.io/badge/SwiftUI-native-blueviolet?logo=swift\u0026logoColor=white)]()\n\n**English** · [中文](README.zh-CN.md)\n\n\u003c/div\u003e\n\n---\n\n## 💡 Motivation\n\nWhile coding, reading docs, or sitting in a meeting, ideas flash by: a possible cause for a bug, a small improvement, a message to send, an email to reply to. They vanish in seconds.\n\nOpening Notion / Apple Notes / Bear is too heavy — switch apps, find the notebook, place the cursor, type, save, switch back, and the thread of thought is already broken.\n\nQuick Thoughts does exactly one thing: **from any app, ⌥⌘T → type → Enter, three steps**. Light enough not to interrupt your flow, structured enough to browse / search / clean up later.\n\n## ✨ Features\n\n- ⌨️ **Global hotkey** (default `⌥⌘T`, customizable) — never break the current flow\n- 📝 **Spotlight-style popup**: multi-line input, `Enter` to save, `Shift+Enter` for newline, `Esc` to cancel\n- 🗂 **Draft preservation**: closing the popup (clicking outside / Esc) keeps your text for next time\n- 🔍 **Full-text search**: instant filtering in the main panel, case-insensitive\n- ✏️ **Inline edit / delete**: hover-revealed actions, delete asks for confirmation\n- 💾 **Single-file JSON storage**: easy to back up, migrate, grep\n- 🛡️ **Crash-safe**: atomic writes, auto-backup of corrupt files, schema version guard\n- 🌗 **Light / dark adaptive**: follows the system appearance\n- 🌐 **Bilingual UI**: English + 简体中文, switch in Settings\n- 🪶 **Featherweight**: menu bar–only, no Dock icon, native Swift + SwiftUI, no Electron baggage\n\n## 🚀 Install\n\n### Requirements\n\n- **Runtime**: macOS 13.0 or later\n- **Build from source**: [full Xcode](https://apps.apple.com/app/xcode/id497799835) (free, Mac App Store).\n  - Command Line Tools alone (`xcode-select --install`) is not enough: the `KeyboardShortcuts` dependency uses `#Preview` macros (needs the Xcode macro plugin), and `swift test` needs Xcode's bundled XCTest framework.\n  - After installing Xcode, let it install additional components on first launch, then switch the toolchain:\n    ```bash\n    sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer\n    ```\n\n### Option A — Download from Releases (recommended for end users)\n\n\u003e First release pending.\n\n1. Grab the latest `Quick-Thoughts-x.y.z.zip` from [Releases](https://github.com/ruanwenjun/quick-thoughts/releases)\n2. Unzip, drag `Quick Thoughts.app` to `/Applications`\n3. **First launch**: right-click → Open → click **Open** in the warning dialog (one-time Gatekeeper bypass since the app isn't notarized yet; double-click works thereafter)\n\n### Option B — Build from source (recommended for developers)\n\n```bash\ngit clone https://github.com/ruanwenjun/quick-thoughts.git\ncd quick-thoughts\nmake install        # → /Applications, requires sudo\n# or sudo-free:\nmake install-user   # → ~/Applications\n```\n\n`make install` runs a release build, produces the `.app` bundle, ad-hoc signs it, and copies it to the target directory.\n\n## 🎯 Usage\n\n| Action | Shortcut |\n| --- | --- |\n| Open capture popup | `⌥⌘T` (configurable) |\n| Newline in popup | `Shift+Enter` |\n| Save \u0026 close popup | `Enter` |\n| Cancel popup (keep draft) | `Esc` |\n| Open Settings | `⌘,` |\n\nClick the menu bar icon for \"New Thought / Open Panel / Settings… / Quit\".\n\nIn the main panel, **hover** any row to reveal ✏️ edit and 🗑️ delete (delete shows an inline confirmation first to prevent mistakes); the toolbar search box filters in real time.\n\nThe Settings window has a **Language** picker — `Auto / English / 中文`. `Auto` follows the system language (Chinese variants → 中文, otherwise English).\n\n### Launch at login\n\nThe recommended path is to add `Quick Thoughts` under **System Settings → General → Login Items**.\n\n\u003e Settings also has a \"Launch at login\" toggle (built on `SMAppService`), but that API needs a properly signed app to work reliably; with the current ad-hoc–signed build it may fail — the inline red error is expected. The System Settings approach is more reliable.\n\n## ⚙️ Data Storage\n\n```\n~/Library/Application Support/QuickThoughts/thoughts.json\n```\n\nA simple, stable format — easy to back up, grep, or migrate by hand:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"thoughts\": [\n    {\n      \"id\": \"5C9E1F8A-...\",\n      \"content\": \"Saw a nice design today\",\n      \"createdAt\": \"2026-05-09T10:23:45Z\",\n      \"updatedAt\": \"2026-05-09T10:23:45Z\"\n    }\n  ]\n}\n```\n\nSettings shows the current path with a \"Show in Finder\" button.\n\nFile I/O strategy:\n- **Atomic writes**: write `thoughts.json.tmp` first, then `replaceItemAt` / `moveItem` — a crash doesn't lose the previous file\n- **Debounced**: continuous edits flush 500 ms after the last keystroke; a forced flush runs on `willTerminate`\n- **Corruption recovery**: JSON decode failure → backs up the original as `thoughts.json.corrupt-\u003ctimestamp\u003e-\u003cuuid\u003e`, starts with an empty database\n- **Schema guard**: reading a higher `schemaVersion` than supported aborts writes and prompts the user to upgrade\n\n## 🛣️ Roadmap\n\n**v1 shipped**: capture, browse, search, edit, delete, settings, JSON persistence, menu bar app, Spotlight-style popup, card-style main panel, bilingual UI.\n\n**Explicitly not in v1 (YAGNI)**: iCloud sync, iOS / web clients, tags / folders, rich text / Markdown rendering, image attachments, reminders / alarms, multi-account.\n\n**Possible future work (issues / discussion welcome)**:\n\n- [ ] Apple Developer signing + notarization → double-click `.dmg` install, stable `SMAppService` launch-at-login\n- [ ] Homebrew Cask (`brew install --cask quick-thoughts`)\n- [ ] GitHub Actions CI: tag → build / sign / publish Release\n- [ ] Tags / lightweight Markdown rendering\n- [ ] Export / one-click zip backup\n\n## 🛠️ Development\n\n```bash\nmake build      # swift build (debug)\nmake test       # swift test — 16 cases covering the data layer\nmake run        # swift run (terminal blocks; closing it kills the app)\nmake bundle     # bundle .app into dist/ only\nmake uninstall  # remove the installed .app\nmake clean      # wipe .build / dist\n```\n\n### Project structure\n\n```\nSources/QuickThoughts/\n├── QuickThoughtsApp.swift                 entry; MenuBarExtra + Window + Settings\n├── Models/Thought.swift                   data model\n├── Storage/\n│   ├── JSONFileRepository.swift           atomic write, corruption backup, schema guard\n│   └── ThoughtStore.swift                 ObservableObject + CRUD + debounced flush\n├── Features/\n│   ├── MenuBarContent.swift               menu bar menu\n│   ├── Capture/                           capture popup (NSPanel + NSTextView bridge)\n│   └── Browse/                            main panel + card row\n├── Localization/                          bilingual UI (Auto / English / 中文)\n└── Settings/                              shortcut Recorder + login launch\n```\n\nOne runtime dependency: [KeyboardShortcuts](https://github.com/sindresorhus/KeyboardShortcuts) — global shortcut registration + SwiftUI Recorder component.\n\n### Test coverage\n\n```\nThoughtTests              Codable round-trip\nJSONFileRepositoryTests   read / write / missing file / corrupt file / higher schema / nested dirs\nThoughtStoreTests         CRUD / whitespace trim / search / sort / flush / fatalLoadError\n```\n\nUI is not unit-tested; relies on manual smoke testing. Please attach before/after screenshots in PRs that touch UI.\n\n## 🤝 Contributing\n\nIssues and PRs are welcome. Before submitting:\n\n1. `make test` passes\n2. `make build` has no new warnings\n3. Keep changes surgical — don't \"improve\" unrelated code along the way\n4. UI changes should include before/after screenshots\n5. Use lowercase verb-prefixed commits (`feat:` / `fix:` / `style:` / `chore:` etc.)\n\n## 📄 License\n\n[Apache License 2.0](LICENSE) © 2026 ruanwenjun\n\n## 🙏 Acknowledgements\n\n- [Sindre Sorhus](https://github.com/sindresorhus)' [KeyboardShortcuts](https://github.com/sindresorhus/KeyboardShortcuts) — global shortcuts + recording UI with nearly zero code\n- macOS native `MenuBarExtra` / `NSPanel` / `Settings` scenes — the menu bar app substrate\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruanwenjun%2Fquick-thoughts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruanwenjun%2Fquick-thoughts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruanwenjun%2Fquick-thoughts/lists"}