The field guide.

The creature and the code

Meet the app.

Want to hear it first? Watch the 45-second demo, then try the individual sound packs.

Klicky adds mechanical keyboard sounds to an ordinary keyboard on Linux, macOS and Windows 11 x64. It includes ten sound packs, volume control, overlapping playback and native desktop integration. It runs locally as your user, without an account or subscription.

The creature beneath the keys is our fictional mascot. The application is a focused Rust utility, not an AI assistant, game or virtual pet.

Releases and the source changelog cover downloads and changes. Project-owned Homebrew and Scoop packages are available. Chocolatey and Cargo installation are not published.

Choose a doorway

Installation.

Use your desktop's normal terminal, as your user. Linux package setup asks for sudo when needed; the app remains unprivileged. Inspect the Unix or PowerShell helper first if you prefer.

Linux packages/source · macOS source + menu bar · Windows installer/portable

Linux.

Ubuntu 24.04+ / compatible Debian amd64, or Arch / Omarchy x86_64:

curl -fsSL https://klicky.muneer320.tech/install.sh | bash

The helper verifies the pinned APT key or Arch release checksum, installs the package and sounds, and enables/starts the systemd user service. Use a terminal with curl; APT setup installs GnuPG if missing. Debian packages need glibc 2.39+, libasound2t64, systemd and udev.

Compatible Omarchy QML shells get the toggle automatically. To skip it:

curl -fsSL https://klicky.muneer320.tech/install.sh | bash -s -- --no-omarchy-toggle

sudo apt install klicky
systemctl --user enable --now klicky.service

# Ubuntu / compatible Debian
curl -fL --retry 2 -o klicky.deb https://klicky.muneer320.tech/pool/main/k/klicky/klicky_0.5.0-1_amd64.deb
sudo apt install ./klicky.deb
systemctl --user enable --now klicky.service

# Arch / Omarchy
curl -fL --retry 2 -o klicky.pkg.tar.zst https://github.com/Muneer320/klicky/releases/download/v0.5.0/klicky-0.5.0-1-x86_64.pkg.tar.zst
sudo pacman -U ./klicky.pkg.tar.zst
systemctl --user enable --now klicky.service

Build from source

For other distributions/architectures, older systems or development:

curl -fsSL https://klicky.muneer320.tech/install.sh | bash -s -- --source

This prepares missing Rust 1.87, compiler and ALSA development dependencies on supported APT/pacman/dnf systems, then builds and starts Klicky using systemd/udev. Existing checkout:

git clone https://github.com/Muneer320/klicky.git
cd klicky
./scripts/install-linux.sh

Checkouts need Rust 1.87+, Git, a compiler, pkg-config and ALSA headers (libasound2-dev on Ubuntu/Debian; alsa-lib-devel on Fedora). For non-systemd setup or source-to-package migration, see advanced installation.

macOS.

curl -fsSL https://klicky.muneer320.tech/install.sh | bash

Prepares missing Rust and Apple tools, builds the app, installs the menu helper and enables login startup. Approve Apple's tools dialog if shown. First setup can take several minutes; this is a source installation. For Homebrew-managed setup, use the tap below.

Skip the helper:

curl -fsSL https://klicky.muneer320.tech/install.sh | bash -s -- --no-menu

From a checkout with Rust 1.87+ and Apple build tools:

./scripts/install-macos.sh
./scripts/install-macos-menu-bar.sh

The menu toggles the daemon; change packs/volume through the CLI. Quitting the helper closes the menu, not the daemon.

Homebrew on macOS.

On Apple Silicon, with Homebrew and Apple Command Line Tools installed:

brew install muneer320/tap/klicky && brew services start muneer320/tap/klicky && klicky service enable

The tap builds the app, sounds and menu helper from source. Grant Accessibility to the actual binary shown by brew info klicky, then run klicky service start. To omit the menu, leave out brew services start muneer320/tap/klicky.

Intel Macs use the one-line source installer. Klicky still supports Intel; Homebrew has ended its supported Intel coverage. Remove a previous source installation without purge before switching. Keep one installation and one menu helper.

klicky service stop && brew update && brew upgrade muneer320/tap/klicky && brew services restart muneer320/tap/klicky && klicky service start

