README
¶
tuigotchi
A terminal focus companion: a to-do-driven focus timer whose Tamagotchi-style companion builds legendary LEGO sets out of your focused minutes.
Pick a to-do, declare a watch (any length — 50 minutes pairs well with a 50-10 cycle), and stay focused: every full focused minute earns a piece toward the set your companion is building, from the Orchid all the way up to the UCS Millennium Falcon. Finished sets live forever in your collection.
- Auto-pause: if the terminal loses focus for more than a few seconds, the watch pauses — focus back to resume. Left paused too long, the watch is set aside (pieces earned are kept; the companion gets a little sad, never dies).
- No currency, no streaks: just one set at a time and a collection that only grows.
Install / run
Requires Go 1.26+ on macOS or Linux (Windows isn't supported yet — the single-instance lock uses POSIX file locking).
One-line install:
go install github.com/murathan9165/tuigotchi/cmd/tuigotchi@latest
tuigotchi
Or run from a clone:
git clone https://github.com/murathan9165/tuigotchi.git
cd tuigotchi
go run ./cmd/tuigotchi
There's no config step: the app creates its data directory on first launch (see Data).
Only one tuigotchi can run at a time. A second instance exits immediately with "another tuigotchi instance appears to be running" — that's by design, not a hang, and there's nothing to clean up; the lock releases on exit or crash.
Updating
Bug fixes land as new tags, so re-run
go install github.com/murathan9165/tuigotchi/cmd/tuigotchi@latest
(or git pull in your clone) to pick up the latest version.
Focus detection inside tmux
Auto-pause relies on terminal focus events. Most terminal emulators support them out of the box; inside tmux you must enable pass-through:
# ~/.tmux.conf
set -g focus-events on
Without this, tuigotchi still works — it just can't notice when you switch away, so watches won't auto-pause.
Data
State lives in your user config directory (~/Library/Application Support/tuigotchi
on macOS, ~/.config/tuigotchi on Linux): an append-only event log plus a
small to-do file. Delete the directory to start over.
Feedback
Found a bug or something confusing? Please open an issue — the bug report template asks for everything needed to reproduce it.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tuigotchi
command
Command tuigotchi is a terminal focus companion: a to-do-driven focus timer whose Tamagotchi-style companion builds legendary LEGO sets out of your focused minutes.
|
Command tuigotchi is a terminal focus companion: a to-do-driven focus timer whose Tamagotchi-style companion builds legendary LEGO sets out of your focused minutes. |
|
internal
|
|
|
applock
Package applock guards against two tuigotchi processes writing the same event log — a second instance would silently violate the single-active- watch invariant the reducers depend on.
|
Package applock guards against two tuigotchi processes writing the same event log — a second instance would silently violate the single-active- watch invariant the reducers depend on. |
|
builds
Package builds holds the bundled roster of real LEGO sets the companion works toward, and the tier-unlock rules for choosing the next one.
|
Package builds holds the bundled roster of real LEGO sets the companion works toward, and the tier-unlock rules for choosing the next one. |
|
companion
Package companion derives the companion's presentation-facing state — mood, set progress, and the finished-set collection — from the event log.
|
Package companion derives the companion's presentation-facing state — mood, set progress, and the finished-set collection — from the event log. |
|
eventlog
Package eventlog defines tuigotchi's append-only event log: the single source of truth from which all companion, set, and watch state is derived.
|
Package eventlog defines tuigotchi's append-only event log: the single source of truth from which all companion, set, and watch state is derived. |
|
todo
Package todo is a small persisted to-do list.
|
Package todo is a small persisted to-do list. |
|
tui
Package tui renders tuigotchi: a root model routing between screens (to-do list, running watch, set menu, collection) with a continuously animated companion while a watch runs.
|
Package tui renders tuigotchi: a root model routing between screens (to-do list, running watch, set menu, collection) with a continuously animated companion while a watch runs. |
|
watch
Package watch owns the focus-watch domain: the pure watch-state reducer over the event log, and (in watch.go) the live engine that appends events.
|
Package watch owns the focus-watch domain: the pure watch-state reducer over the event log, and (in watch.go) the live engine that appends events. |