README

CandyCodetime

Formerly published as sugarcraft/sugar-tick (renamed 2026-10). Namespace changed: SugarCraft\Tick\ → SugarCraft\CodeTime\.

candy-codetime — a privacy-first coding-time tracker for PHP 8.3+. Storage is JSONL on local disk (no cloud, no database server), the dashboard is a SugarCharts-driven TUI that reads it.

Run it

# write a heartbeat from your editor (one-shot CLI):
candy-codetime push <project> <language> <file> [duration]

# open the dashboard:
candy-codetime

By default heartbeats land in $XDG_DATA_HOME/candy-codetime (or ~/.local/share/candy-codetime). Override with CANDY_CODETIME_DIR=....

Keys (dashboard)

Key	Action
`←`	Shift the 7-day window back
`→`	Shift forward (to today)
`r`	Reload from disk
`q` / `Esc`	Quit

Architecture

File	Role
`Heartbeat`	Value object — one activity sample (project, language, file, duration).
`Store`	JSONL-backed reader / appender. One file per day under the data dir.
`Stats`	Pure folder — totals per project / language + per-day timeline buckets.
`Dashboard`	SugarCraft Model — renders the report, ←/→ shifts the window, r reloads.
`Renderer`	View — header + ranking panes side-by-side + Sparkline timeline (SugarCharts).

The Store is intentionally append-only at the file level, so editor plug-ins can >> echo a JSON line directly without coordinating with the dashboard. The dashboard reads at r / on launch / when the day shifts — never holds a file lock.

Shared foundations

candy-codetime uses sugar-async for cancellation support in async write operations.

Test

composer install
vendor/bin/phpunit

Credits & inspiration

Design antecedent: Rtarun3606k/TakaTime; SugarCraft is developed as a native PHP project.

sugarcraft / candy-codetime

Package info

Security

Statistics