clod-coder

Overview

clod-coder is a hackertyper-style TUI game that hooks into Claude Code. When Claude uses tools (Bash, Write, Edit), the tool content appears in the game as text you have to “type out” before Claude can continue.

Designed to run in cool-retro-term for maximum aesthetic.

How It Works

1. The game listens on a Unix socket ($XDG_RUNTIME_DIR/clod-coder.sock) and TCP (127.0.0.1:31337)
2. The clod-coder hook subcommand intercepts Claude Code tool calls and sends them to the game
3. The game presents the tool content as a typing challenge
4. The hook blocks until you complete the task, then Claude continues

If the game isn’t running, hooks pass through silently — Claude works normally.

Game Modes

• leet (default) — hackertyper style, any key advances N characters
• predictive — you must type the exact next character, with a preview window ahead
• blanks — some characters are hidden and must be typed correctly; visible ones auto-advance

Building

# Build the game binary
make game

# Or build everything (including cool-retro-term)
make

# Install to ~/.local/bin
make install PREFIX=~/.local

Dependencies

• Go 1.21+
• mpv (recommended, for music playback and audio-reactive visualizer)
• ffplay (fallback audio player, no visualizer reactivity)
• Qt5 dev packages (only if building cool-retro-term)

Setup

On first launch, clod-coder shows an onboarding screen that checks prerequisites and can install the Claude Code hook automatically.

Or install the hook manually by adding a PreToolUse hook to ~/.claude/settings.json that runs clod-coder hook. The hook is a subcommand of the main binary and intercepts Bash, Write, and Edit tool calls.

Settings (mode, keys, volume, music, CRT profile, etc.) are persisted to ~/.config/clod-coder/config.json and restored on next launch. CLI flags override saved values.

Usage

# Start the game
./clod-coder

# With options
./clod-coder -mode predictive -speed 1l -keys vim -music

In another terminal, run Claude Code as normal. Tool calls will appear in the game.

CLI Flags

Flag	Default	Description
-mode	leet	Game mode: leet, predictive, blanks
-speed	3c	Speed: Nc (chars), Nw (words), Nl (lines)
-blanks	30	Blank percentage for blanks mode
-timer	0	Seconds per task (0=off)
-keys	cua	Keybinding scheme: cua, vim, emacs
-no-effects	false	Disable visual effects
-no-sound	false	Disable sound
-music	false	Start background music
-music-dir	music	Directory containing music files
-volume	80	Music volume (0-100)
-audio-device	(auto)	Audio output device
-profile	Monochrome Green	cool-retro-term profile
-socket	(auto)	Unix socket path

In-Game

• Press / to enter command mode
• Press F2 to open the config view (also /config)
• Press F1 to pause

Slash Commands

Command	Description
/mode <name>	Switch game mode
/timer <secs>	Set task timer
/effects	Toggle visual effects
/music	Toggle background music
/skip	Skip current task
/stats	Toggle stats display
/config	Open config view
/filter	Manage task filters
/help	Show available commands
/quit	Quit

Keybindings

Three preset schemes are available via -keys flag or the config view:

CUA (default)

Standard keybindings. Arrow keys for navigation, Esc to cancel, Enter to confirm.

Vim

Action	Keys
Navigate	h/j/k/l, arrows
Command	/ or :
Cancel	Esc, Ctrl+[
Quit	Ctrl+C, Ctrl+Q

Emacs

Action	Keys
Navigate	C-b/C-n/C-p/C-f, arrows
Command	M-x or /
Cancel	C-g, Esc
Quit	C-c, C-q

Custom Overrides

Create ~/.config/clod-coder/keys.json to override individual bindings on top of any preset:

{
  "quit": ["ctrl+c", "ctrl+q", "ctrl+x ctrl+c"],
  "up": ["k", "up", "ctrl+p"],
  "open_command": ["/", ":", "alt+x"]
}

Available actions: quit, pause, open_config, open_command, up, down, left, right, confirm, cancel.

Key names match bubbletea’s KeyMsg.String() output.

Audio Visualizer

When music is playing, an audio-reactive visualizer displays at the bottom of the screen. During active tasks it renders as a single-line bar so it doesn’t compete with text. On the idle screen it expands to a multi-line display alongside the matrix rain.

With mpv, the visualizer reads real audio levels via mpv’s JSON IPC protocol (using the lavfi astats filter). RMS and peak levels drive the bar heights with a bell-curve spectral distribution across the bars.

If mpv IPC is unavailable (e.g. using ffplay), the visualizer falls back to simulated random animation.

Architecture

Claude Code ──hook──> Unix Socket / TCP ──> Task Queue ──> Game UI
                      (clod-coder hook)       (FIFO)      (bubbletea)
                            │                                  │
                            └──── blocks until ────────────────┘
                                  task.Complete()

Package	Purpose
cmd/clod-coder	Entry point (multicall: game + hook)
internal/hook	Hook logic (clod-coder hook subcommand)
internal/game	Bubbletea model, views, key handling
internal/modes	Typing mode implementations
internal/effects	Matrix rain, timer, audio, visualizer
internal/keys	Keybinding presets and customization
internal/config	CLI flags, config persistence, setup
internal/server	Unix socket + TCP server
internal/queue	FIFO task queue
music/	Bundled music tracks (embed with -tags bundle)