timeglance

Config-driven time planning at a glance - one web UI controls two planners:

• Weekly - your routine sheet with topic layers. Print it or set it as a desktop wallpaper.
• Year - a wide year-at-a-glance planner, with layers fed by your own calendars, public holidays, and manually added events. Print it or set it as a desktop wallpaper.

One web control panel drives both - preview live, toggle layers, edit the YAML, export, or set the wallpaper:

...and the rendered output you print or set as a wallpaper:

Try it instantly (Docker)

The zero-install way to see the control panel and renders - a test drive, not a deployment target. A container can't reach your desktop session, so Docker can never set the wallpaper (the UI auto-hides it, and a scheduled "set wallpaper" renders the file but skips the set). Bridging the host display/DBus into a container isn't something we intend to solve - to actually use timeglance on your desktop, install it locally (next section).

docker compose run --rm timeglance timeglance init   # first run: scaffold year/ + weekly/ config.yaml
docker compose up                                    # then open http://localhost:8753

Config, outputs and scheduler state are bind-mounted under ./year, ./weekly and ./state, so the UI edits files on your host. Outputs are written as your host user — the compose file defaults to 1000:1000 (the usual first Linux user), so it just works for most; if your uid differs, run UID=$(id -u) GID=$(id -g) docker compose up.

Install (Ubuntu/Debian)

The simplest way on a Debian-based desktop. Grab the .deb from the latest release and install it - apt pulls the native libraries (Cairo, Pango, GDK-PixBuf, fonts) for you:

sudo apt install ./timeglance_<version>_amd64.deb

That puts timeglance on your PATH - a self-contained install under /opt/timeglance using the system Python. Scaffold the configs and open the panel:

timeglance init     # scaffold year/ + weekly/ config.yaml from the templates
timeglance serve    # the control panel at http://localhost:8753

Built for Ubuntu 24.04 / Debian 13 (Python 3.12); remove with sudo apt remove timeglance.

Install (Python/uv)

Needs Python 3.12+ and uv. WeasyPrint and CairoSVG load native libraries (Cairo, Pango, GDK-PixBuf) at runtime; most Linux desktops already have these, but on a minimal or server install add them first (Debian/Ubuntu):

sudo apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0
uv sync
uv run timeglance init      # scaffold year/ + weekly/ config.yaml from the templates
uv run timeglance serve     # the control panel at http://localhost:8753

Config, state and rendered output live under the XDG base directories by default (~/.config/timeglance, ~/.local/state/timeglance, ~/.local/share/timeglance); set TIMEGLANCE_HOME=$PWD to keep it all in the current folder instead.

Headless renders (each flag has a YAML equivalent):

uv run timeglance render year --theme light --layout vertical   # render the year planner
uv run timeglance render weekly --format both                   # render the weekly sheet

Set and forget (systemd timer)

To re-render (and optionally re-wallpaper) on a schedule with nothing running and nothing to start after a reboot:

timeglance install              # write a user service + timer and enable it now
timeglance install --time 06:30 # or pick the time (default: schedule.yaml's)
timeglance uninstall            # remove it

(From a source checkout, prefix these with uv run.) This drops timeglance-render.service (a oneshot that runs timeglance run, honouring your schedule.yaml) and timeglance-render.timer into ~/.config/systemd/user/, then enables the timer. Persistent=true means a run missed while the machine was off happens on the next boot. Change the time by re-running timeglance install --time HH:MM.

Setting the Plasma wallpaper needs an active graphical session, so a render while you're fully logged out writes the files but can't paint - it repaints on your next session. For renders while logged out (no wallpaper), enable lingering: loginctl enable-linger $USER.

Tray controller (optional)

A system-tray menu to open the panel and flip the schedule - a launcher and quick toggles, not the scheduler (the timer above keeps running whether or not the tray is open).

The tray isn't in the .deb: its KDE backend needs the system AppIndicator/GObject libraries, so install it with pipx (allowed to see system packages):

sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1
pipx install --system-site-packages 'timeglance[tray]'
timeglance tray

(From a source checkout it's uv sync --extra tray then uv run timeglance tray, but on Plasma the icon may not appear without the system libraries above.)

The menu opens the control panel (starting the server first if needed), starts/stops it, picks the port, and toggles the schedule: enabled, time, which planners render, and which set the wallpaper. Autostart adds an XDG autostart entry so the tray is there every session (the same thing KDE's System Settings → Autostart manages). Quitting the tray only closes the panel it started - the systemd timer keeps running regardless.

Docs

• Motivation - why this exists, and how it fits a GTD/calendar setup
• The control panel - preview, config editor, scheduler & activity log
• Configuration - year & weekly YAML, calendar (.ics) sources
• Reference - every CLI flag and YAML key
• Wallpaper - KDE Plasma, per-screen native-resolution rendering
• Use as a library - import and render PNG/PDF/SVG from Python
• Contributing - setup, CI, releasing

Limitations

• Wallpaper-setting is host-only. The container can't reach a Plasma session, so inside Docker the feature self-hides and a scheduled "set wallpaper" renders the files but skips the set (logged as wallpaper skipped (no backend)). Run the server/CLI on the host to set wallpapers.
• Weekly activities can't overlap in time. Two activities over the same slot on the same day render on top of each other, so only one reads clearly.