232 lines
9.4 KiB
Markdown
232 lines
9.4 KiB
Markdown
# keydr
|
||
|
||
A terminal typing tutor with adaptive learning, a skill-tree progression
|
||
system, and live statistics — built in Rust on [ratatui]. Heavily inspired by
|
||
[keybr.com], extended for code practice and the terminal.
|
||
|
||
Warning: still very much a WIP and is heavily vibe-coded so there may be bugs.
|
||
Backwards compatibility is not guaranteed in this phase of development.
|
||
|
||
<img width="1187" height="797" alt="Adaptive drill screen" src="https://github.com/user-attachments/assets/74c358d6-976f-42bc-ae24-efd1feab5579" />
|
||
|
||
<details>
|
||
<summary><h2>Screenshots</h2></summary>
|
||
|
||
<img width="1187" height="797" alt="Main menu" src="https://github.com/user-attachments/assets/64512852-c379-4e4b-94c6-6e62ef7d0526" />
|
||
|
||
<img width="1437" height="988" alt="Skill tree" src="https://github.com/user-attachments/assets/d975ac93-ec63-4fff-a275-27a71754d3bb" />
|
||
|
||
<img width="1437" height="988" alt="Statistics" src="https://github.com/user-attachments/assets/d98e67e8-1f85-46db-a22b-fe8b13cbe3d0" />
|
||
|
||
<img width="1437" height="988" alt="Keyboard explorer" src="https://github.com/user-attachments/assets/68eb3127-0046-499c-9a11-a641a82debf3" />
|
||
|
||
<img width="1437" height="988" alt="Code drill (farout theme)" src="https://github.com/user-attachments/assets/b079037b-2ce8-4bba-93b1-38151ebd7b68" />
|
||
|
||
<img width="1437" height="988" alt="Passage drill (kanagawa lotus theme)" src="https://github.com/user-attachments/assets/78d0eb61-4be0-4c11-aadb-72c355458314" />
|
||
|
||
<img width="1437" height="988" alt="Settings" src="https://github.com/user-attachments/assets/912b743e-72e3-4a19-84cd-d0ee9267b75e" />
|
||
|
||
</details>
|
||
|
||
|
||
## What makes it different
|
||
|
||
Most TUI typing apps either drop you on a fixed word list or randomize from a
|
||
dictionary. keydr keeps a model of _your_ typing: per-key timing, per-bigram
|
||
error rates, and a confidence score for every key on the keyboard. The text it
|
||
generates for you is shaped by that model — words bias toward the keys you're
|
||
slowest at, new keys unlock only when the keys you already have are solid, and
|
||
the difficulty grows with you.
|
||
|
||
## Features
|
||
|
||
### Adaptive engine
|
||
|
||
- **Per-key confidence model.** Every keystroke updates an exponential moving
|
||
average of your per-key time. Your `confidence` for a key is your target
|
||
speed divided by that filtered time — a key with `confidence >= 1.0` is at
|
||
or above your target speed.
|
||
- **Gradual letter unlocking.** You start with 6 letters in English-frequency
|
||
order (`e t a o i n …`). A new letter unlocks only when every letter you
|
||
already have is confident, so you're never thrown into the full alphabet at
|
||
once.
|
||
- **Focused-key biasing.** Whichever included key has the lowest confidence
|
||
becomes your "focused" key. The generator searches its Markov chain for
|
||
states containing the focused letter and starts pseudo-words from there, so
|
||
drills naturally pile up practice on your weak spots.
|
||
- **Phonetic pseudo-word generation.** Words are generated from a Markov
|
||
transition table (the same approach as keybr) so they're pronounceable and
|
||
language-shaped, not random consonant noise.
|
||
- **N-gram error tracking.** Beyond single keys, keydr tracks bigrams and
|
||
trigrams with Laplace-smoothed error rates and a redundancy formula that
|
||
separates _genuine_ transition difficulties (e.g. awkward same-finger
|
||
bigrams) from errors that are just proxies for a single weak key. Hard
|
||
bigrams get folded into drill selection.
|
||
|
||
### Skill tree
|
||
|
||
Once you've mastered the lowercase alphabet, you don't just keep grinding
|
||
prose — five sibling branches unlock at once and you pick what to drill next:
|
||
|
||
- **Capitals** (A–Z, 3 levels) — sentence-start and proper-noun rules
|
||
- **Numbers** (0–9, 2 levels)
|
||
- **Prose punctuation** (`. , ' " ? !` …, 3 levels)
|
||
- **Whitespace** (Tab, Enter, …, 2 levels)
|
||
- **Code symbols** (`{ } [ ] ( ) ; : = + - * /` …, 4 levels)
|
||
|
||
Each branch tracks its own current level and its own focused key. You can have
|
||
multiple branches "in progress" at once, and drills can be scoped globally
|
||
(everything you've unlocked) or to a single branch.
|
||
|
||
### Three drill modes
|
||
|
||
- **Adaptive** — the default. Generated text from the phonetic model, biased
|
||
by your skill-tree scope and focused key.
|
||
- **Code** — language-specific syntax practice. Bundled snippets for Rust,
|
||
Python, JavaScript, and Go, with optional opt-in downloads of real code
|
||
samples from GitHub for more variety. Configurable per-language, with an
|
||
onboarding screen on first use and a download progress screen.
|
||
- **Passage** — type real prose from public-domain books (Project
|
||
Gutenberg). Opt-in downloads, configurable paragraphs-per-book limit, falls
|
||
back to bundled content when offline.
|
||
|
||
### Statistics dashboard
|
||
|
||
A multi-tab dashboard with everything the engine has learned about you:
|
||
|
||
- **Dashboard** — current WPM, accuracy, confident-key count, level/streak
|
||
- **History** — recent drills with WPM/accuracy
|
||
- **Activity** — a GitHub-style heatmap of drilling activity over time
|
||
- **Accuracy** — per-key accuracy heatmap laid out on the keyboard
|
||
- **Timing** — per-key timing heatmap
|
||
- **N-grams** — your worst bigrams/trigrams, redundancy scores, watchlist of
|
||
emerging weak transitions, and what's currently driving drill focus
|
||
|
||
### Visual keyboard
|
||
|
||
A live keyboard diagram colors each key by the finger that should press it,
|
||
highlights your focused key, and (in terminals that support the Kitty keyboard
|
||
protocol) lights up modifier keys as you press them. A separate **Keyboard
|
||
Explorer** screen lets you click around the layout to inspect any key's
|
||
stats.
|
||
|
||
### Theming
|
||
|
||
14 built-in themes: Catppuccin (Mocha/Latte), Dracula, Gruvbox (Dark/Darkest),
|
||
Kanagawa (Wave/Dragon/Lotus), Nord, One Dark, Solarized Dark, Tokyo Night,
|
||
Farout, plus an ANSI-safe `terminal-default` that respects your terminal's
|
||
own colors.
|
||
|
||
### Internationalization
|
||
|
||
- **UI translated into 21 languages** (`en`, `de`, `es`, `fr`, `it`, `pt`,
|
||
`nl`, `sv`, `da`, `nb`, `fi`, `pl`, `cs`, `ro`, `hr`, `hu`, `lt`, `lv`,
|
||
`sl`, `et`, `tr`).
|
||
- **Dictionaries for the same 21 languages**, sourced from
|
||
[keybr-content-words](https://github.com/aradzie/keybr.com).
|
||
- **Keyboard layout profiles**: QWERTY, Dvorak, Colemak, German QWERTZ,
|
||
French AZERTY — with per-layout finger maps so the diagram stays accurate.
|
||
- Unicode-normalized (NFC) input matching, so composed and decomposed forms
|
||
of accented characters compare equal.
|
||
|
||
### Import / export
|
||
|
||
Back up everything — config, profile, key stats, ranked stats, drill history
|
||
— to a single timestamped JSON file from the Settings page, and restore it on
|
||
another machine. Machine-local paths (download directories) are preserved
|
||
from the target machine on import. Versioned format with a clear error if
|
||
schemas don't match.
|
||
|
||
### Other niceties
|
||
|
||
- Atomic JSON writes (temp file → fsync → rename) so a crash mid-save can't
|
||
corrupt your stats.
|
||
- Auto-continue between drills with a brief input lock so a trailing
|
||
keystroke doesn't start the next drill prematurely.
|
||
- Mouse support for menus, tabs, and the keyboard explorer.
|
||
|
||
## Build and run
|
||
|
||
keydr is a regular Cargo project. You need a recent Rust toolchain (Rust
|
||
edition 2024, i.e. a 2026-era stable compiler).
|
||
|
||
```sh
|
||
git clone <repo-url> keydr
|
||
cd keydr
|
||
cargo run --release
|
||
```
|
||
|
||
Or build once and run the binary:
|
||
|
||
```sh
|
||
cargo build --release
|
||
./target/release/keydr
|
||
```
|
||
|
||
### CLI flags
|
||
|
||
```sh
|
||
keydr [--theme <name>] [--layout <layout>] [--words <n>]
|
||
```
|
||
|
||
- `--theme, -t` — pick a theme by name for this run (e.g. `dracula`,
|
||
`nord`, `catppuccin-mocha`)
|
||
- `--layout, -l` — pick a keyboard layout: `qwerty`, `dvorak`, `colemak`,
|
||
`de_qwertz`, `fr_azerty`
|
||
- `--words, -w` — number of words per drill
|
||
|
||
Everything else is set from inside the app, on the Settings screen.
|
||
|
||
### Features
|
||
|
||
The `network` Cargo feature (on by default) pulls in `reqwest` and enables the
|
||
optional GitHub code download and Project Gutenberg passage download flows. To
|
||
build a fully offline binary:
|
||
|
||
```sh
|
||
cargo build --release --no-default-features
|
||
```
|
||
|
||
### Files on disk
|
||
|
||
- Config: `~/.config/keydr/config.toml`
|
||
- Profile, key stats, drill history: `~/.local/share/keydr/*.json`
|
||
- Downloaded passages: `~/.local/share/keydr/passages/`
|
||
- Downloaded code samples: `~/.local/share/keydr/code/`
|
||
|
||
(`dirs` is used to resolve these, so the exact paths follow XDG/macOS/Windows
|
||
conventions on your platform.)
|
||
|
||
### Tests and benchmarks
|
||
|
||
```sh
|
||
cargo test
|
||
cargo bench # n-gram benchmarks in benches/
|
||
```
|
||
|
||
## Terminal requirements
|
||
|
||
keydr works in any reasonably modern terminal. For the best experience —
|
||
modifier-key highlighting on the keyboard diagram, unambiguous key
|
||
disambiguation, and per-key release events — use a terminal that supports the
|
||
[Kitty keyboard protocol] (Kitty, WezTerm, foot, recent Ghostty, recent
|
||
Alacritty). keydr falls back gracefully on terminals that don't (tmux, mosh,
|
||
SSH to older hosts) using timer-based heuristics.
|
||
|
||
A true-color terminal is recommended so the bundled themes render as
|
||
intended; the `terminal-default` theme is provided for ANSI-only setups.
|
||
|
||
## License and attribution
|
||
|
||
keydr is licensed under the GNU Affero General Public License v3.0 only
|
||
(AGPL-3.0-only) — see [LICENSE](LICENSE).
|
||
|
||
It incorporates content and ideas from [keybr.com] (dictionaries, the core
|
||
adaptive algorithm). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for
|
||
attribution and [docs/license-compliance.md](docs/license-compliance.md) for
|
||
the compliance process.
|
||
|
||
[ratatui]: https://ratatui.rs/
|
||
[keybr.com]: https://www.keybr.com/
|
||
[Kitty keyboard protocol]: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
|