event-tracker/CLAUDE.md

CLAUDE.md

Context for future Claude sessions working on this repo.

Current status (2026-08-22)

• Desktop app (event_tracker.py) is feature-complete and working on the user's machine: record buttons, stats popup, settings popup, reset, relocatable data path, taskbar icon, "Time Since" column.
• Repo is pushed to repo.tas-tech.net/tas-tech.net/event-tracker (private — will go public once there's a tagged release).
• Android build (android/) is in progress. Native recipe compilation (SDL2, OpenSSL, sqlite3, pyjnius, hostpython3) succeeds. The last blocker was a p4a upstream bug in the kivy recipe's python_depends — see "Android companion — design decisions" below for the fix (android/p4a-recipes/kivy). Not yet confirmed working end-to-end — next session should check whether the user has run ./build.sh android debug since that fix landed and, if not, ask for the latest log tail before touching anything else Android-related.
• Outstanding, agreed but not implemented: split config.json into two files — event list (safe to sync between machines) vs. data file path (must stay local per-device, same principle as the Android app's own config). User explicitly agreed to this; it just hasn't been built yet. Don't re-ask, just do it when picking this up.
• Outstanding: LICENSE file. User has decided on GPL-3.0 (want to give simple apps away free via F-Droid/Aurora, charge for the same thing on Play Store — GPL permits charging for build/distribution, doesn't force pricing). Not yet added as a file; add it before the first public/tagged release if nobody's done it by then.
• Standing rule, unchanged: never git push without asking the user first, even though this repo now has a remote and history — treat every future push as needing fresh confirmation, not a standing yes.

What this is

Single-file GTK3 + matplotlib desktop app (event_tracker.py, despite the filename it's now multi-event and the event list is user editable). One button per entry in self.events records a timestamp to a CSV file; the main window shows a total/avg-hour/avg-day row per event and a line graph of today's counts by hour. A stats popup adds streaks/trends and by-hour/week/month charts; a settings popup renames or adds events and relocates the data file.

Design decisions

• CSV, not sqlite — dataset is tiny (a handful of rows/day), and a flat file lets the user hand-edit a bad entry without tooling.
• No inline magic numbers — all environment-specific values (DEFAULT_EVENTS, COLOR_PALETTE, DEFAULT_DATA_PATH, CONFIG_PATH, WEEKLY_WEEKS, MONTHLY_MONTHS, TIMESTAMP_FORMAT) live in a config block at the top of the file. Change those, not the logic below.
• GTK3 over Tkinter/Qt — native widget set on the target desktop (EndeavourOS/GNOME-ish), no pip-installed GUI runtime to drag around.
• Malformed CSV rows are skipped, not fatal — load_entries() tolerates a hand-edited file rather than crashing the app on startup.
• One CSV, event + timestamp columns — chosen over one file per event so stats/graph code doesn't duplicate per event. ensure_csv() auto-migrates the original single-column format on first run (existing rows relabelled to the first configured event).
• Reset backs up, never deletes outright — reset_log() copies the current CSV to a timestamped .bak-* file before truncating. The confirmation dialog in TrackerWindow.on_reset is the only path to this, and always warns before calling it.
• Integer y-axis ticks — MaxNLocator(integer=True) on every graph; event counts are always whole numbers, so fractional ticks (e.g. 0.2) would be misleading.
• compute_stats()/weekly_counts()/monthly_counts()/format_elapsed() are pure — take a sorted list of datetimes (or a timedelta) for one event, return plain dicts/tuples/strings, no GTK/matplotlib references. Keeps the date math testable without a display.
• "Time Since" ticks live, not just on action — GLib.timeout_add_seconds(60, ...) in TrackerWindow.__init__ calls refresh() every 60s so the elapsed time keeps counting up without a new event or button click. This is the one thing in the UI that changes purely with wall-clock time.
• Event list is config, not data — stored separately in config.json (via load_config()/save_config()), not in the CSV. self.events on TrackerWindow is the live, mutable copy; renaming in Settings calls rename_event_in_csv() so historical rows follow the rename rather than becoming orphaned. Colors are derived from an event's position in the list (event_color()), not stored per-event, so there's nothing to keep in sync when the list changes.
• Data file location is also config, and is itself relocatable — every CSV function (ensure_csv, load_entries, append_entry, rename_event_in_csv, reset_log) takes csv_path as an explicit argument rather than reading a module constant, because it can change at runtime via Settings. self.data_path on TrackerWindow is the live value; CONFIG_PATH itself (where that value is recorded) stays fixed — it's a small pointer file, not the user's data, so it isn't exposed as something to relocate. move_data_file() backs up whatever's already at a destination before overwriting it, same belt-and-suspenders approach as reset_log().
• Widget rebuild over dynamic-only display — rebuild_event_widgets() destroys and recreates the record buttons and stats-grid rows when the event list changes, rather than trying to diff them. Simpler and this only runs on an explicit Settings save, not per-frame.
• App icon requires both a window icon and WM_CLASS matching — GTK's window icon alone isn't enough for KDE/GNOME taskbars to pick the right icon; without a WM_CLASS matching the .desktop file's StartupWMClass, the taskbar can fall back to an unrelated running app's icon. main() calls GLib.set_prgname(WM_CLASS) before creating any window, and WM_CLASS must stay identical to StartupWMClass in event-tracker.desktop.in.
• Icon is PNG, not SVG, on purpose — event-tracker.svg still ships (source of truth for the design, regenerate the PNG from it if the icon changes), but ICON_FILE points at event-tracker.png and the .desktop file's Icon= does too. SVG decoding depends on the system's gdk-pixbuf loader modules (librsvg's loader specifically), which isn't guaranteed present/registered even when librsvg itself is installed — confirmed missing on the dev machine via gdk-pixbuf-query-loaders | grep svg returning nothing despite librsvg being installed. PNG decoding is core gdk-pixbuf, no optional loader involved, so it isn't a system-dependent single point of failure. Both files are loaded by absolute path — no icon-theme install/cache-refresh step required either way.

Repo layout

event_tracker.py           # the desktop GTK app
event-tracker.desktop.in   # launcher template (no machine-specific path baked in)
install-launcher.sh        # generates event-tracker.desktop for this clone's actual path and installs it
event-tracker.svg          # icon source (edit this if the design changes)
event-tracker.png          # icon actually referenced by the app + launcher, regenerate from the .svg
README.md                  # install/run instructions for the desktop app
CLAUDE.md                  # this file
android/
  main.py                  # minimal Kivy touchscreen app, v1 — see its own README for scope
  buildozer.spec           # Android build config
  README.md                # build/install/permission instructions specific to Android
  setup-build-env.sh       # creates the isolated venv for buildozer/cython
  build.sh                 # runs buildozer through that venv (sets PATH + VIRTUAL_ENV by hand)
  p4a-recipes/kivy/        # local override of p4a's built-in kivy recipe — see design decisions below

Android companion — design decisions

• Same CSV format, deliberately zero coupling otherwise — the Android app only knows the event,timestamp column format and TIMESTAMP_FORMAT; it has no code path that talks to the desktop app or assumes anything about it. The two apps stay in sync purely because they read/write the same file, which some third-party sync tool (FolderSync/DAVx5) mirrors between devices — that sync is out of scope for both apps and is the user's own infrastructure.
• v1 is intentionally thin (record buttons, today's totals, one bar) — Android build tooling (buildozer/SDK/NDK) is the actual risk on a first build, not app logic. Shipping the smallest thing that proves the pipeline works, before porting the stats popup / settings / rename / charts from the desktop app, was a deliberate choice — see android/README.md.
• No matplotlib on Android — unreliable through Kivy's garden packaging. BarRow in main.py hand-draws a proportional bar with Kivy's own Color/Rectangle canvas primitives instead.
• Config path is local-only, same principle as desktop's CONFIG_PATH — each device's app-private storage holds only that device's CSV path; it is never itself synced. Only the CSV — the actual data — goes through the user's sync tool.
• MANAGE_EXTERNAL_STORAGE permission — the CSV can live in an arbitrary user-chosen folder (wherever the sync tool puts it), so scoped storage / SAF alone isn't enough; broad file access is required and must additionally be granted manually in Android settings post-install (see android/README.md step 5) — Android doesn't allow silently requesting this one like the legacy permissions.
• The APK is built by the user, on their own machine — this was never attempted in the cloud sandbox that authored the code: no reliable way to fetch a multi-GB Android SDK/NDK there, and "run buildozer android debug on your own box" is the correct place for this regardless.
• Known gap, not silently glossed over: whole-file sync tools don't merge concurrent CSV writes from two devices — logging on both within the same sync window risks a conflicted duplicate file rather than merged rows. Documented in android/README.md, not solved in code.
• Build tooling lives in a venv, never --break-system-packages — setup-build-env.sh creates a plain python3 -m venv (no --system-site-packages — that was tried and reverted, see next point) at android/build/venv and installs buildozer/cython into it. build.sh runs buildozer by absolute path rather than source-ing the venv, so it manually replicates the two things activation would do: puts venv/bin on PATH (buildozer shells out to find cython) and sets VIRTUAL_ENV (buildozer's own targets/android.py checks this env var to decide whether its bootstrap pip install needs --user; without it, it wrongly assumes it's not in a venv, uses --user, and pip refuses since there's no user site-packages inside an isolated venv).
• p4a-recipes/kivy — local override, not a workaround — p4a's own built-in kivy recipe declares python_depends = ['certifi', 'chardet', 'idna', 'requests', 'urllib3', 'filetype'] (for kivy.network.UrlRequest, which this app never calls). requests transitively needs charset-normalizer, whose newest release is the first to ship a prebuilt Android-tagged wheel (new, tied to CPython 3.14's official Android build target). p4a's own dependency resolver (process_python_modules in pythonforandroid/build.py) finds that wheel correctly during its pip --dry-run --platform=android_24_arm64_v8a pass and pins the exact URL into a generated requirements.txt — but the next stage (run_pymodules_install) installs from that file with a plain host pip and no --platform override, so it rejects its own pinned wheel as "not a supported wheel on this platform." That's a real upstream p4a bug, confirmed by reading pythonforandroid/build.py directly (not guessed) — and python_depends isn't something buildozer.spec can override, so p4a-recipes/kivy/__init__.py is a full copy of the upstream recipe (patches included) with just python_depends = []. buildozer.spec points at it via p4a.local_recipes = p4a-recipes. If a future Kivy release actually needs one of those network extras, re-diff against p4a's current pythonforandroid/recipes/kivy/__init__.py before blindly re-adding them.
• Previously-tried and reverted: --system-site-packages on the build venv. It fixed the --user/pip-in-venv error above, but leaked the real system Python's installed packages into what p4a decided the app needed to bundle (confirmed via pip show requests showing a system-wide install), which is a worse, harder-to-diagnose failure mode than the one it fixed. Don't reintroduce it as a quick fix for a future build error without checking whether it's actually leaking something first.

Conventions for changes

• Keep the desktop app single-file unless it grows enough to justify splitting (e.g. a separate stats module) — ask before restructuring.
• Any new tunable value goes in the config block at the top of whichever file it belongs to, never buried in a function body.
• Keep the CSV format (event,timestamp, TIMESTAMP_FORMAT) identical across event_tracker.py and android/main.py — changing one without the other breaks cross-device sync silently.
• Git remote is repo.tas-tech.net (Forgejo), auth via ~/.netrc, user AI_Assistant — never push without asking the user first.