Quickstart

The quickest way in is from the terminal, inside the repository you work in. The CLI can see the two things a browser cannot — the repository's remote and the email your commits carry — so it can set them up and then prove they work.

1. Install the CLI and run init

npm install -g @blastin-dev/clocktopus-cli
cd path/to/your/repository
clocktopus init

The welcome screen a new account opens on starts with the same setup as one line, npm install -g @blastin-dev/clocktopus-cli && clocktopus init, and moves on to the dashboard once init finishes. It also offers the same setup in the browser, step by step.

init signs this machine in if it is not already, then walks through:

• You — your timezone and working hours.
• Organisation and project — if a teammate already attached the repository to a project, it says which and moves on. Otherwise it names an organisation and a project and attaches the repository.
• Repository — installs the GitHub App, or adds a webhook (Bitbucket always takes a webhook). See Connect a repository.
• Git email — if the email in your git config is neither your login nor a commit address, it offers to track it. Otherwise your commits arrive with nobody to attach them to.
• Agents — connects the coding agents installed on this machine.
• Verify — checks each part against what Clocktopus has actually received.

Every step can be skipped, and every question has a flag — see the CLI reference.

Restart your agents afterwards — the exporter and the hooks read their configuration once, at startup, so an open session picks up none of it.

2. Push something

init only says all set once a commit has arrived and been credited to you, and it offers to push an empty commit to check. Otherwise, push as you normally would. 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.

3. Correct the clock when you need to

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.

4. Set rates, if you bill

Hours become money through job roles. Open Settings → Job roles for the organisation in the sidebar switcher and give each role a sell rate and a cost rate; every member is assigned one role, on Settings → Members. Projects can then carry a budget, as one allocation per agreement, each with its own margin goal. See Rates and project budgets.

Without the CLI

The web app walks a new account through the same ground on the way in. To do it by hand later: in Settings → Projects, create a project and add the repository's URL; then connect the repository as described in Connect a repository; and add any other email your commits use under commit addresses. Agents can only be connected from the terminal, with clocktopus agent setup.

Check it is working

Where	What you should see
clocktopus init --skip you,project,repository,email,agents	Each lane checked against what Clocktopus received
Time screen	Entries for today, against the right project
Settings → Git connection	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