Keybumps is a native macOS utility combining local Quick Search, bounded text-and-image Clipboard History, ScreenGrabs (screenshots and screen recordings), on-device Dictation, Snippets, Timer, Emoji Picker, Translation, Keystrokes, Window Manager, and Shortcut Coach in one app. Search (⌘1), Clipboard History (⌘2), ScreenGrabs (⌘3, screenshots and recordings), Dictation History (⌘4), Snippets (⌘5), Timers (⌘6), Emoji (⌘7, once you turn Emoji Picker on in Settings › Plugins), Translate (⌘8, once you turn Translation on; it needs macOS 15), and Shortcut Coach History (Hotkeys, ⌘9, hidden by default) are the tabs of Quick Search, one Raycast-style, keyboard-first window that ⌘Space opens on Search; with the search field empty, ← and → switch between its tabs. In Timers, type a duration such as 5m or tea 25 and press Return; when it ends, an alarm stays on screen and rings until you stop it. On a highlighted row, ⌘C copies, ⌘V pastes into the app you're using (in Translate, ⌘V pastes into the search field, and a saved translation pastes from its Paste button), and ⌘E edits a screenshot, image, recording, or snippet, and with the search field empty, Space plays a recording or reads a saved translation aloud. Snippets are text you save to reuse: Return or ⌘C copies one and ⌘V pastes it into the app you're using. In Translate, type or paste text and it is translated on this Mac as you type, between the two languages you choose; Return saves the translation to the tab's recent translations (the last 50, kept on this Mac) and ⌘Return saves it and pastes it. With the field empty, the highlighted recent translation shows in full beside the list; Return or ⌘C copies it, its Paste button pastes it, and the detail's Read Aloud button or Space reads it aloud in a macOS voice. Delete removes the highlighted row (in Snippets, Dictation, and Translate it asks first), and the footer names each key, and copies confirm with a brief notice that grows out of the notch.
Keystrokes, once you turn it on in Settings › Plugins, shows the shortcuts you press on screen for demos, recordings, and screen sharing: Keybumps-style keycaps with the action's name ("Copy" with ⌘C), or KeyCastr's classic bezel, at the bottom left, center, or right of the screen with the pointer, with the last one or two above the newest. By default it shows only shortcuts (⌘ or ⌃, or ⌥ with a key that types nothing, such as ⌥←); All keys also shows typing. Nothing shows while you type a password. A screenshot shortcut that macOS or Keybumps knows (macOS's, as you've set them, and ScreenGrabs' screenshot hotkeys and Record Screen) clears the keys at once instead of showing; other apps' screenshot shortcuts aren't known. It can show a ring where you click, and it needs Input Monitoring. To take the keys off the screen without turning Keystrokes off, turn off Show keystrokes at the top of Settings › Keystrokes, or uncheck Show Keystrokes in the menu bar menu, or press the Show & Hide Keystrokes shortcut (unassigned until you set one). Keystrokes remembers which.
ScreenGrabs takes screenshots and records the screen (ADR 0010). Its screenshot hotkeys (⇧⌘2 every screen, ⇧⌘3 every screen then edit, ⇧⌘4 a selected area then edit; they need Screen Recording, and while ScreenGrabs is on they take over macOS's own ⇧⌘3/⇧⌘4) add those and the screenshots macOS's own tools take to Clipboard History and the ⌘3 ScreenGrabs grid. New screenshots also go on the clipboard unless that's turned off in Settings › ScreenGrabs or you've copied something since the screenshot was saved; ⇧⌘3 and ⇧⌘4 copy only when you Save, so an unredacted shot never lands there. In the ⌘3 grid, Return copies a screenshot, as in the Clipboard tab, and ⌘E (or ⌘Return here, or ⌘E on any image in the Clipboard tab) opens a lightweight editor with arrow, text, draw, blur, and redact (keys 1–5); Save (Return) copies the flattened image and saves <name> (edited).png beside the original, and Cancel (Esc) discards it. The grid lists recordings beside screenshots, newest first, and recordings even with Clipboard History off (on macOS 15 and later): Return copies a recording's videos as files, ⌘E opens it in the recording window to trim, crop, or blur it, Space shows either kind in Quick Look, and Delete on a recording asks, then moves its folder to the Trash. Beside the grid, the screenshot or recording you highlight with ↓ or a click shows in full, with its details and a button for each of these keys.
ScreenGrabs also records the screen as a video, on macOS 15 or later, with your voice and the Mac's sound, and keeps each recording on this Mac under ~/Documents/Keybumps/captures/<timestamp>/ (ADR 0009). Record Screen (⇧⌘5, which takes over macOS's screenshot toolbar while ScreenGrabs is on, or Quick Search) opens a picker for an area, a window, or a screen; the Recordings group in Settings › ScreenGrabs holds its sound and recording preferences and shows the recordings folder. Screenshots don't go through the picker. While it records, a floating control bar, left out of the video, pauses, mutes, restarts, discards, or stops it, and the time shows in the menu bar. Draw on the bar marks up the screen with a pen, an arrow, a highlighter, or a rectangle, and with Show shortcuts on, the ⌘, ⌃, and ⌥ shortcuts you press show on the recorded screens; both are in the video.
Clipboard writes Keybumps makes for you stay out of Clipboard History: Dictation insertion, transcript copies from the Dictation tab, copies from the Snippets, Emoji, and Translate tabs and of emoji in the Search tab, ⌘V pastes, keyword expansion, the copy made when a paste can't go through, and putting your clipboard back afterwards. A copy you make yourself, in any app, is normal clipboard activity.
Each completed dictation is stored locally under ~/Documents/Keybumps/recordings/<timestamp>/ with meta.json transcript metadata and playable output.wav audio. The dedicated Dictation History screen supports search, playback, copy, Finder reveal, and deletion.
On macOS 15 or newer, each expanded history card can open Keybumps's on-device translation panel for immediate target-language selection, translated-text copying, and optional spoken playback using an installed macOS voice without changing the original transcript.
Keybumps sends crash and freeze reports to its developers through Sentry, never with user content, and Settings › General turns them off. Report a Problem… (Help menu, menu bar menu, Settings › General) sends a description the person writes, with the Mac's details (ADR 0007).
Dictation records for up to five minutes by default. Dictation settings provide 10, 15, 30, and 60-minute limits plus No Limit. Keybumps transcribes the completed local WAV so pauses or early live results do not truncate the remainder of the session. After inserting, Dictation puts back what was on the clipboard unless something else was copied meanwhile; Settings › Dictation turns that off.
brand/ holds the approved Keybumps brand pack (see brand/README.md): the keycap logo with the mascot, the standalone mascot, and platform exports. The macOS app icon is an Icon Composer file, apps/macos/Keybumps/Resources/Keybumps.icon (the 3D keycap and the mascot as separate layers on a purple gradient); Xcode compiles it into the asset catalog with fallbacks for older macOS. Edit it in Icon Composer and copy it to brand/apple/macos/Keybumps.icon. The menu-bar item and small in-app marks use the standalone mascot as a template image (KeybumpsMascot.imageset, cropped from brand/monochrome/mascot-dark.png). The web/ and social/ exports are for keybumps.app.
The Mac app lives in apps/macos/: its sources, tests, Xcode project (project.yml), scripts, and bundled licenses. Commands below run from the repository root unless they cd first. Requirements: Apple Silicon Mac, macOS 14.2+, Xcode, and XcodeGen.
apps/macos/scripts/build-and-run.shRun deterministic tests:
cd apps/macos
xcodegen generate
xcodebuild -project Keybumps.xcodeproj -scheme Keybumps -configuration Debug -derivedDataPath .derived testBuild, install, and launch a Developer ID-signed manual-QA candidate for an issue (backs up the installed app first):
apps/macos/scripts/build-qa-candidate.sh <issue-number>
apps/macos/scripts/restore-previous-keybumps.sh # roll backReleases are Developer ID-signed and notarized, licensed with Polar license keys (ADR 0002), and updated through Sparkle (update operations). QA candidates are never notarized or published.
apps/web/ holds the keybumps.app website (Next.js on Cloudflare Workers through OpenNext). It is separate from the Mac app, with its own pnpm project, CI (.github/workflows/web.yml checks pull requests, and web-deploy.yml deploys after merge), and agent instructions (apps/web/AGENTS.md). Release-please skips a commit only if every file it touches is under apps/web/, so website PRs change only apps/web/**; a needed root change goes in a separate chore:, docs:, or ci: PR. Run pnpm install && pnpm check from apps/web/; see apps/web/README.md.
Window Manager behavior is derived from the MIT-licensed Rectangle project and the owner's independently identified fork. See apps/macos/LICENSE.rectangle and docs/provenance/donor-ledger.md.
ScreenGrabs' screenshot redaction and markup rendering is adapted from the MIT-licensed Shotnix project. See apps/macos/LICENSE.shotnix and docs/provenance/donor-ledger.md.
Timer's duration parsing is adapted from the MIT-licensed Tock project. See apps/macos/LICENSE.tock and docs/provenance/donor-ledger.md. The Emoji Picker's emoji, names, and keywords come from Unicode and CLDR, and its :shortcode: aliases from GitHub's gemoji; see apps/macos/LICENSE.unicode, apps/macos/LICENSE.gemoji, and the donor ledger.
ScreenGrabs' recording engine is adapted from Screendrop (CC0-1.0) for its file writer, the MIT-licensed Shotnix for pausing, audio placement, and which windows a recording shows, the MIT-licensed BetterCapture for its system-audio stream, and the BSD-3-Clause-licensed Snapzy for its stereo mixdown; its picker from Screendrop for its area selection, highlight, and countdown, BetterCapture for drawing, moving, and resizing the area, and Snapzy for the remembered area and which windows can be picked. See apps/macos/LICENSE.screendrop, apps/macos/LICENSE.shotnix, apps/macos/LICENSE.bettercapture, apps/macos/LICENSE.snapzy, and docs/provenance/donor-ledger.md. Its control bar follows Snapzy for its layout, the microphone's wave behind it, and keeping it on screen, Shotnix for asking before a discard or a restart and for its panel, and BetterCapture for its panel; see the same licenses and the donor ledger. Drawing on screen while recording is adapted from Snapzy and from the MIT-licensed hop, for its drawing layer and its fading marks; see apps/macos/LICENSE.snapzy, apps/macos/LICENSE.hop, and the donor ledger. Its review window is adapted from Snapzy's video editor, for its window and Space to play and pause, and from Snapzy's quick-access card, for how it copies a recording; see apps/macos/LICENSE.snapzy and the donor ledger. Its recording edits are adapted from Shotnix's video editor, for how an edited recording is put together and written, and for the crop's rectangle and moving and resizing a blur; see apps/macos/LICENSE.shotnix and the donor ledger. In the ⌘3 tab, a recording's length badge is Snapzy's duration badge, and Quick Look is adapted from Screendrop's; see apps/macos/LICENSE.snapzy, apps/macos/LICENSE.screendrop, and the donor ledger.
Local Whisper transcription uses the OpenAI Whisper model family, run by the MIT-licensed Argmax OSS Swift/WhisperKit package or, for Large v3 Turbo (Fast), by MIT-licensed whisper.cpp on the GPU (ADR 0008). See apps/macos/LICENSE.argmax-oss-swift, apps/macos/NOTICES.argmax-oss-swift, apps/macos/LICENSE.whisper-cpp, and apps/macos/LICENSE.openai-whisper.
Crash reports use the MIT-licensed Sentry Cocoa SDK. See apps/macos/LICENSE.sentry-cocoa.
Keystrokes' key names and its lines that stack and fade are adapted from the BSD-3-Clause KeyCastr project, and its overlay window from the BSD-3-Clause Snapzy project. See apps/macos/LICENSE.keycastr, apps/macos/LICENSE.snapzy, and docs/provenance/donor-ledger.md.