clavirio

www.clavir.io

Learn touch typing without leaving the terminal.

Progressive lessons for QWERTY, Dvorak & Colemak.
Real-time stats, a virtual keyboard with finger hints, and session history — in a fast,
lightweight binary built with Rust and ratatui.

clavirio — from Latin clavis (key).

Table of Contents

• Methodology
• Features
• Lessons
• Install
• CLI
• Controls
• Settings

Methodology

Research on typing skill suggests that skilled typing relies more on implicit procedural control than on explicit knowledge of key locations. The paper also suggests that the keyboard is represented in terms of its row-and-column structure, not as a memorized list of individual letters.

Clavirio follows that idea by teaching the keyboard row by row with the same 7-lesson progression for each row:

index pair → middle pair → ring pair → pinky pair → reach pair → full row → row + Shift

Each lesson introduces only 2 new keys and uses only characters from earlier lessons. The same progression is used for QWERTY, Dvorak, and Colemak, so the lesson structure stays consistent across layouts.

The paper does not compare typing tutors directly, so it does not prove that this exact sequence is optimal. It does support the broader design choice: structured, incremental repetition that builds reliable finger-to-key habits instead of relying on conscious recall of key positions.

Features

• Lessons mode — 27 progressive drills: home row → top row → bottom row (2 keys per lesson, by finger pair), numbers, and symbols; lessons 1-21 are layout-specific, 22-27 are shared
• Practice mode — random words (english 200/1k), code keywords (Rust, Python, JavaScript, Go, C/C++, Java, HTML/CSS), timed sessions (30s/60s), weak keys, common bigrams, quotes, and zen free-typing
• Punctuation & numbers — optional injection into word and code drills, toggle with 5/6 in practice mode
• Live stats — WPM, accuracy, errors, time, and line progress in a one-row status bar
• WPM sparkline — speed over time on the results screen
• 3 keyboard layouts — QWERTY, Dvorak, and Colemak
• Virtual keyboard — highlights the next key with finger hints (Pinky, Ring, Middle, Index, Thumb)
• Error feedback — two modes: error stop off (default) lets you type past mistakes with backspace correction within the current word; error stop on blocks until corrected
• Weak key tracking — per-key accuracy saved across sessions; press w after a drill to practice that session's weakest keys, or select Weak Keys from the menu for cumulative stats
• Session history — saved to ~/.clavirio/history.json with per-lesson tracking and averages
• Progress tracking — remembers your lesson and menu mode across sessions
• Custom text — load any file via Ctrl-F or --file
• Dark & light themes

Lessons

Lessons 1-21 are layout-specific — 7 lessons per row (home, top, bottom), 2 new keys each. Lessons 22-27 are shared (numbers and symbols).

Install

Prebuilt binary

Download from GitHub Releases (macOS, Linux, Windows):

# macOS / Linux
tar xzf clavirio-*.tar.gz
sudo mv clavirio /usr/local/bin/

# Windows — extract the .zip, then add the folder to your PATH

macOS: On first run, macOS may block the binary. Go to System Settings → Privacy & Security and click Allow Anyway.

With Rust

cargo install clavirio

From source

git clone https://github.com/alexylon/clavirio.git
cd clavirio
cargo build --release

CLI

clavirio                        # interactive menu
clavirio -w                     # 100 random words (english 200)
clavirio -w 50 -l 1k            # 50 random words (english 1k)
clavirio -w -l rust             # 100 code tokens (rust)
clavirio -t 60                  # 60-second timed session
clavirio -t 30 -l python        # 30-second timed (python)
clavirio -w -p -n               # words with punctuation and numbers
clavirio -f path/to/file.txt    # custom file

Available word lists: 200, 1k, rust, python, javascript (js), go, c (cpp), java, html (css)

Controls

Best with a maximized terminal window so text, keyboard, and stats fit comfortably.

Main Menu

Typing

Finished Screen

Pause Menu

Settings

Preferences are stored in ~/.clavirio/settings.toml and saved automatically.

[keyboard]
layout = "qwerty"           # qwerty, dvorak, colemak

[display]
show_keyboard = true
show_hints = true
show_fingers = true
theme = "dark"              # dark, light
include_punctuation = false
include_numbers = false
practice_mode = false
error_stop = false              # true = block on error, false = advance past errors