clavirio 0.2.3

A terminal typing tutor with virtual keyboard, built-in lessons, and session tracking
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# clavirio

![](https://github.com/alexylon/clavirio/actions/workflows/rust.yml/badge.svg)   [![Crates.io](https://img.shields.io/crates/v/clavirio.svg?color=blue)](https://crates.io/crates/clavirio)

[www.clavir.io](https://www.clavir.io)

*From Latin **clavis** (key) — a terminal typing tutor.*

<div align="center"><img src="/assets/images/screenshot.png" style="width: 800px;" alt="clavirio"></div>

A terminal typing tutor built with Rust and [ratatui](https://ratatui.rs). Practice with built-in lessons or any text file while a virtual keyboard tracks your keystrokes in real time.

## Features

- **15 built-in lessons** — progressive drills from home row basics to full paragraphs and code, ordered by difficulty
- **Live stats** — WPM, accuracy %, elapsed time, keystrokes, and line progress update as you type
- **Virtual keyboard** — highlights the expected next key (including Shift) with a finger hint (**P**inky, **R**ing, **M**iddle, **I**ndex, **T**humb) on the top border; adapts to macOS and PC layouts
- **Error feedback** — wrong keystrokes are shown inline and block progress until corrected with Backspace
- **Completion summary** — final WPM, accuracy percentage, and your weakest keys
- **Session history** — results saved to `~/.clavirio/history.json` with per-lesson tracking, scrollable history view, and averages across completed sessions
- **Progress tracking** — the menu cursor remembers your last built-in lesson: points to it if unfinished, advances to the next if completed
- **Custom text** — load any text file via `Ctrl-F` or as a CLI argument
- **Graceful shutdown** — in-progress sessions are saved on SIGTERM/SIGHUP

## Lessons

| # | Lesson | Focus |
|---|--------|-------|
| 1 | f j d k | Index fingers |
| 2 | d k (+ f j) | Index + middle fingers |
| 3 | s l ; (+ f j d k) | Ring + pinky fingers |
| 4 | a s d f j k l ; | Full home row |
| 5 | g h (home row) | Home row complete |
| 6 | e i r u | Top row reach |
| 7 | q w e r t y u i o p | Full top row |
| 8 | z x c v b n m , . | Bottom row |
| 9 | All Letters | Pangrams |
| 10 | Capitals & Shift | Mixed case |
| 11 | 0-9 Numbers | Numbers in context |
| 12 | Punctuation & Symbols | Special characters |
| 13 | Common Words | High-frequency words |
| 14 | Full Paragraphs | Real-world text |
| 15 | Code (Rust) | Programming syntax |

## Build & Run

```
cargo build --release
cargo run
```

Optionally pass a file directly:

```
cargo run -- sample.txt
```

## Terminal Size

clavirio is a terminal UI application — your terminal window should be large enough to display all elements (text panel, keyboard, stats).
On a laptop screen this usually means a maximized terminal window.

## Controls

| Key | Action |
|-----|--------|
| `↑`/`↓` or `k`/`j` | Navigate lesson menu / scroll history |
| `Enter` | Start selected lesson |
| `h` | View session history (main menu) |
| `Ctrl-F` | Open file path input |
| `Ctrl-R` | Restart current text |
| `Ctrl-C` | Save and quit immediately |
| `Esc` | Save and back to menu / quit |
| `Backspace` | Correct a mistake |
| `r` | Restart (completion screen) |