typist

README

╔══════════════════════════════════════════════════════════════════╗
║                                                                  ║
║     ████████╗██╗   ██╗██████╗ ██╗███████╗████████╗               ║
║     ╚══██╔══╝╚██╗ ██╔╝██╔══██╗██║██╔════╝╚══██╔══╝               ║
║        ██║    ╚████╔╝ ██████╔╝██║███████╗   ██║                  ║
║        ██║     ╚██╔╝  ██╔═══╝ ██║╚════██║   ██║                  ║
║        ██║      ██║   ██║     ██║███████║   ██║                  ║
║        ╚═╝      ╚═╝   ╚═╝     ╚═╝╚══════╝   ╚═╝                  ║
║                                                                  ║
║              A fast, offline typing test                         ║
║         No account. No paywall. No internet required.            ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

A fast, offline typing test
_{No account. No paywall. No internet required.}

---

---

Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Terminal UI
• Web UI
• Code Mode
• Blind Mode
• Scores & Export
• Architecture
• Roadmap
• License

---

Features

┌────────────────────────────────┬──────────┬──────────┐
│ Feature                        │ Terminal │   Web    │
├────────────────────────────────┼──────────┼──────────┤
│ Word Mode — 30 common words    │    ✓     │    ✓    │
│ Time Mode — 15/30/60/120s      │    ✓     │    ✓    │
│ Quote Mode — Literary excerpts │    ✓     │    ✓    │
│ Code Mode — Go/JS/Python/Rust  │    ✓     │    ✓    │
│ Syntax Highlighting (Chroma)   │    ✓     │    ✓    │
│ Live WPM + Accuracy Stats      │    ✓     │    ✓    │
│ WPM Graph Over Time            │Sparkline │ Chart.js │
│ Mistake Heatmap                │ Top-6    │Keyboard  │
│ Blind Mode (muscle memory)     │    ✓     │    ✗    │
│ Persistent Personal Bests      │    ✓     │    ✓    │
│ Session History (last 200)     │    ✓     │    ✗    │
│ Export to JSON / CSV           │    ✓     │    ✗    │
│ Single Binary, Zero Deps       │    ✓     │    ✓    │
└────────────────────────────────┴──────────┴──────────┘

---

Installation

   go install github.com/chuma-beep/typist@latest

Prerequisite

• Go 1.21+ — Download here

Build from Source

# 1. Clone the repository
git clone https://github.com/chuma-beep/typist
cd typist

# 2. Install dependencies
go mod tidy

# 3. Build the binary
go build -o typist .

# 4. Move to your PATH (optional)
mv typist ~/.local/bin/  # Linux/Mac
# or
mv typist $GOPATH/bin/   # If GOPATH is set

---

Usage

typist          # Launch terminal UI
typist --web    # Launch web UI on random free port
typist --help   # Show all options

---

Terminal UI

Terminal UI

┌─────────────────────────────────────────────────────────────────┐
│  CONTROLS                                                       │
├─────────────────────────────────────────────────────────────────┤
│  Menu                                                           │
│    ← →     Switch mode                                          │
│    ↑ ↓     Switch sub-row (time/lang)                           │
│    Enter   Start test                                           │
│    Esc/q   Quit                                                 │
│                                                                 │
│  Typing                                                         │
│    Ctrl+R  Restart with new text                                │
│    Ctrl+B  Toggle Blind Mode                                    │
│    Tab     Type tab (code mode)                                 │
│    Enter   Type newline (code mode)                             │
│    Esc     Quit                                                 │
│                                                                 │
│  Results                                                        │
│    Enter/R  Try again                                           │
│    M        Back to menu                                        │
│    H        View session history                                │
│    J        Export to JSON                                      │
│    C        Export to CSV                                       │
│    Esc      Quit                                                │
└─────────────────────────────────────────────────────────────────┘

---

Web UI

The web interface provides a beautiful browser-based experience with:

• Chart.js WPM graphs
• Visual keyboard mistake heatmap
• Same core typing engine as TUI
• Responsive design

Launch with:

typist --web

The server automatically picks a free port on 127.0.0.1 — no conflicts, no firewall prompts.