klicky service disable && brew services stop muneer320/tap/klicky && brew uninstall muneer320/tap/klicky

Scoop on Windows.

With Scoop installed, run in normal PowerShell:

scoop bucket add klicky https://github.com/Muneer320/scoop-bucket
scoop install klicky/klicky
klicky service start

The complete portable package includes all sounds and a Start shortcut. Enable login startup with klicky service enable. Remove an existing installer copy before switching; settings can carry over.

klicky service stop
scoop update
scoop update klicky
klicky service start

Windows.

Windows 11 x64 desktop. Run in PowerShell:

irm https://klicky.muneer320.tech/install.ps1 | iex

Downloads a published installer, verifies its SHA-256 and opens per-user setup. Choose login startup in the wizard. Rust, Visual Studio and elevation are not needed. The helper starts the installed app afterward, respecting a paused launch.

Download the setup EXE or portable ZIP. For portable use, extract everything into a stable folder and open klicky-desktop.exe. Keep both executables, sounds and notices together.

Windows downloads are unsigned. Windows 10, ARM64 and x86 are not initial targets. Security help · Windows controls and recovery guide.

Your first few clicks.

On Linux/macOS, check the app, choose a sound and set the volume:

klicky list
klicky status
klicky switch cherrymx-blue-pbt
klicky volume 0.5

If the shell cannot find a source installation, use ~/.local/bin/klicky. Linux packages install /usr/bin/klicky. Windows has tray controls and this installed CLI:

& "$env:LOCALAPPDATA\Programs\Klicky\klicky.exe" status

Select the intended speakers/headphones and type briefly. On Windows, Resume if paused. The macOS menu toggles sounds; Linux uses its service controls.

CLI reference.

Common commands below work on Unix and Windows. Windows uses the installed path above, or .\klicky.exe from a portable folder; it is not added to PATH.

Windows additions

pause, resume, retry-audio and read-only diagnostics. service start --paused affects a newly launched instance. Foreground start also takes --paused, --seconds N (1–3600) and aggregate --benchmark diagnostics.

Linux/macOS benchmark mode

start --benchmark prints mapped key names and internal timing. Use only for controlled tests, never while typing sensitive information. Windows-only pause/seconds/diagnostics commands do not exist on Unix.

A successful live pack/volume command confirms the change was loaded, saved and applied. If a response fails or times out, check status and logs before retrying. Full CLI reference →

Configuration.

Two fields in config.toml:

sound_pack = "eg-oreo"
volume = 0.8

Use controls for live changes; edit configuration while stopped. Custom packs go in the neighboring sounds folder and override system/bundled names.

KLICKY_SYSTEM_SOUNDS_DIR overrides the secondary pack root; Windows requires an absolute path. KLICKY_SKIP_UDEV=1 skips the Linux source installer's device rule when access is managed elsewhere. These are advanced environment options, not config fields. Configuration reference →

A sound of your own.

Ten bundled packs: Cherry MX Black, Blue, Brown and Red with PBT/ABS variants, EG Oreo and EG Crystal Purple. Listen in the sound room.

A custom pack is a directory containing sound.ogg and config.json. The JSON maps keys to [start_ms, duration_ms]:

{
  "defines": {
    "KeyA": [0, 120],
    "Space": [235, 180],
    "Return": [415, 150]
  },
  "name": "My Pack"
}

Copy it into your sounds folder, then select it:

# Linux example; use the corresponding macOS/Windows path above.
mkdir -p ~/.config/klicky/sounds
cp -R my-pack ~/.config/klicky/sounds/
klicky switch my-pack

A malformed or undecodable pack leaves the current one active. Include common keys, avoid clipping and redistribute only recordings you have permission to use. Format and supported key names →

Under the keycaps.

One resident application serves the user session. Native input feeds the platform runtime; shared preparation decodes OGG with Symphonia, creates per-key PCM slices and applies capped normalization when loading a pack.

1. Native input

   Linux evdev / macOS event taps / Windows passive Raw Input.

2. Cached PCM

   Select prepared samples and apply the user's volume.

3. Persistent mixer

   Overlap key sounds through the platform renderer.

