CandyCodetime
Privacy-first coding-time tracker
Tracks edit-time per project / language to a local append-only JSONL file — or to an optional embedded SQLite backend via --backend=sqlite (no cloud, no database server either way) — and renders a SugarCharts-driven dashboard. Editor integrations can record heartbeats with the push CLI subcommand; the dashboard reads whichever backend you picked.
Install
composer require sugarcraft/candy-codetime
A signed single-file build ships with every release: download
candy-codetime.phar with its .sha256 (and
minisig) sidecars, verify the digest, and run
php candy-codetime.phar on stock PHP — the app never
rewrites its own archive and there is no self-update channel, so an
upgrade is a new download. Inside an archive --version
prints the release build stamp (the frozen vendor/ would
otherwise report the build root's dev guess), and
SOURCE_DATE_EPOCH keeps rebuilds of a tag byte-stable.
Quickstart
# Editor plugin / cron / git hook pushes a heartbeat:
vendor/bin/candy-codetime push sugarcraft php src/App.php 60
# Open the dashboard:
vendor/bin/candy-codetime
# Override the data dir:
CANDY_CODETIME_DIR=/var/data/codetime vendor/bin/candy-codetime
Formerly shipped as sugar-tick: two separate compat mechanisms
remain. Any SUGARTICK_* env export is imported under the
CANDY_CODETIME_* name on every launch (new name wins, each
import prints a deprecation notice on stderr). The one-time data-directory move
from ~/.local/share/sugar-tick runs on first launch only, and only
when CANDY_CODETIME_DIR is unset — an explicit directory
outranks the migration.
What's in the box
{time, project, language, file, duration, tags} — JSONL, one beat per line; tags is never set by the CLI; a plugin-written tag is honored on read and export.YYYY-MM-DD.jsonl per day — append-only, easy to ship to cold storage.Sparkline driven by one bucket per day, shown in minutes.← / → shift the 7-day window one day per press; r reloads.milestone add|list markers — sqlite-only, and the dashboard never shows them.Stats::compute is total-input deterministic — every dashboard test runs against fixed beats.Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by TakaTime (Go); SugarCraft is developed as a native PHP project.
Key Classes
| Class | Method | Description |
|---|---|---|
| Store | append(heartbeat) | Record one heartbeat (fail-loud, private file modes) |
| SqliteBackend | insert(heartbeat) | Record via the optional indexed backend |
| Stats | compute(heartbeats, from, to) | Pure fold of totals and day buckets |
| Heartbeat | __construct(time, project, language, file, duration) | Create a heartbeat |
| Dashboard | start(reader) | Load the window over any HeartbeatReader |
Demos.
VHS-recorded GIFs of the shipped demos. Regenerated automatically on every push that touches the source.