Minimal wakatime-style tracker - question about where heartbeat / idle / session logic lives #1255
Description
I am trying to build a small, intentionally minimal time-tracker inspired by WakaTime. The goal is a tiny tool that only records when a user is actively typing in an editor, the start and end times for a project session, and produces simple reports and metrics (daily/weekly/monthly totals and a lightweight dashboard). I want to avoid the extra complexity and features in the full wakatime stack and implement only the bare, correct logic for tracking active time and producing aggregated reports.
Before I start coding I want to make sure my understanding of how WakaTime handles "active" vs "idle" vs "session" is accurate, and I’d appreciate pointers to the exact parts of your codebase or documentation that implement these behaviors. I have not yet dug into the wakatime-cli source and would be very grateful for links or file references.
Specifically, can you help clarify these points?
Which component is considered the canonical place for deciding when to send a heartbeat and with what fields: the editor plugin, wakatime-cli, or the server?
Where is the idle timeout logic defined and enforced (the threshold used to decide that a gap between heartbeats means the user is idle)? Is that logic in the plugin, in wakatime-cli, or only on the server when building sessions and durations?
Where is the code that “joins” heartbeats into sessions or computes durations from heartbeats located? If there is a server-side implementation that merges heartbeats into durations, which repo/files should I inspect?
How do plugins normally invoke wakatime-cli (command line arguments, stdin, or other IPC)? Is there a documented minimal heartbeat format you recommend for a tiny tracker?
Are there any helper libraries in wakatime-cli for formatting metadata (language, project detection, branch) that you recommend reusing, or would you advise keeping those out of a minimal implementation?
If there are configuration knobs (idle timeout, granularity for joining heartbeats into durations, or report aggregation parameters), where are they documented and where do they live in code?
I may have described things in non-technical terms above; please correct any misunderstandings. If you can point me to exact files, functions, or docs to read (for example, the file path(s) in wakatime-cli or related repos that implement heartbeat handling, idle detection, and session building), that would save me a lot of time and help me design a minimal, compatible implementation.
Thank you for any guidance or links you can share.