claudoro CLAUDE.md

Claudoro

A Pomodoro timer that lives inside the Claude Code terminal: a live, ticking countdown in the status line plus a render-decoupled end-of-block alarm. Open source, distributed as npm install -g claudoro with a thin Claude Code plugin wrapper.

Read first: specs/spec.md (architecture, modules, data model, acceptance tests) and specs/decisions.md (D-001..D-012, the authoritative rationale). The spec supersedes specs/charter.md where they disagree. When in doubt, the decisions log wins.

Core principle

The code must always be robust, flexible, and elegant.

One architectural truth underpins everything (D-001): the pomo CLI is the single source of truth. It owns all state, scheduling, and history. The status line, the /pomo command, and the alarm are thin surfaces over it. The CLI runs with zero model involvement, so the core feature never costs API tokens.

A second truth makes mutation safe (D-007): derive, do not store, aggregates. Counts, cycle position, focus minutes, and streaks are folded from immutable records on read. There are no mutable counters, so undo/restore are correct by construction.

How we write code

Functional-first, composition over cleverness. Favour small, pure, well-named functions composed into larger behaviour. Avoid complex code; if a function is hard to name or test, split it.

• Pure core, impure edges. Keep logic (timer math, derivation, rendering, formatting) as pure functions of their inputs. Push side effects (file I/O, flock, spawn, clock, stdout) to a thin boundary layer. A function reads the clock once and passes now down; it does not call Date.now() deep in a fold.
• Compose, don't branch-pile. Build a verb from discrete subfunctions (resolvePaths → readState → mutate → writeAtomic), not one long procedure. Prefer map/filter/reduce and data transformation over imperative mutation.
• Data in, data out. Functions take plain values and return plain values. Immutable updates ({...state, run_state: 'paused'}), no in-place mutation of shared objects.
• Total functions. Handle the empty/missing/corrupt case in the function, not at the call site. Missing state → idle; corrupt JSON → quarantine + reinit; never throw on the render path.
• Explicit over implicit. No hidden globals, no ambient singletons. Dependencies (paths, clock, fs) are passed in, which also makes them trivially mockable in tests.
• Small modules with one job, mirroring the spec's M1..M10. A file should fit in your head.