SameKeys

New Mac. Same Keys.

Your Windows shortcuts, on your Mac.

SameKeys lets people who just moved from Windows to macOS keep their muscle memory: Ctrl+C still copies, Home/End still jump to line start/end, mouse side buttons still go back and forward, Ctrl/fn + scroll still zooms the page, and ⌥V brings up a Windows-style clipboard history.

Website: samekeys.com (English, 简体中文, 日本語)

Download the latest SameKeys or install it with Homebrew:

brew install --cask lynnjeans/tap/samekeys

Open the disk image and double-click SameKeys: it installs itself in Applications and opens. From then on it keeps itself up to date.

---

Why

macOS is missing, or does differently, a lot of what Windows users do by reflex:

Windows habit	On macOS
Ctrl+C / Ctrl+V	⌘C / ⌘V
Win+V clipboard history	doesn't exist
Ctrl + scroll zooms a page	zooms the whole screen, or nothing
Mouse side buttons go back / forward	do nothing
Mouse wheel and touchpad each scroll their own way	one setting flips both
Delete, F2 and right-click › New in File Explorer	Delete does nothing in Finder, Enter renames, and there is no New Document

Today the fixes are scattered across separate apps: a key remapper for the keyboard, another tool for the mouse buttons and wheel, a clipboard manager, a window snapper, a Finder add-on. Each one has to be found, installed, granted permissions and set up from scratch, and none of them starts from Windows habits. Karabiner-Elements owns deep keyboard remapping but can't see scroll events; BetterTouchTool covers a lot but is paid, closed source and built for power users; LinearMouse and Mac Mouse Fix cover the mouse only.

SameKeys brings it all together in one app, set up for Windows habits from the first launch. That is why I made it: when I moved from Windows to the Mac, years of habits would not go away, and I did not want five apps to keep them. SameKeys is for one audience none of the others targets directly: the migrant.

What it does

• Configurable combo → combo remapping engine (Ctrl→⌘, key swaps, fn combos — all just rules)
• Windows presets, one click to apply, every entry still individually editable
• Each keyboard its own way: a MacBook's keyboard and a PC keyboard can press Ctrl and Win/Alt differently
• Mouse side buttons → back / forward or any shortcut
• Modifier + scroll → ⌘+ / ⌘− (page zoom), on from the start with fn, or Ctrl if you prefer; no separate mouse tool needed
• Scroll direction reversal, mouse only, trackpad untouched
• Finder key suite — Delete, F2, Enter, Ctrl+X/V move, Backspace up
• Clipboard history on Win+V or ⌥V, with search, pinning, and password-manager exclusion
• Per-app scoping: a rule for every app, or just one
• Window snapping: ⌥+←/→/↑ like Win+←/→/↑
• Finder right-click menu: new document, copy path, open in Terminal
• Open and save dialogs: Ctrl+G jumps to Finder's folder, Ctrl+Shift+G lists recent and favorite folders
• Record Shortcuts: when a shortcut misbehaves, record it and export what happened
• Open at Login, and automatic updates, signed and checked daily
• English, 简体中文, 繁體中文, 日本語, 한국어, Deutsch, Français, Español, Português (Brasil), Polski

Out of scope: deep keyboard remapping — tap/hold dual-role keys, layers, chords. SameKeys maps combinations to combinations (Ctrl+C → ⌘C, fn+C → ⌘C) and nothing more. That keeps it on a single event tap with two permission toggles, instead of the root daemon and virtual keyboard driver that deep remapping requires. If you need those, use Karabiner-Elements.

Requirements

• macOS 14+ (developed against macOS 26)
• Two system permissions: Accessibility and Input Monitoring

A sandboxed app can watch the keyboard and send keystrokes, but not use the Accessibility API, which SameKeys needs to read other apps: whether you are typing in a text field before Delete deletes a file, Finder's folder for Ctrl+G in open and save dialogs, the window to snap. Nor is it clear that a sandboxed app may hold back the key you pressed, so that Ctrl+C is not also sent on as it is. SameKeys is therefore distributed outside the Mac App Store, signed and notarized, via GitHub Releases and Homebrew Cask.

