CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Typewell is a terminal-based typing practice application written in Haskell, similar to Keybr and Monkeytype. It features multiple game modes, progress tracking, and adaptive difficulty.

Build Commands

# Build the project
cabal build

# Build and run
cabal run typewell

# Clean build artifacts
cabal clean

Architecture

The project is structured as a library (

typewell

) with an executable (

typewell

app/Main.hs          - Entry point, calls UI.runApp
src/Typewell/
├── Types.hs         - Core data types (AppState, GameState, GameMode, etc.)
├── Game.hs          - Game logic (newGame, handleChar, handleBackspace)
├── UI.hs            - Brick TUI framework integration and event handling
├── UI/
│   ├── Themes.hs    - Color schemes and visual attributes
│   └── Widgets.hs   - UI widget rendering components
├── Stats.hs         - WPM and accuracy calculations
├── Progress.hs      - JSON persistence (~/.config/typewell/)
├── Adaptive.hs      - Weak key detection for adaptive mode
└── WordLists.hs     - Word list and text generation

Key Data Flow

Startup:
```
Main.hs
```
→
```
UI.runApp
```
loads saved history/key stats, starts timer thread (100ms ticks), initializes Brick app
Event Loop: Brick handles keyboard events and timer ticks, routes to appropriate screen handlers
Game Logic:
```
Game.hs
```
processes character input,
```
Stats.hs
```
computes metrics
Persistence: On session completion,
```
Progress.hs
```
saves stats to JSON files

Core Types (Typewell.Types)

```
AppState
```
: Main state with current screen, game state, history, key stats
```
GameState
```
: Target text, typed characters, timing, current mode
```
GameMode
```
: TimedMode, WordCountMode, EndlessMode, AdaptiveMode
```
Screen
```
: MenuScreen, ModeSelectScreen, TypingScreen, ResultsScreen, HistoryScreen

Key Dependencies

brick / vty: Terminal UI framework
aeson: JSON serialization for persistence
microlens: Lightweight lenses for state manipulation

Architecture

The project is structured as a library (

typewell

app/Main.hs          - Entry point, calls UI.runApp
src/Typewell/
├── Types.hs         - Core data types (AppState, GameState, GameMode, etc.)
├── Game.hs          - Game logic (newGame, handleChar, handleBackspace)
├── UI.hs            - Brick TUI framework integration and event handling
├── UI/
│   ├── Themes.hs    - Color schemes and visual attributes
│   └── Widgets.hs   - UI widget rendering components
├── Stats.hs         - WPM and accuracy calculations
├── Progress.hs      - JSON persistence (~/.config/typewell/)
├── Adaptive.hs      - Weak key detection for adaptive mode
└── WordLists.hs     - Word list and text generation

Startup:

Main.hs

→

UI.runApp

loads saved history/key stats, starts timer thread (100ms ticks), initializes Brick app

Event Loop: Brick handles keyboard events and timer ticks, routes to appropriate screen handlers

Game Logic:

Game.hs

processes character input,

Stats.hs

computes metrics

Persistence: On session completion,

Progress.hs

saves stats to JSON files

AppState

: Main state with current screen, game state, history, key stats

GameState

: Target text, typed characters, timing, current mode

GameMode

: TimedMode, WordCountMode, EndlessMode, AdaptiveMode

Screen

: MenuScreen, ModeSelectScreen, TypingScreen, ResultsScreen, HistoryScreen

brick / vty: Terminal UI framework

aeson: JSON serialization for persistence

microlens: Lightweight lenses for state manipulation

CLAUDE.md

CLAUDE.md

Project Overview

Build Commands

Architecture

Key Data Flow

Core Types (Typewell.Types)

Key Dependencies

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Project Overview

Build Commands

Architecture

Key Data Flow

Core Types (Typewell.Types)

Key Dependencies