Key Monster

A keyboard-driven macOS utility built around your clipboard. Key Monster lives in the menu bar, quietly records what you copy, and lets you search back through it and paste any earlier entry from a fast, centered panel — plus a set of keyboard-only ways to drive the rest of your Mac: focus apps, click anything on screen, scroll any pane, and jump the caret through text, all without the mouse.

Features

Clipboard history

• Menu bar resident — runs as a background accessory (LSUIElement), no Dock icon, no window cluttering your screen.
• Captures text, images, and files — records plain text, images (e.g. copied from Preview or a browser), and file URLs (files copied in Finder).
• Search-first, two-pane panel — a floating, centered panel with a search field that matches across text content, file names, and the source app name. The left column lists matches; the right column previews the full content of the selected item — the complete text, the image, or every file path.
• Fully keyboard-driven — open with a global shortcut, type to filter, and navigate without touching the mouse:
  • ↑ / ↓ or Ctrl-N / Ctrl-P — move the selection
  • Ctrl-J / Ctrl-K — scroll the preview pane for long content
  • Return — paste the highlighted item into the app you were just using (or copy it, if auto-paste is off or unavailable)
  • Esc — dismiss the panel (it also closes when it loses focus)
• Auto-paste — Return pastes the selection straight into the previously focused app by synthesizing a ⌘V, so you don't have to switch back and paste manually. On by default; it needs Accessibility permission (Key Monster requests it when you enable the toggle) and gracefully falls back to copy-only without it.
• Source app tracking — each entry remembers (and shows the icon of) the app it was copied from. The origin is preserved when you re-select an old item.
• Password-manager aware — respects the nspasteboard.org convention and skips clipboard contents marked concealed, transient, or auto-generated.
• Persistent & deduplicated — history is stored locally in SQLite and survives restarts. Duplicate copies move to the top instead of piling up; the store is capped at 10,000 items.

Keyboard shortcuts for the rest of your Mac

• Configurable global shortcut — record any modifier + key combo in Settings to summon the history panel from anywhere.
• App focus shortcuts — bind a global shortcut to one or more apps. Press it to focus the app; press again while one is frontmost to cycle through the rest, so a single combo can rotate through e.g. Slack and Chrome. Settings warns when a combo is bound more than once, since only the first binding can register.
• Click hints (vimium-style) — press a shortcut and every clickable element in the frontmost window grows a short label (a single home-row letter when few elements are visible, two letters otherwise); type a label to click it without touching the mouse. Works on native macOS controls and on web content in Safari, Chrome, and Electron apps (Key Monster asks them to expose their accessibility trees). In kitty (also inside tmux) URLs and OSC 8 hyperlinks — including ones Claude prints as linked text — get hints too, read from the window's screen text; picking one asks kitty to open it (no mouse movement), so your open_url_with and open-actions.conf still apply; this needs allow_remote_control yes and listen_on unix:/tmp/kitty in kitty.conf (restart kitty after adding it), and tmux needs set -ga terminal-features ",xterm-kitty:hyperlinks" for linked text to survive. Settings → Mouse shows whether kitty is set up (and says what to fix), and hint mode explains on screen when it can't read kitty. Kitty windows with splits aren't supported yet. Set File Path Script (Settings → Mouse) and file paths on screen that exist (/abs, ~/x, or src/a.swift:12:5, resolved against the window's directory) are hinted too; picking one runs your script with the absolute path as $1 (and $KEYMONSTER_LINE/$KEYMONSTER_COLUMN when given), e.g. to open it in nvim in a tmux pane. Relative paths inside tmux resolve against kitty's directory, not the pane's. Separate shortcuts for left-click and right-click hints; holding Shift on the final letter clicks with the opposite button. Elements too close together to label individually share one green area label — typing it zooms into that area (a magnified screenshot; this needs Screen Recording permission — Key Monster prompts the first time, and zoom stays unavailable until it's granted) and each element gets a normal label; Delete backs out of the zoom. Esc, a real click, or any other chord dismisses the overlay. Requires Accessibility permission.
• Grid click — for clicking somewhere with no element to label, a shortcut overlays a fine grid on the frontmost window, each cell wearing a short home-row label; type the label nearest your target to pick a starting cell. From there the grid mirrors the keyboard's three letter rows (…, …, …), so the key under your finger names the cell in the same spot on screen — and each keypress zooms into that cell, magnifying it into a loupe so small targets stay legible. After a few zooms the next key clicks its cell. clicks the center of the current region at any point, and holding on the deciding key right-clicks instead. zooms back out (and from the first zoom, back to the initial label grid); , a real click, or any other chord dismisses. Requires Accessibility permission; the zoomed loupe needs Screen Recording (prompted on first use, and zooming stays unavailable until it's granted).

