chuma-beep/typist — 21 Stars

Topics

#cli #go #golang #productivity #tui-app #typing-practice #web-ui

Language breakdown

Go 72.7%

HTML 27.2%

Dockerfile 0.2%

▸ Files click to expand

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.}

demo

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/v2@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

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

Usage

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

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.        │
└─────────────────────────────────────────────────────────────────┘

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

🔗 More in this category