KeyVoid

Global keyboard lock in your terminal with safe mouse-first unlock.

KeyVoid is a cross-platform CLI that intercepts keyboard input at the OS level and displays an interactive full-screen terminal UI. It is built for focus sessions, safe keyboard lock while away from desk, toddler/cat-proof moments, and lightweight prank demos.

Table of Contents

• What You Get
• System Requirements
• Install
• First Run Checklist
• Usage
• Modes
• Safety and Unlock Paths
• Troubleshooting
• Developer Setup
• Project Structure
• Security Notes
• License

What You Get

• Global keyboard suppression (not just app-local key capture)
• Mouse-first unlock control with visible UI feedback
• Emergency failsafe combo (ESC + SPACE) and Ctrl+C fallback
• Seven built-in visual modes (clean, zen, arcade, hacker, cat, prank, toddler)
• Works through npm (npx, local install, or global install)

System Requirements

Requirement	Minimum
Node.js	>= 18
Terminal	Interactive TTY (not piped/non-interactive)
OS	macOS, Linux, or Windows

Platform-specific notes:

OS	Status	Required Setup
macOS	Supported	Accessibility permission for your terminal app
Linux	Supported	X11 session + xinput installed
Windows	Supported	PowerShell available (default on modern Windows)

Install

# run instantly (no install)
npx keyvoid

# OR install globally once
npm install -g keyvoid
keyvoid

First Run Checklist

macOS

1. Open System Settings
2. Go to Privacy & Security -> Accessibility
3. Add your terminal app (Terminal, iTerm2, etc.)
4. Toggle permission to ON

Linux

Install xinput:

# Ubuntu / Debian
sudo apt install xinput

# Fedora
sudo dnf install xinput

# Arch
sudo pacman -S xorg-xinput

Note: KeyVoid is intended for X11 environments. Wayland setups may not provide equivalent behavior.

Windows

No additional permission prompts are typically required.

Usage

# interactive mode picker
keyvoid

# direct mode launch
keyvoid --clean
keyvoid --zen
keyvoid --arcade
keyvoid --hacker
keyvoid --cat
keyvoid --prank
keyvoid --toddler

CLI utilities:

keyvoid --help
keyvoid --version

Modes

Flag	Theme	Description
--clean	Minimal UI	High-contrast dashboard with animated blocked-key counter
--zen	Calm focus	Breathing-style motion and low-stimulus visuals
--arcade	Retro 8-bit	Shooter-inspired animation reacting to key mashing
--hacker	Matrix style	Green terminal aesthetic with lock-screen vibes
--cat	ASCII cat defense	Reactive cat states and streak-based animation
--prank	Fake updater	Convincing fake update view with secret unlock gesture
--toddler	Color chaos	Giant emoji bursts and fast-changing vibrant colors

Safety and Unlock Paths

KeyVoid is intentionally designed with redundant exits:

1. Click the on-screen UNVOID button using your mouse
2. Hold ESC + SPACE for about 5 seconds (failsafe)
3. Use Ctrl+C as emergency terminal fallback

On exit, KeyVoid attempts to restore keyboard hook state before terminating.

Troubleshooting

"It says permissions are missing on macOS"

• Re-check Accessibility permission for your exact terminal app
• Fully close and re-open terminal after granting permission
• Run keyvoid again

"Linux launch fails or keyboard is not blocked"

• Confirm you are in an X11 session
• Confirm xinput exists: xinput --version
• Retry from a local terminal session (not remote shell)

"I launched with --cat but got another mode"

• Ensure you are on the latest commit/release
• Verify command spelling: keyvoid --cat
• Check version: keyvoid --version

"Command not found: keyvoid"

• If installed globally, check npm global bin is on PATH
• Or run via npx keyvoid

Developer Setup

git clone https://github.com/chirayuoli/keyvoid.git
cd keyvoid
npm install
npm run verify

Useful scripts:

• npm run smoke -> checks CLI help/version
• npm run pack:preview -> previews publish tarball contents
• npm run verify -> runs smoke + pack preview

Project Structure

keyvoid/
├── bin/keyvoid.js                     # CLI entry point
├── src/app.js                         # Application orchestrator
├── src/engine/permissions.js          # OS/platform checks
├── src/engine/suppressor/             # Native keyboard suppression layer
├── src/ui/renderer.js                 # Full-screen ANSI renderer
├── src/ui/mouse.js                    # Mouse region tracking and clicks
├── src/ui/skins/                      # Visual modes
├── src/scripts/postinstall.js         # macOS helper dependency bootstrap
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE

Contributing

Please see CONTRIBUTING.md for workflow and PR expectations.

Security Notes

KeyVoid intercepts keyboard input by design. Use only on systems and sessions you control. Avoid running in privileged production shells or remote sessions where recovery may be difficult.

License

MIT - see LICENSE.