Convenience

• Launch at login — an optional toggle registers Key Monster to start automatically when you log in.
• Automatic updates — the app checks for a newer release daily (via Sparkle) and installs it in the background, taking effect the next time it starts. A badge on the menu bar icon and an "Update Available" item show when one is waiting; "Check for Updates…" in the menu looks right now. Both the daily check and the silent install can be turned off in Settings.

Download

Grab the latest KeyMonster-<version>.dmg from the Releases page, open it, and drag Key Monster.app into /Applications. Releases are signed with a Developer ID certificate and notarized by Apple, so it opens like any other app.

Prefer to build it yourself? See Building & Running below.

Requirements

• macOS 14 (Sonoma) or later
• Swift 6 toolchain (Xcode 16+) to build
• SwiftLint for make lint

Building & Running

The project uses a Makefile for common tasks:

make run      # build a proper .app bundle (icon, menu bar agent, signed) and open it
make app      # build the .app bundle without launching it
make build    # plain `swift build`
make install  # build a release bundle and copy it into /Applications
make test     # run the test suite
make lint     # run SwiftLint
make icon     # regenerate Resources/AppIcon.icns from Resources/icon.svg
make dist     # build the release .app and package it into a DMG in .build/dist/
make notarize # submit the DMG to Apple's notary service and staple the ticket
make clean    # clean build artifacts

make run assembles a real .app bundle so the menu bar agent, icon, code signature, and bundled Sparkle framework are in place. Because persistence is SQLite (via GRDB) rather than something requiring a bundle identifier, plain swift run also works for day-to-day development (update checks stay off there, since a bare binary has no feed URL). make install builds a release bundle and installs it to /Applications (override with make install INSTALL_DIR=~/Applications).

Accessibility grants (needed for auto-paste, click hints, grid click, and text jump) are tied to the app's code-signing identity. The Makefile auto-detects a real signing identity from your keychain and signs with it, so the grant persists across rebuilds; it falls back to ad-hoc signing if none is found (in which case macOS forgets the grant on every rebuild). Override explicitly with make run CODESIGN_IDENTITY=<identity> if needed.

Cutting a release

See RELEASING.md for the release workflow — tagging, signing, notarization, and the GitHub Actions pipeline.

Usage

1. Launch Key Monster — the monster-keyboard glyph appears in the menu bar. On first launch the Settings window opens automatically.
2. Settings is organized into tabs, one per feature, each with a short description of what it does. In the Clipboard tab, record a Clipboard Shortcut. To use auto-paste, leave Paste into the active app on Return enabled and grant Accessibility access when prompted (Key Monster links you to the right System Settings pane).
3. Optionally set up the other tabs — Focus (app switching), Clicking (hints and grid), Text (jump to character), Menus (menu search), Notifications (dismiss them), and Scripts (run script files) — and toggle Launch at Login in the General tab, which leads the row.
4. Copy things as you normally would; Key Monster records them in the background.
5. Press your shortcut (or choose Show Clipboard History from the menu) to open the panel, type to search, select an entry, and press Return — it pastes into the app you came from (or just copies, if auto-paste is off/ungranted).

Your history is stored at:

~/Library/Application Support/keymonster/history.sqlite

Architecture

See ARCHITECTURE.md for a file-by-file map of the codebase.

Tech Stack

• Swift 6 + SwiftUI + AppKit
• GRDB for SQLite persistence
• Sparkle for automatic updates