Bluekeys

Monkeytype for your terminal.

https://github.com/user-attachments/assets/8d9b45df-4393-4d3a-a882-71819f1a64b4

About

Bluekeys is a feature-rich typing speed test that runs entirely in your terminal. Born from a love of Monkeytype and a desire to never leave the command line, Bluekeys brings the same addictive typing test experience to your terminal with full keyboard-driven navigation, beautiful themes, and detailed stats.

No browser. No distractions. Just you and your words per minute.

Installation

Homebrew (macOS / Linux)

brew install anirban12d/tap/bluekeys

Quick install (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/anirban12d/bluekeys/main/scripts/install.sh | sh

This downloads a prebuilt binary — no Node.js required.

npm

npm install -g bluekeys

From a specific release

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/anirban12d/bluekeys/main/scripts/install.sh | sh -s v1.1.0

Then simply run:

bluekeys

Upgrading

brew upgrade bluekeys               # if installed via Homebrew
bluekeys upgrade                    # upgrade to latest version
bluekeys upgrade v1.1.0             # install a specific version

Or re-run the install script:

curl -fsSL https://raw.githubusercontent.com/anirban12d/bluekeys/main/scripts/install.sh | sh

Uninstalling

brew uninstall bluekeys             # if installed via Homebrew
npm uninstall -g bluekeys           # if installed via npm
sudo rm /usr/local/bin/bluekeys     # if installed via curl

To also remove your config and data:

rm -rf ~/.bluekeys

Quick start with flags

bluekeys --mode time -t 60                    # 60-second timed test
bluekeys --mode words -w 100                  # 100-word test
bluekeys --mode quote                         # quote mode
bluekeys --mode code --code-language python   # type Python code snippets
bluekeys --mode cli --cli-category git        # type git commands
bluekeys --theme dracula                      # start with a specific theme
bluekeys --language french                    # test in French
bluekeys --punctuation --numbers              # enable punctuation and numbers

Features

Test modes

• Time — 15, 30, 60, or 120 second tests
• Words — 10, 25, 50, 100, or 200 word tests
• Quote — type real quotes (short, medium, long, thicc)
• Code — type real code snippets (Python, JavaScript, Go, Rust)
• CLI — type real terminal commands (general, git, docker, npm, linux)
• Zen — free typing, no target text
• Custom — paste your own text

Languages

English, French, German, Spanish, Python, JavaScript — with more on the way.

15 themes

Serika Dark, Dracula, Monokai, Nord, Gruvbox, Solarized Dark, Catppuccin Mocha, Tokyo Night, Rose Pine, Carbon, Minimal, Olive, 80s After Dark, Botanical, and Serika Light. Live preview when browsing themes in settings.

Keybinding modes

Navigate menus and settings with the style you prefer:

• Normal — arrow keys
• Vim — hjkl navigation, q to go back
• Emacs — Ctrl+N/P/F/B navigation, Ctrl+G to go back

Keybinding mode only affects navigation. It never interferes with your typing test.

Learning mode

A full touch-typing curriculum built right into the terminal:

• 25 progressive lessons across Beginner, Intermediate, and Advanced levels
• Keyboard visualization with color-coded finger assignments — shows exactly which finger to use for each key
• Home row first — start with J and F, build up row by row
• Three lesson types — key drills, real-word practice, and mixed reviews
• Star ratings — earn up to 3 stars per lesson based on accuracy (80% / 92% / 98%)
• Persistent progress — pick up where you left off across sessions

Access from the main menu via learn.

Error heatmap

• Per-test heatmap on the results screen showing your most mistyped words with character-level error coloring
• Cross-session heatmap screen with 5 tabs:
  • Overview — total tests, words typed, errors, accuracy, avg/best WPM
  • Most missed words — all-time error words ranked with bar charts
  • Character mistakes — which character pairs you confuse most (e.g. h→e)
  • Accuracy trend — sparkline showing improvement over time
  • Practice suggestions — words to focus on based on your history

Access from the main menu via heatmap.

Detailed stats

• WPM, raw WPM, accuracy, consistency
• Per-second WPM/raw history chart
• Character breakdown (correct / incorrect / extra / missed)
• Personal best tracking per mode and configuration
• Results history saved locally

Difficulty modes

• Normal — standard typing test
• Expert — fail if accuracy drops below 95%
• Master — fail on any error

Funbox modes

22 fun modifiers: mirror, upside down, rAnDoMcAsE, capitals, nospace, backwards, ddoouubblleedd, memory, read ahead, gibberish, specials, binary, hexadecimal, rot13, and more.

Other features

• Confidence mode (no backspace / word-level backspace only)
• Stop on error (word or letter level)
• Freedom mode, lazy mode, blind mode, strict space
• Configurable caret style (block, outline, underline)
• Live WPM, accuracy, and burst display
• Tape mode (letter or word)
• Multiple highlight modes
• Quick restart with Tab, Esc, or Enter
• Repeat test with Enter on results screen
• Personal best notifications

Configuration

Bluekeys stores its config at ~/.bluekeys/config.toml (Windows: %APPDATA%\.bluekeys\config.toml). A fully commented config file is generated on first run.

# mode: time | words | quote | code | cli | zen | custom
mode = "time"
timeLimit = 30
language = "english"

# Code snippets language (used when mode = "code")
# Available: python, javascript, go, rust
codeLanguage = "python"

# CLI commands category (used when mode = "cli")
# Available: general, git, docker, npm, linux
cliCategory = "general"

# keybindingMode: normal | vim | emacs
keybindingMode = "vim"

theme = "dracula"

All settings can also be changed from the in-app settings screen.

Data files

| File | Location | Purpose | | --------------------- | -------------- | ------------------------ | | config.toml | ~/.bluekeys/ | All settings | | pb.json | ~/.bluekeys/ | Personal bests | | results.ndjson | ~/.bluekeys/ | Full result history | | learn-progress.json | ~/.bluekeys/ | Learning mode progress |

CLI options

| Flag | Short | Description | | ------------------ | ----- | ---------------------------------------------------- | | --mode | -m | Test mode (time, words, quote, code, cli, zen, custom) | | --time | -t | Time limit in seconds | | --words | -w | Word count | | --language | -l | Language | | --difficulty | | normal, expert, master | | --theme | | Theme name | | --quote-length | | 0-3 (short to thicc) | | --code-language | | Code language (python, javascript, go, rust) | | --cli-category | | CLI category (general, git, docker, npm, linux) | | --punctuation | | Enable punctuation | | --no-punctuation | | Disable punctuation | | --numbers | | Enable numbers | | --no-numbers | | Disable numbers | | --version | -v | Show version | | --help | -h | Show help |

| Command | Description | | -------------------- | ------------------------------------- | | bluekeys | Open interactive menu | | bluekeys upgrade | Upgrade to latest version | | bluekeys version | Show version | | bluekeys help | Show help |

Building from source

git clone https://github.com/anirban12d/bluekeys.git
cd bluekeys
pnpm install
pnpm run build
node dist/cli/index.js

Building a standalone binary

Requires Bun:

pnpm build:binary
./bluekeys

Documentation

| Document | Description | | ------------------------------------ | --------------------------------------------------------------- | | Architecture | Codebase structure, engine/UI separation, directory map | | Contributing | How to set up the dev environment, make changes, and submit PRs | | Themes | How to create and submit a new theme | | Languages | How to add a new language or word list | | Quotes | How to add new quotes for quote mode | | Funbox | How to create a new funbox mode |

Contributing

Contributions are welcome! See the Contributing Guide for full details on setting up your development environment, running tests, and submitting pull requests.

1. Fork the repo
2. Create your branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

For specific contribution types, see:

• Adding a theme? Follow docs/THEMES.md
• Adding a language? Follow docs/LANGUAGES.md
• Adding quotes? Follow docs/QUOTES.md
• Adding a funbox mode? Follow docs/FUNBOX.md

Bug reports & feature requests

Found a bug or have an idea? Open an issue on GitHub.

Support the project

If you enjoy Bluekeys, consider supporting its development:

Credits

Bluekeys wouldn't exist without these projects:

• Monkeytype — The original typing test that inspired this project. Bluekeys brings the Monkeytype experience to the terminal. All credit for the core concept, game modes, scoring logic, and design philosophy goes to the Monkeytype team.

• Ink — The React-based terminal UI framework that powers Bluekeys' interface. Ink makes it possible to build rich, interactive terminal apps with React components.

License

GPL-3.0 — made by anirban12d