Colophon

A native Linux desktop (GTK4) statistics viewer for KOReader.

KOReader quietly tracks a surprising amount about how you read: per-page timing, per-book totals, whole session histories. The existing ways to look at that data are web dashboards and self-hosted Docker services. Colophon is neither. It is a local desktop app that reads a copy of your KOReader statistics database and turns it into a wide set of attractive, varied graphs and widgets. No server, no account, no cloud, and it never touches the live file on your device.

Status: v2.0.0. Ingestion, the app shell, the full widget catalogue, per-book sidecar reconciliation, eight themes, device auto-pull, and Meson + Flatpak packaging are all shipped. 2.0.0 replaced the GNOME design language with Colophon's own: libadwaita is gone, the look is flat, square, and hard-edged, and the whole stylesheet is generated by the app. See roadmap.md for what remains deferred.

What you get

The library. Import a copy of your statistics.sqlite3 and browse it. Short "junk" reads (plugin READMEs and the like) are filtered by default, and two files of one work group together without being merged.

The "All Books" overview. A scrolling dashboard of focused widgets:

• Totals (time, pages, books, active days, busiest day) over a 30 / 90 / 365 / all-time window, with a period-over-period trend against the previous equal window.
• Current and longest reading streaks.
• A GitHub-style year heatmap and a 7x24 "when do I read" heatmap.
• A reading-speed trend (pages/hour over time).
• Session analytics: length histogram, sessions per day, start-time patterns, records.
• Weekday and monthly distribution bars.
• A reading personality card: synthesised traits (chronotype, session style, weekly rhythm, author variety) read off your own behaviour.
• A records card (longest session, biggest day, most pages in a day) and a whole-history recap (books finished, completion rate, longest streak, most-active month).
• Series and author rollups, a finished-books timeline, and a gentle set-aside list of books you started and left for a month.

Per book. An honest positional progress bar (so a book read partly off the device does not look half-done), stat cards that reproduce KOReader's own math so the numbers match your device, an estimated finish date with a confidence, a recent-pace momentum read, a per-page activity strip that shows where your reading concentrated, and inferred read-through cards.

Bring your own files

Colophon only ever sees files you hand it, exactly as it does the statistics database. It does not scan or read anything on your device.

KOReader keeps each book's user-declared finished status and your highlights in a per-book .sdr sidecar next to the book. Give Colophon a book's sidecar from that book's page and it reads two things from it: the device's own finished / reading / abandoned verdict (which becomes authoritative over Colophon's position-based guess), and your highlights, notes, and bookmarks, drawn as markers at their true place on the activity strip. A book you have not provided a sidecar for simply keeps the inferred stats. The same principle governs anything Colophon might ever need beyond the stats database: if a statistic needs a file you have not given it, that statistic stays hidden until you do.

Themes

Eight palettes (Kanagawa Dragon, Wave, and Lotus; Gruvbox Dark and Light; Nord; Rosé Pine; Solarized Light) plus a Follow-system mode. One theme drives both the window chrome and the hand-drawn charts; switch it live in Preferences (Ctrl+comma). The default is Kanagawa Dragon, matching the rest of the Vir Invictus portfolio.

Local-first, always

• Reads a copy of statistics.sqlite3, opened strictly read-only. The live file on your device is never opened in place and never written to.
• No telemetry, no accounts, fully offline.
• No web UI, no Docker, no hosted service. That is the entire reason Colophon exists instead of the tools already out there.

Why "Colophon"

A colophon is the note printers historically placed at the end of a book, recording its production: press, date, paper, edition. It is the book's own record of how it was made. This app turns that idea toward reading instead of printing: the technical record of how a book was actually read.

Stack

Rust 2024, plain GTK4 (no libadwaita since 2.0.0), rusqlite (read-only opens only), and mlua (a sandboxed Lua VM for the .sdr sidecars). Charts are hand-drawn on cairo, no charting crate; the window chrome comes from an app-owned generated stylesheet, one definition per palette.

Follow-system dark/light reads org.freedesktop.portal.Settings over D-Bus, so a settings portal backend (xdg-desktop-portal-gtk, -hyprland, or GNOME's own) is the one runtime expectation outside GNOME; without one the app quietly defaults to its dark palette.

Building

From source with Cargo:

cargo build --release

Or the packaged desktop build with Meson (installs the binary, GSettings schema, desktop entry, AppStream metainfo, and icon):

meson setup build
meson install -C build

A Flatpak manifest (org.virinvictus.Colophon.json) builds it against the GNOME 49 runtime (which is where GTK4 ships; the app no longer uses libadwaita) with a read-only host sandbox.

License

MIT. See LICENSE.

Support

If Colophon's useful to you and you'd like to chip in:

bc1qkge6zr45tzqfwfmvma2ylumt6mg7wlwmhr05yv