KeyVoid

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
• NPM Publishing (Maintainer)
• 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

NPM Publishing (Maintainer)

# 1) login
npm login
npm whoami

# 2) verify package before release
npm run verify

# 3) dry-run package contents
npm pack --dry-run

# 4) publish
npm publish --access public

Recommended release flow:

1. Bump version (npm version patch|minor|major)
2. Update CHANGELOG.md
3. Tag and push (git push origin main --tags)
4. Publish to npm

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.