Windows gates capture outside the verified active/unlocked desktop and discards obsolete input across transitions. Its adapters preserve the separate Unix implementation. Module map, concurrency and lifecycle →

Local sounds. Sensitive permissions.

Normal operation does not store typed text, log key names, record microphone audio or make network requests. Installation helpers download files; the running app needs no cloud service.

Global keyboard access is sensitive. macOS requires Accessibility; Linux uses a keyboard-only udev rule; Windows receives passive Raw Input without elevation. Grant access only to software you trust. Do not make input devices world-readable.

Unix benchmarks print mapped key names; Windows diagnostics use aggregate counters. The website has no analytics, account or global keyboard listener. Its small script copies commands and prevents overlapping previews. Security model and private reporting →

Responsive by design.

Decoding, slicing and normalization happen at pack load. Keypress playback reuses cached PCM and an existing output stream instead of opening a device or decoding OGG for every press.

This does not guarantee a particular physical latency, CPU load or memory footprint on every system. Device buffering, drivers, Bluetooth and load matter. Internal dispatch timings and requested buffer sizes do not measure physical keypress-to-audible delay.

Compare speakers or wired output when diagnosing an out-of-sync feeling. Read the measurement guide →

When the clicks go quiet.

& "$env:LOCALAPPDATA\Programs\Klicky\klicky.exe" status
& "$env:LOCALAPPDATA\Programs\Klicky\klicky.exe" diagnostics

klicky status
systemctl --user status klicky.service
journalctl --user -u klicky.service -n 50 --no-pager

~/.local/bin/klicky service status
launchctl print "gui/$(id -u)/dev.klicky.daemon"
launchctl print "gui/$(id -u)/dev.klicky.menu"

More troubleshooting · Report a bug. Include OS, build, output and reproduction steps; you need not share what you typed.

Good questions.

Keep your resident up to date.

Settings and custom sounds are preserved. Stop packaged Linux processes before replacing the binary, including copies in other signed-in sessions:

# APT repository
systemctl --user stop klicky.service
sudo apt update && sudo apt install --only-upgrade klicky
systemctl --user start klicky.service

For Arch, install the newer release package instead of the APT command. For source installs, rerun the download installer or update the checkout and rerun the platform scripts, including the macOS helper. Check Accessibility again if replacement stops macOS input.

Windows: run the newer installer. It verifies shutdown and preserves the running/pause choice. Disable owned startup and quit before replacing/moving a portable copy. Keep recovery material after a failed update. Recovery details →

Until the next click.

Removal stops the app, disables owned login startup and removes installed controls. Settings and custom sounds stay by default. Purge explicitly deletes them.

Linux / macOS

curl -fsSL https://klicky.muneer320.tech/uninstall.sh | bash

Also delete personal settings/sounds:

curl -fsSL https://klicky.muneer320.tech/uninstall.sh | bash -s -- --purge

Linux handles the package/source copy, service, device rule, APT source/key and supported Omarchy control. Other signed-in users must stop packaged copies first. macOS unloads daemon/helper and removes their binaries, LaunchAgents and menu images. Rust and Apple tools remain; Accessibility permission can be removed manually.

Windows installer setup

irm https://klicky.muneer320.tech/uninstall.ps1 | iex

Complete the native wizard. Also remove settings, custom sounds and installer data:

& ([scriptblock]::Create((irm https://klicky.muneer320.tech/uninstall.ps1))) -Purge

Use -WhatIf instead of -Purge to preview. Failed/cancelled native removal keeps personal data. Settings → Apps → Installed apps also has the uninstaller.

Windows portable copy

Disable that bundle's login startup in its tray, choose Quit and delete only its extracted folder. The helper does not search drives or delete arbitrary portable/development folders. After closing all copies, its purge command can remove shared settings. Complete removal guide →

Help this little world grow.

Useful bug reports, accessible docs, sound packs and focused code changes are welcome. Work on dedicated branches, explain the change and validate affected platforms.

• Contributor setup and PR workflow
• Architecture and module map
• Sound-pack authoring
• Brand assets and usage
• Release checklist
• Credits and notices

Built on Sauhard Gupta's original Klicky, with work by Muneer Alam and contributors. Read the engineering story or the audio deep dive on DEV.