Quickstart

Everything below is optional except the first two steps. Those two are what make entries appear on their own.

1. Create a project and attach a repository

In Settings → Projects, create a project and add the URL of the repository you work in. Commits are only tracked for repositories attached to a project, and the project is what an entry gets filed against.

2. Point the repository at Clocktopus

Add a webhook so pushes reach Clocktopus. Both providers take a URL and a secret, and both are covered step by step in Connect a repository.

If the email in your git config differs from your Clocktopus login, add it under tracked emails — otherwise your commits arrive with nobody to attach them to.

3. Push something

Push a commit. Within a few seconds, an entry appears on the Time screen for today, filed against the project that owns the repository.

The first push of a day has nothing earlier to measure from, so it records 0h and is flagged. That is expected, and the next commit measures from it normally. Flagged entries explains why, and how to supply the missing start.

4. Install the CLI

npm install -g @blastin-dev/clocktopus-cli
clocktopus login

The CLI is how you correct the clock from where you already are:

clocktopus clock in --at 08:15
clocktopus clock out

If you keep regular hours you may never need it. If you do not, clocking in is what makes your day accurate rather than assumed. See the CLI reference.

5. Connect your AI agents

From a checkout of a repository attached to a project:

clocktopus agent setup

Then restart your agent — the exporter and the hooks read their configuration once, at startup, so an open session picks up none of it. This is the most common reason a correct setup appears to do nothing.

6. Set rates, if you bill

Hours become money through job roles. In Settings → Organisations, give each role a sell rate and a cost rate; every member is assigned one role. Projects can then carry a budget and a margin goal. See Rates and project budgets.

Check it is working

Where	What you should see
Time screen	Entries for today, against the right project
Settings → Git webhook	Recent deliveries, with no signature failures
clocktopus agent status	What the receiver has actually received from this machine
Reports → Summary → AI agents	Agent spend grouped by project