Building

Requires Xcode 16 or later — the full install, not just the Command Line Tools.

git clone https://github.com/lynnjeans/samekeys.git
cd samekeys
open SameKeys.xcodeproj

The Xcode project is generated from project.yml by XcodeGen. The generated project is committed so a fresh clone builds with no extra tools, but to change build settings, edit project.yml and regenerate rather than editing the project in Xcode:

brew install xcodegen
xcodegen generate

Code signing

SameKeys needs Accessibility and Input Monitoring permissions, and macOS ties those grants to the app's code signature. An ad-hoc signed build gets a new identity every time it is rebuilt, so the grants are lost on each build. To keep them, sign development builds with your own certificate — a free Apple ID is enough:

1. In Xcode › Settings › Accounts, add your Apple ID, select its Personal Team, choose Manage Certificates… and create an Apple Development certificate.

2. Copy the template and fill in your Team ID (instructions are inside it):

   cp Config/Local.xcconfig.template Config/Local.xcconfig
   

Config/Local.xcconfig is git-ignored, so your Team ID never enters the repository. Without it the build falls back to ad-hoc signing: everything still runs, but you will have to re-grant permissions after every build.

Localization

Every string the UI shows lives in SameKeys/Resources/Localizable.xcstrings, SameKeys's String Catalog, with English as the source language. Write UI text as string literals in SwiftUI (Text("…")) or as String(localized: "…") where a String is needed; building in Xcode adds new strings to the catalog and lists missing translations. A command-line build only extracts them, so sync the catalog afterwards:

xcodebuild -project SameKeys.xcodeproj -scheme SameKeys -derivedDataPath build build
scripts/sync-strings.sh

App icon

SameKeys/Resources/AppIcon.icon is an Icon Composer document: three SVG layers (an ∞ joining the two loops, keycaps, legends) on a blue gradient. macOS 26 draws it in Liquid Glass; the build derives the flat icon macOS 14 and 15 show. The layers, the menu bar icon (SameKeys/Resources/MenuBarIcon.svg) and the website's favicon are written by one script, so they always match; change the drawing there and run it again:

scripts/icons/infinity.py

Render every appearance without opening Icon Composer with its ictool:

"$(xcode-select -p)/../Applications/Icon Composer.app/Contents/Executables/ictool" \
  SameKeys/Resources/AppIcon.icon --export-image --output-file /tmp/icon.png \
  --platform macOS --rendition Dark --width 512 --height 512 --scale 1

Renditions: Default, Dark, ClearLight, ClearDark, TintedLight, TintedDark.

Project docs

Design and planning documents live in docs/.

Website

The product website is plain HTML in site/, one page per language, published to GitHub Pages by .github/workflows/pages.yml whenever site/ changes on main, and served at samekeys.com (the domain is set in the repository's Pages settings). Nothing is built. To preview it:

python3 -m http.server 8123 --directory site

and open http://localhost:8123/. The three pages share one stylesheet but not their markup: a change to one page's structure goes into all three.

The screenshots come from the Debug build, with a fresh settings folder and an example clipboard history, so nothing of yours shows up in them. Retake them all after the UI changes:

xcodebuild -project SameKeys.xcodeproj -scheme SameKeys -derivedDataPath build build
scripts/site/screenshots.sh

The image shown when a link to the website is shared is drawn from scripts/site/social-preview.html, with the app icon and each language's Shortcuts screenshot. Redo it after retaking the screenshots (it needs Google Chrome), and upload site/assets/social/en.png as the repository's social preview in its GitHub settings:

scripts/site/social-preview.sh

License

Copyright © 2026 Lei Sun and SameKeys contributors.

SameKeys is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3. It is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See LICENSE for the full terms.

SameKeys is free software and always will be. If it saves you some frustration, donations are welcome, but never required: sponsor the project on GitHub.

The only third-party code in SameKeys is Sparkle (MIT), which handles automatic updates. It, the projects SameKeys was designed after, and the ones whose licenses rule out reuse are listed in THIRD_PARTY_NOTICES.md.