LitClock Go

A terminal-native literary clock written in Go. It chooses a book passage for the current minute, lays it out like an e-ink display, and bolds only the words that tell the time.

This repository is a focused Go port of kapoorankush/litclock. It keeps the original quote corpus and attribution while replacing the Raspberry Pi, Python, web, and display-driver stack with a self-contained TUI.

Run

Go 1.24 or newer is required.

go run ./cmd/litclock

Mature quotes are disabled by default. Enable them with either form:

go run ./cmd/litclock --allow-nsfw
ALLOW_NSFW_QUOTES=true go run ./cmd/litclock

The quote corpus is embedded at build time, so the compiled binary needs no data files:

go build -o litclock ./cmd/litclock
./litclock

Controls

Key	Action
q / Ctrl+C	Quit
r	Pick another quote for the current minute
s	Toggle mature quotes

The display updates automatically at each minute boundary and responds to terminal resizing. For a non-interactive frame suitable for scrollback:

go run ./cmd/litclock --once --allow-nsfw

Architecture

The code uses a deliberately small ports-and-adapters layout:

cmd/litclock        composition root and CLI
    ├── internal/clock   quote model, policy, and selection use case
    ├── internal/corpus  embedded CSV adapter implementing clock.Source
    ├── internal/frame   framework-free wrapping and time emphasis
    └── internal/tui     Bubble Tea and Lip Gloss presentation adapter

Dependencies point toward internal/clock; the quote-selection and emphasis rules can be tested without a terminal or Bubble Tea.

Test

go test ./...
go vet ./...

Credits and licensing

Program code is available under the MIT License. The embedded quote corpus contains material with additional attribution, NonCommercial, and ShareAlike terms. See NOTICE.md before redistributing or using the corpus.