⌨️ CLI-Local-Monkeytype

A lightweight, flicker-free, and highly responsive Terminal User Interface (TUI) touch-typing tutor built in Python. Designed for minimalists, terminal enthusiasts, and developers who want to practice typing directly in their shell environment without leaving the command line.

✨ Key Features

• Interactive TUI Menu: Seamless in-terminal navigation to select dictionary modes (en_1000, ru_1000) and session lengths (5, 10, 15, 25, 50 words).

• Vim Keybindings & Arrow Navigation: Fully navigable using standard Arrow keys or Vim motion keys (h / j / k / l).

• Finite State Machine Architecture: Smooth transitions between MENU → TYPING → RESULTS states without process restarts or screen flashes.

• Flicker-Free Multi-Line Renderer: Powered by blessed and textwrap. Automatically wraps long texts (up to 50+ words) into multi-line centered blocks with zero screen tearing.

• CLI Flags Integration: Pre-configure sessions directly from your shell (-m, -w) or quickly inspect history without entering the UI (-H).

• Session History & JSON Storage: Automatically logs session metrics (timestamp, mode, word count, WPM, accuracy, time) into history.json.

• Terminal Resize Resilience: Intercepts window resize events (KEY\_RESIZE) and dynamically re-centers the interface layout.

• Safe Terminal Context Management: Reliably restores terminal cursor, buffer, and input modes upon exit or Ctrl+C.

🛠️ Architecture

The codebase follows a clean Separation of Concerns (SoC) modular design:

CLI-Local-Monkeytype/  
├── dicts/              # Local dictionary text files (en_1000.txt, ru_1000.txt)  
├── history.json        # Saved typing sessions history  
└── src/  
    ├── config.py       # Themes, constants, AppState enum, and dictionary settings  
    ├── engine.py       # Core logic: WordGenerator and StatsTracker (WPM/Accuracy)  
    ├── storage.py      # Persistence layer for reading/writing history.json  
    ├── ui.py           # TUIContext (terminal safety) & TUIRenderer (multi-line layout)  
    └── main.py         # Entry point, CLI parser, menu loop, and FSM app state runner

WPM (Words Per Minute) — typing speed. Calculated as the number of correctly typed characters divided by 5 (average word length), then converted to a per-minute rate. Formula used: (correct_chars / 5) / minutes Accuracy — typing precision. Percentage of correct keystrokes out of all keystrokes made. correct_chars / total_typed * 100

🚀 Getting Started

Prerequisites

• Python 3.10+

• Linux / macOS / Windows (WSL or Modern Terminal)

Installation

1. Clone the repository:

Bash

git clone https://github.com/zen-dix/CLI-Local-Monkeytype
cd CLI-Local-Monkeytype

2. Set up a virtual environment:

Bash

python -m venv venv

source venv/bin/activate  # On Windows: venv\\Scripts\\activate

3. Install dependencies:

Bash

pip install -r requirements.txt

4. Run the application:

Bash

python src/main.py

💡 Usage & CLI Options

Bash

# Launch interactive TUI menu

python src/main.py


# Launch directly with pre-selected mode and word count

python src/main.py -m ru\_1000 -w 25


# Show session history in terminal and exit

python src/main.py -H

Controls

• Menu Navigation: ↑ / ↓ / ← / → or k / j / h / l

• Select / Confirm: Enter or Space

• Exit / Return to Menu: Esc

🗺️ Roadmap & Future Plans

• Code Practice Mode: Support for syntax-highlighted code snippets with auto-skipping indentation.

• Time-Based Sessions: Alternative timer modes (15s, 30s, 60s) alongside word counts.

• Custom Dictionaries: Ability to load custom text files on the fly via CLI flags.

• Adaptive Backspace Stack: Advanced error tracking to recalculate real-time typing dynamics on backspaces.