# Color Timer Clock

- Link: https://blog.curbsoftware.com/project/color-timer-clock/
- Published: 2026-11-01T12:27:29+00:00
- Author: curbsoftware

# Color Timer Clock

A Cinnamon desklet with three cards (**Clock**, **Timer** and **Chronometer**) whose
background colors follow a schedule you define. Each card’s color ramps between (
time, color) stops: the clock by time of day wrapping over midnight, the timer by
time remaining, the chronometer by time elapsed.

On the desktop:

The settings window:

## Why this exists

The color is not decoration. It’s the signal. Each card has a job:

 * The **clock** shows when AI providers run their low-traffic discounts. Set the
   color stops to match the window, and you know at a glance when it’s cheap to 
   run.
 * The **timer** counts down to credit resets, so I know when my API credits come
   back.
 * The **chronometer** runs sprints. Most of the work happens in the last stretch
   before a deadline, so the color tells me where I am in the sprint: green for 
   the first half hour, amber sliding to red over the next hour and a half, blue
   once two hours are up. Blue means take a break.

One glance tells me the state of things. That’s the whole idea.

## Features

 * Up to three responsive cards. Narrow widths wrap cards onto centered rows and
   add enough height instead of hiding or clipping cards
 * Per-card color schedules with smooth (interpolated) or stepped transitions
 * Clock card with an optional IANA timezone
 * Timer with on-card play/pause, reset and hour/minute/second buttons under Ready;
   survives restarts and expires correctly even after downtime
 * Optional desktop notification when the timer finishes
 * Optional notifications when the clock or chronometer reaches a schedule stop
 * Chronometer with pause/resume and a Lap button on the card; the accumulated time
   survives restarts, and an optional hundredths display (20 updates/s while running)
 * Text and border colors adapt to the card background for readability (WCAG contrast
   ratio)
 * Keyboard focus, pressed states, accessible names and tooltips on every card control
 * One **Reload color schedules** desklet menu action that does not interrupt a 
   running timer or chronometer
 * A footer clock on each card (`HH:MM:SS` until the next colour, with a 28 px colour
   sample that carries the go-next icon). Hide it from Display settings; timer and
   chronometer play/reset stay
 * A clear setup message when every card is disabled
 * One-click “Reset all schedules to defaults”

## Configuration

Right-click the desklet and choose **Configure**.

 * **Color schedules**: a list of (time, color) stops per card. Colors are hex (`#
   rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) or a name such as `red` or `blue`. Duplicate
   times keep the last row; invalid rows are dropped with a log line
 * **Smooth color transitions**: blend gradually between stops, or hold each color
   and jump at the next stop
 * **Show a notification when the timer finishes**: pops a desktop notification 
   when the countdown reaches zero
 * **Notify (per schedule row)**: tick a clock or chronometer schedule row’s Notify
   checkbox to pop a notification when that time is reached
 * **Timer minutes / seconds**: the default duration the timer restarts from
 * **Reload color schedules**: the desklet menu action reloads all three schedules
   without restarting a running timer or chronometer
 * **Show next color countdown**: footer clock until the next scheduled colour, 
   with a colour sample. Timer and chronometer controls stay visible either way
 * **Show hundredths of a second**: adds a `.ss` fraction to the chronometer while
   it runs
 * **Time / date format**: `strftime` patterns for the clock card
 * **Maximum font sizes, card spacing, desklet width / height**: cards shrink text
   to fit

## Manual install

No root needed. Everything installs into your home directory.

From a release package:

    ```bash
    curl -fLO https://github.com/CurbSoftware/cinnamon-color-timer-clock-desklet/releases/latest/download/cinnamon-color-timer-clock-desklet.zip
    unzip -o cinnamon-color-timer-clock-desklet.zip
    mkdir -p ~/.local/share/cinnamon/desklets
    rm -rf ~/.local/share/cinnamon/desklets/cinnamon-color-timer-clock-desklet@curbsoftware
    cp -r cinnamon-color-timer-clock-desklet@curbsoftware/files/cinnamon-color-timer-clock-desklet@curbsoftware \
       ~/.local/share/cinnamon/desklets/cinnamon-color-timer-clock-desklet@curbsoftware
    ```

Or straight from git:

    ```bash
    git clone https://github.com/CurbSoftware/cinnamon-color-timer-clock-desklet.git || git -C cinnamon-color-timer-clock-desklet pull
    cd cinnamon-color-timer-clock-desklet
    mkdir -p ~/.local/share/cinnamon/desklets
    rm -rf ~/.local/share/cinnamon/desklets/cinnamon-color-timer-clock-desklet@curbsoftware
    cp -r files/cinnamon-color-timer-clock-desklet@curbsoftware \
       ~/.local/share/cinnamon/desklets/cinnamon-color-timer-clock-desklet@curbsoftware
    ```

The `rm -rf` before the copy is the upgrade path: old files are removed so
 nothing
deleted upstream lingers, then the copy brings the new tree in. Your settings and
running timer state are stored separately in `~/.config/cinnamon/spices/cinnamon-
color-timer-clock-desklet@curbsoftware/` and survive reinstalls.

Restart Cinnamon (**Alt-F2**, type `r`, Enter) and add the desklet from
 Cinnamon
Settings.

## Notes

Colors interpolate piecewise-linearly in RGB, so a red to blue ramp passes through
purple. The clock schedule wraps over midnight; timer and chronometer schedules 
hold the last stop’s color beyond it. Cards share the desklet width and wrap onto
more rows when each card would otherwise become too narrow. Enabled cards never 
disappear because of desklet width.

UUID: `cinnamon-color-timer-clock-desklet@curbsoftware`

## License

GNU General Public License v2.0 or later. See [LICENSE](https://blog.curbsoftware.com/project/color-timer-clock/LICENSE).
