Automatic tracking

Clocktopus does not watch you work. It measures the distance between the things you leave behind.

An entry is the gap between one piece of activity and the piece before it. That is the whole model — everything below is what happens when there is no piece before it, when it arrives late, or when it lands on a day you have already signed off.

How an entry is made

1. You push to a repository attached to a project.
2. The webhook delivers each commit, with its author time.
3. Each commit is measured against the previous piece of activity on your timeline, in your configured timezone.
4. The result is filed as an entry against the project that owns the repository.

Two commits at 10:00 and 11:30 produce one entry of 1h30m. A third at 14:00 produces another of 2h30m. Nothing is rounded and nothing is estimated.

Pull request reviews count too. Submitting a review is a timeline event exactly like a commit, which is the only way that work gets recorded at all.

A day with no activity is a day off. If you worked but pushed nothing, add the hours by hand.

Your work hours and the day

A day has to start somewhere. Where it starts depends on what Clocktopus knows.

Situation	Where the day starts
You clocked in	At your clock-in
An agent session opened the day	At the time that session started
Neither, and the first commit falls inside your work hours	Backfilled to your configured start time
Neither, and the first commit falls outside your work hours	At the commit itself — 0h, flagged

Your default work hours and timezone live in your preferences. They are not a rule about when you are allowed to work; they are the assumption used when nothing better is available.

Sunday afternoons, 6 AM starts and midnight pushes are ordinary work. Clocktopus does not flag or discount them. As long as something earlier exists to measure from, the hours are simply the gap.

Clock signals

If your hours are irregular, the assumption is wrong more often than it is right, and signals are how you replace it. They cost a few seconds and they go where you already are:

clocktopus clock in
clocktopus clock out

Backdate one you forgot:

clocktopus clock in --ago 45m
clocktopus clock in --at 08:15

The clock-in / clock-out button on the dashboard and in the Time screen header does the same thing.

Clocking in on a new day also closes any session you left open yesterday, so you can never end up with two running at once.

Signals matter most in two places: they give the day a real start instead of a backfilled one, and clocking out for a long break keeps that break out of the next entry.

Flagged entries

A flag is a statement about the measurement, not about you. It appears when Clocktopus could establish that you worked but not how long, or when a number it produced may overlap time already counted.

A flagged entry usually records 0 hours — not because the work took no time, but because its starting point is unknown. The commit still becomes the reference for everything after it, so the rest of the day measures normally.

No reference

A session had to open at the commit's own timestamp, because nothing earlier existed to measure from. Typically the first push of a day that nothing else opened, or a push after a long quiet stretch.

The fix: clock in — the CLI can backdate it — or edit the entry and give it a start time. Both replace a guess with something you know.

Out of order

A commit arrived whose timestamp falls before an entry already on your timesheet: a push delivered late, or work pushed from a second machine after the fact. The hours are still measured consistently, but the window they price may already have been counted, so the day's total can be inflated.

This is the one flag that can push a total up. The others leave time uncounted, which is recoverable. Reconcile this one before you invoice.

Force push

A force push arrived while your force-push preference was set to collapse. Rather than pricing rewritten commits as fresh work, Clocktopus records a single zero-duration summary entry. A rebase can replay fifty commits in a second, and counting them as work would invent hours that never happened. The commits are still kept for audit.

Retired flags

Outside work hours, Before clock-in and After clock-out are no longer emitted. Clocktopus used to flag work for happening at the wrong time; that judgement is gone. If you see one of these on an old entry, it is a historical record, not a fresh finding.

Edge cases

Commits do not always land neatly. These are the guardrails, and every entry they produce is still editable.

A commit lands after you clocked out. A fresh session opens at that commit. Its first entry records 0h and is flagged no reference; the ones after it measure normally.

Commits made before you clocked in. They measure from each other, not from a clock-in sitting in their future. Only the earliest records 0h. The first commit after the clock-in measures from the clock-in, so the gap outside the session is not billed twice.

A stretch crossing midnight. No entry may extend past midnight of the day it starts on. A duration that would spill over is capped at 23:59:59, so one entry can never occupy two calendar days.

A session left open overnight. The first webhook or clock-in the next day closes yesterday's session first — at your configured end time if the last activity was inside work hours, at the last activity time if it was after hours — then opens today's. Any unbooked time from that day is backfilled as a single tail entry.

Days in between with no activity. Treated as days off. Commit on Monday afternoon and again on Thursday morning, and Tuesday and Wednesday stay empty rather than absorbing three days of silence.

Cross-project work

All of your commits share one timeline, whichever project they belong to. The time between two commits is attributed to the project of the later one, so switching repositories mid-morning splits the morning between the two projects without any action from you.

This is also why single-tasking pays off here. The timeline cannot tell that you were doing two things at once; it can only see which repository you touched last.

Manual entries and edits

Every automated entry can be edited, and you can add entries by hand for work that leaves no git trace.

The Time screen has two views: a weekly grid, where you drop hours against a project for a given day, and a daily view for a detailed breakdown. Colleagues who do not commit code log their hours in the same place — manual for them, but the ledger stays in one piece.

Auto-lock past days

Once you have reviewed a week, a late or rebased commit should not quietly rewrite it.

Set a cutoff under Auto-lock past days in your preferences — 2, 7, 14 or 30 days, or off. It is a rolling window: with a 7-day cutoff, anything older than a week is locked, and the window slides forward each day.

When a commit lands on a locked day it is skipped: no entry is created or changed. The commit is still recorded in the activity log, so nothing is lost, and manual edits to a locked day are blocked too. To reopen recent days, raise the cutoff or switch it off.

Getting better data out of it

Clocktopus parses conventional commit scopes to pull the ticket out of a message, which is what lets reports break time down by ticket without an issue-tracker integration.

fix(bla-134): resolve signature verification files that time under BLA-134. Nothing else is required, and the same rule feeds the ticket rows in the AI agents report.