keybr-tui 0.2.0

A terminal typing trainer inspired by keybr.com with adaptive learning
keybr-tui-0.2.0 is not a library. 
 _              _
| | _____ _   _| |__  _ __
| |/ / _ \ | | | '_ \| '__|
|   <  __/ |_| | |_) | |
|_|\_\___|\__, |_.__/|_|
          |___/

  type. learn. master.

keybr-tui

CI Crates.io docs.rs License: MIT MSRV

A terminal typing trainer with adaptive learning, inspired by keybr.com.

keybr-tui generates practice text using phonetic Markov chains and adapts to your weaknesses in real time. Letters are introduced progressively as you demonstrate proficiency, so you always practice what you need most.

Features

  • Adaptive text generation using phonetic Markov chains (faithful port of the keybr.com algorithm)
  • Per-key confidence tracking with exponential smoothing of reaction times
  • Progressive letter unlocking based on your performance against a target speed
  • Persistent progress across sessions (stats and config saved automatically)
  • Backspace and error recovery with two error modes (forgive mistakes / stop on error)
  • Lesson summary after each practice round showing WPM, accuracy, and weakest keys
  • Progress view to review per-key statistics
  • Configurable settings (target WPM, error mode, fragment length)
  • Minimalist terminal-native UI built with ratatui

Install

Quick install (Linux & macOS)

curl -sSf https://y0sif.github.io/keybr-tui/install.sh | sh

The script downloads the latest prebuilt binary for your platform and installs it to /usr/local/bin (or ~/.local/bin if not root). Pin a specific version with KEYBR_TUI_VERSION=v0.1.0.

From crates.io

cargo install keybr-tui

Prebuilt binary

Each tagged release on the releases page ships prebuilt binaries for Linux (x86_64), macOS (Intel and Apple Silicon), and Windows (x86_64). Unix archives are .tar.gz, Windows is .zip.

tar -xzf keybr-tui-x86_64-unknown-linux-gnu.tar.gz
./keybr-tui

From source

git clone https://github.com/y0sif/keybr-tui.git
cd keybr-tui
cargo install --path .

Usage

keybr-tui [OPTIONS]

Options

Flag Description
--target-wpm <N> Set target typing speed in words per minute (default: 35)
--error-mode <MODE> move-on (default) or stop-on-error
--reset Delete saved stats and start fresh
--data-dir Print the data directory path and exit
--import <FILE> Import a keybr.com data export and exit (see below)
--force With --import: replace existing stats (a .bak backup is kept)
--help Show help
--version Show version

Migrating from keybr.com

If you've been practicing on keybr.com, you can carry your full learning state over and continue in the terminal:

  1. On keybr.com, open your profile page and click Download data — you'll get a typing-data.json file with your complete practice history.

  2. Import it:

    keybr-tui --import typing-data.json

The importer replays every session through the same per-key smoothing keybr.com uses, so your unlocked letters, per-key speeds, and focus letter come out exactly as the website computed them. Since your target speed setting is not part of the export, pass --target-wpm <N> alongside --import if you use a non-default target on keybr.com — the unlocked set is derived against it (with no flag, the target saved in your config is used, so adjusting Settings between two imports changes what counts as "learned"; re-import any time to re-derive).

Sessions from non-English layouts are skipped (this TUI is English-only for now), and existing local stats are never overwritten unless you pass --force, which still writes a stats.json.bak backup first.

Keyboard Shortcuts

Key Action
Esc Return to menu / quit
Enter Select menu item / dismiss lesson summary
Arrow keys Navigate menus and settings
Left/Right Adjust settings values

How the Adaptive Algorithm Works

keybr-tui uses a phonetic text generation algorithm ported from keybr.com:

  1. Letter scheduling: You start with a small set of letters (6). The scheduler tracks your per-key reaction time using exponential smoothing and computes a confidence score against your target speed.
  2. Unlocking: When all active letters reach sufficient confidence, a new letter is unlocked from a frequency-ordered list.
  3. Focus key: The weakest key among your active set becomes the "focus key" and appears more frequently in generated text.
  4. Text generation: A Markov chain trained on English phonetic patterns generates pronounceable pseudo-words using only your active letters, with bias toward the focus key.
  5. Tracking: Each keystroke's reaction time is recorded; at the end of each lesson, every key's mean latency feeds an exponential moving average — the same per-result smoothing keybr.com applies.

Project Structure

keybr-tui/
├── src/
│   ├── main.rs           # Entry point
│   ├── app.rs            # Central state (MVU)
│   ├── update.rs         # State transitions
│   ├── ui.rs             # Rendering (read-only state)
│   ├── events.rs         # Input + tick event channel
│   ├── tui.rs            # Terminal setup/teardown
│   ├── metrics.rs        # Per-key statistics
│   ├── config.rs         # Config file parsing
│   ├── persistence.rs    # Stats save/load
│   ├── engine/           # Adaptive text generation
│   └── components/       # UI widgets
├── docs/                 # User-facing docs (comparison, FAQ, troubleshooting)
└── .github/workflows/    # CI and release

Development

Build:

cargo build

Run:

cargo run

Test:

cargo test

Format:

cargo fmt --all

Lint:

cargo clippy --all-targets -- -D warnings

See CONTRIBUTING.md for the full contribution workflow.

Configuration

Config file location (XDG on Linux):

~/.config/keybr-tui/config.toml

Example config:

target_wpm = 35
error_mode = "forgive-mistakes"  # or "stop-on-error"
fragment_length = 100

Stats are saved separately in the data directory. Use keybr-tui --data-dir to find it.

Screenshots

A terminal recording (asciinema/vhs) is on the roadmap. For now, run cargo install keybr-tui and try it.

Documentation

Credits

License

MIT