```
_ _
| < __/ |_| | |_) | |
|_|\_\___|\__, |_.__/|_|
|___/
type. learn. master.
```
# keybr-tui
[](https://github.com/y0sif/keybr-tui/actions/workflows/ci.yml) [](https://crates.io/crates/keybr-tui) [](https://docs.rs/keybr-tui) [](LICENSE) [](https://www.rust-lang.org)
A terminal typing trainer with adaptive learning, inspired by [keybr.com](https://www.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)
```bash
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
```bash
cargo install keybr-tui
```
### Prebuilt binary
Each tagged release on the [releases page](https://github.com/y0sif/keybr-tui/releases) ships prebuilt binaries for Linux (x86_64), macOS (Intel and Apple Silicon), and Windows (x86_64). Unix archives are `.tar.gz`, Windows is `.zip`.
```bash
tar -xzf keybr-tui-x86_64-unknown-linux-gnu.tar.gz
./keybr-tui
```
### From source
```bash
git clone https://github.com/y0sif/keybr-tui.git
cd keybr-tui
cargo install --path .
```
## Usage
```bash
keybr-tui [OPTIONS]
```
### Options
| `--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](https://www.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:
```bash
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
| `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](https://github.com/aradzie/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
```text
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:
```bash
cargo build
```
Run:
```bash
cargo run
```
Test:
```bash
cargo test
```
Format:
```bash
cargo fmt --all
```
Lint:
```bash
cargo clippy --all-targets -- -D warnings
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution workflow.
## Configuration
Config file location (XDG on Linux):
```text
~/.config/keybr-tui/config.toml
```
Example config:
```toml
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
- [docs/comparison.md](docs/comparison.md) — how keybr-tui compares to alternatives
- [docs/faq.md](docs/faq.md) — frequently asked questions
- [docs/troubleshooting.md](docs/troubleshooting.md) — common issues and fixes
## Credits
- Algorithm inspired by [keybr.com](https://www.keybr.com) by [aradzie](https://github.com/aradzie/keybr.com)
- Built with [ratatui](https://ratatui.rs/) and [crossterm](https://github.com/crossterm-rs/crossterm)
## License
[MIT](LICENSE)