How automated time tracking works
Clocktopus tracks your development time by listening to your git commits. When you push code to GitHub or Bitbucket, we calculate the time you spent working and create time entries for you.
How it works
Supported providers
Time calculation rules
Clocktopus calculates the time between your commits using your configured timezone and work hours. It uses either your default working hours or signals as the reference.
Say you work 9am to 5pm most days. You don't need to do anything special, just keep committing. Your first commit of the day gets picked up automatically, and the system calculates hours from your configured start time.
But real life isn't always that neat. Maybe you had a dentist appointment, or you're running late after a chaotic school drop-off. That's where signals come in. They let you override the default hours so Clocktopus captures what actually happened.
Some companies are strict about arrival, lunch, and finish times. Others are flexible. If yours is the flexible kind, we recommend using signals to capture your actual hours. Either way, most of the time you just need to keep your code committed and let Clocktopus handle the rest.
If you don't push a single commit, Clocktopus treats it as a day off. You can always log hours manually through the web portal if you did work that day.
Same-day commits
Exact time difference between commits is recorded
Next-day commits
When Thursday's commit arrives, Monday's still-open session is auto-closed at 5 PM (your configured end time) and any unbooked time from Monday is backfilled as a single tail entry. Tuesday and Wednesday had no activity, so they're treated as days off. Thursday starts a fresh session at 9 AM (backfill) and the 10 AM commit records 1h.
Edge cases
Commits don't always land neatly inside your working hours. Clocktopus has a few guardrails that keep the timesheet honest even when things get messy. Every entry is still editable through the portal if you want to tweak it.
First commit of the day outside work hours. A 6 AM commit with no prior session anchors the new clock-in at the commit time itself (no backfill to 9 AM). The entry records 0h because there's no earlier reference to measure from — the session starts here and the next commit picks up from there. The entry is tagged NO_REFERENCE so you can spot it in the portal.
Commits after a clock-out. If you clocked out and then push another commit, Clocktopus opens a fresh session at the commit time. The first commit in that new session records 0h and carries the same NO_REFERENCE tag; subsequent commits in the new session measure from the previous one.
Out-of-order commits. Picture this: you write some code in the morning but forget to push. You carry on with other work, commit and push everything later, and that morning commit arrives after newer ones. Clocktopus still prices it against its chronological predecessor (so the math is internally consistent), but because a later entry already covered part of the same window, the total for the day is likely inflated. The entry is tagged OUT_OF_ORDER so you can review and reconcile it in the portal.
Long stretches crossing midnight. No entry is ever allowed to extend past midnight of the day it starts on. If the calculated duration would spill into the next day, it's capped at 23:59:59 so a single entry can never occupy two calendar days.
A session left open overnight. If you pushed commits yesterday and forgot to clock out, the first webhook (or manual clock-in) today auto-closes yesterday's session first — at your configured end time if the last activity was within work hours, or at the last activity time if it was after hours — then opens today's session. You can't end up with two open sessions at once.
Cross-project tracking
All your commits go into a single timeline, regardless of which project they belong to. Time between commits is attributed to the project of each commit.
Manual entries
Every automated entry can be edited, and you can add manual entries too. The web portal has two views: weekly, where you drop hours against a project for any given day, and daily, for a more detailed breakdown.
Other collaborators on your team can log their hours through the same portal. It's manual for them, but it keeps everything in one place.
Mindset
Keep it committed. It's simple, and you probably already do it. The more commits you make, the more data points Clocktopus has to work with, and the better the time estimates get.
We recommend using conventional commits to format your messages. Clocktopus can parse structured commit messages and pull out things like time spent on ticket ABC-123. This is where it stops being just a developer tool. It gives the company accurate, real-time data on where time actually goes. That kind of visibility is hard to get any other way.
Signals
Signals add a small overhead, but if you don't have regular hours, there's no way around it. You have to tell the system when your day starts and ends. We made this as painless as possible by putting it right where you already are: the terminal.
Clocking in on a new day also auto-closes any open session you left behind from the previous day, so you never end up with two sessions running at once.
Clock in and out via CLI
clocktopus clock [in|out]Or use the clock-in / clock-out button on the dashboard or the Time page header — same behaviour.