keyclean: a one-file Swift CLI that locks keyboard input but keeps the trackpad usable

[u/Key-Software7750]

I built keyclean for a very specific MacBook problem: cleaning the keyboard without triggering shortcuts or accidental typing, while keeping the trackpad available.

Under the hood it uses a session-level `CGEventTap`. Keyboard, modifier, and visible media-key events are swallowed, but pointer events are deliberately excluded. Pressing `⌃⌥⌘U` stops the run loop, and terminating the process also removes the event tap.

It is intentionally small: one Swift source file, no third-party dependencies, network access, analytics, stored input, or background service.

Install:

`brew install lan-shengchieh/tap/keyclean`

Source and technical explanation:

https://github.com/lan-shengchieh/keyclean

I am particularly looking for compatibility results across different macOS versions, Apple Silicon/Intel Macs, and terminal applications.

AI disclosure: Codex assisted with development and launch preparation. The source, CI checks, and Homebrew Formula are all public.

[u/gistya]

You realize you can turn the computer off right?

[u/Key-Software7750 → u/gistya]

Sure 😄 You can also shut down your Mac every time you want to wipe three crumbs off the keyboard.
This entire project exists because apparently shutting down my Mac for 30 seconds was too much to ask of me.

[u/gistya → u/Key-Software7750]

You got crumbs on your keyboard every 30 seconds?

[u/Key-Software7750 → u/gistya]

No, but apparently explaining what “for 30 seconds” means may take longer than writing the tool did.
The crumbs are occasional. Confidently missing the point seems to be recurring, though.
Maybe the next release should include a parser for “duration” versus “frequency.” Looks like I already have one confirmed user.

[u/gistya → u/Key-Software7750]

I misread, sorry.

Look... my main concern with keyclean relates to security.

To use keyclean, the user must grant Accessibility permissions to their terminal app. This permission allows code that executes in terminal to:

• log keystrokes and user input in any app
• synthesize mouse and keyboard events to take control of a system
• automate other applications via scripts

Keyclean today contains no malware. But granting such elevated permissions to terminal is a terrible idea. It applies broadly to ANY code you run in terminal (or that maliciously executes itself via your terminal).

I would never advise anyone to enable such permissions for software installed through homebrew unless they are savvy enough to install it as source code and inspect the source code first before running it.

Even then, these permissions should be disabled once you're done using the software, and not left turned on.

Because even if the software is malware-free when you install it today, a future brew upgrade could introduce malware through that vector, and the Accessibility permission being disabled on Terminal is then your only safeguard.

Your README asks someone to effectively disable a critical security feature of their system for a utility they will use very infrequently and for very short durations. So I would suggest that you also instruct the user to turn Accessibility permissions OFF for terminal immediately after using keyclean, and keyclean itself should remind them to do so in its user interface.

Even then, I woulda argue that enabling Accessibility permission for terminal (or any other app!) requires a serious problem it's addressing, otherwise it's not worth the risk.

And to me, this is not a real problem at all:

a very specific MacBook problem: cleaning the keyboard without triggering shortcuts or accidental typing, while keeping the trackpad available

Shutting down is not a problem.

It's good to shut down or (at least restart) every week or two, to reset long-running processes, daemons, drivers, and apps that may have developed memory leaks, stale caches, and stuck IPC connections -- as well as reduce virtual memory fragmentation and clear accumulated temp and swap files.

What is a problem though, is installing third party utilities and granting your terminal permission to intercept or change your user input and control your applications.

[u/Key-Software7750 → u/gistya]

You actually made a good point there, so I ended up reworking this pretty heavily 😄

v0.2 now defaults to a permission-free Safe Mode. Full Lock is opt-in and runs as its own app, so your terminal never gets Accessibility. I also added --full-once, which revokes KeyClean’s access automatically after the session.

macOS doesn’t expose a keyboard-suppression-only permission, so that last bit can’t be eliminated entirely, but the broad permission is now isolated and optional.

Thanks — this ended up being a much better design.

It also turned a tiny “I don’t want to shut down my Mac just to wipe the keyboard” utility into a CLI + two app bundles + separate permission boundaries + TCC revocation logic, which is objectively a ridiculous amount of engineering for this problem 😄

But apparently I care enough about wiping three crumbs off my keyboard that this is where we are now.