---

Code Mode Type real snippets with syntax highlighting powered by Chroma:

┌────────────┬──────────┬────────────────────────────────────────┐
│ Language   │ Snippets │ Examples                               │
├────────────┼──────────┼────────────────────────────────────────┤
│ Go         │    8     │ Generics, channels, linked lists       │
│ JavaScript │    6     │ Debounce, memoize, EventEmitter        │
│ Python     │    5     │ Quicksort, LRU cache, decorators       │
│ Rust       │    5     │ Pattern matching, traits, generics     │
└────────────┴──────────┴────────────────────────────────────────┘

Blind Mode

┌─────────────────────────────────────────────────────────────────┐
│  Ctrl+B  →  Every char becomes · (green=correct, red=wrong)     │
│                                                                 │
│  Forces typing from memory. Essential for muscle memory.        │
└─────────────────────────────────────────────────────────────────┘

---

Quick Start with Docker

Run Typist instantly — no need to install Go or any dependencies.

Steps

1. Clone the repository:

   git clone https://github.com/chuma-beep/typist.git
   cd typist

2. Run the application:

docker compose up --build

3. Open the app in your browser: http://localhost:33241

Features

Multi-stage Dockerfile (Go → Alpine) for a small and secure image Non-root user for better security Only the compiled binary is shipped in the final image

4. Stop the app with:

docker compose down

Scores & Export

┌─────────────────────────────────────────────────────────────────┐
│  Storage:  ~/.typist/scores.json                                │
│                                                                 │
│  Export (from results screen):                                  │
│    J  →  ~/typist-export-<timestamp>.json                 │
│    C  →  ~/typist-export-<timestamp>.csv                  │
└─────────────────────────────────────────────────────────────────┘

---

Tech Stack

┌────────────────────┬─────────────────────────┬──────────────────┐
│ Component          │ Technology              │ Purpose          │
├────────────────────┼─────────────────────────┼──────────────────┤
│ TUI Framework      │ Bubble Tea              │ Elm architecture │
│ Terminal Styling   │ Lipgloss                │ Colors/layout    │
│ Syntax Highlight   │ Chroma v2               │ 300+ languages   │
│ Web Charts         │ Chart.js                │ WPM graphs       │
│ Core               │ Go Standard Library     │ HTTP, JSON, CSV  │
└────────────────────┴─────────────────────────┴──────────────────┘

---

Architecture

typist/
├── main.go          # Entry point, --web flag
├── model.go         # Bubble Tea model — all states, update, view
├── highlight.go     # Chroma tokenizer → lipgloss StyleMap
├── words.go         # Word/quote/code generation + line wrapping
├── snippets.go      # Code snippet library (Go, JS, Python, Rust)
├── scores.go        # Persistent scores, PB tracking, JSON/CSV export
├── styles.go        # lipgloss styles (Catppuccin Mocha)
├── web.go           # Embedded HTTP server for --web mode
├── web/
│   └── index.html   # Single-file web UI (Chart.js, no other deps)
└── quotes.json      # Embedded literary quotes

Key Design Decisions

Decision	Rationale
go:embed	Bakes quotes.json and web/index.html into the binary — zero runtime assets needed
Random Free Port	Server picks a random port on 127.0.0.1 — no conflicts, no firewall issues
Server-Side Tokenization	Syntax highlighting happens via Chroma; only token kinds sent to web UI — no duplicate tokenizer in JS
Line Wrapping	Code uses wrapCodeLines (splits on \n, preserves indentation); prose uses wrapIntoLines (soft-wraps at 60 chars)
Pure Value Types	Bubble Tea model returns new Model on every transition — no pointer mutation in the update loop

---

Roadmap

• WPM graph in TUI (unicode sparkline → full bar chart)
• Dark / light theme toggle
• Focus mode (hide stats while typing)
• Custom text mode (paste your own code)
• WebAssembly build for browser deployment (no server needed)

---

┌─────────────────────────────────────────────────────────────────┐
│  MIT License  │  github.com/chuma-beep/typist                   │
└─────────────────────────────────────────────────────────────────┘

Back to Top