CLI

The terminal side of Clocktopus. It signs this machine in, corrects the clock when a day needs it, and connects your AI coding agents — the last of which can only be set up from here.

Install

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

Sign in

clocktopus login

The CLI uses the OAuth 2.0 device flow. It prints a URL and a code:

Starting device authorization...

Open this link to authorize:

  https://clocktopus.app/auth/device?user_code=ABCD1234

Or visit https://clocktopus.app/auth/device and enter code: ABCD-1234

Waiting for authorization...

Open the link, approve it, and the CLI picks it up on its own:

Waiting for authorization.....
Logged in as John Doe ([email protected])

The token is stored in your system's configuration directory. You log in once per device.

Command	What it does
clocktopus login	Authorise this machine
clocktopus logout	Clear stored credentials from this device
clocktopus whoami	Show who this machine is signed in as

Set up a checkout

clocktopus init

Run it inside a checkout of the repository you work in; anywhere else it stops before doing anything. It signs you in first if this machine is not, then walks through each step, every one of which you can confirm or skip. Ctrl-C at any question stops init, keeping the steps already done:

Step	What it does
You	Saves your timezone (this machine's by default) and working hours
Organisation and project	If the repository already belongs to a project in one of your organisations, says which and creates nothing. Otherwise picks or creates the organisation and attaches the repository to a project you manage, or to a new one
Repository	For GitHub, installs the GitHub App and waits until it covers the repository. Press m to add a webhook instead, which gh can create for you. Bitbucket gets the URL and secret to add by hand
Git email	Compares the checkout's git config user.email with your sign-in email and commit addresses, and offers to track it or to set a different one for this repository only
Agents	Runs agent setup for the coding agents installed here
Verify	Reports the project, author, commits, pull requests and agents from what Clocktopus has actually received

It only says all set once a commit from the repository has arrived and been credited to you. Until then it offers to make an empty commit and push it, waits for the delivery, and prints the fix for whatever comes back: a wrong secret, a locked day, or a commit whose author email is not yours. It skips the commit when your branch is behind origin, and removes it again if the push fails.

After a GitHub webhook is added, by gh or by hand, init waits for the ping GitHub sends the moment it is saved, and reports the repository or organisation it was seen on, any of Pushes, Pull requests and Pull request reviews it leaves unticked, or a secret that does not match. It waits two minutes, or ten off a terminal where nobody presses Enter once the webhook is saved. Bitbucket sends no ping, so its webhook is proven by the first push.

When the GitHub App and a repository webhook both deliver the same repository, each push arrives twice; with gh installed, init offers to delete your webhook.

Every question has a flag, so init also runs unattended:

Option	Description
-y, --yes	Take every default without asking
--skip <steps>	Skip you, project, repository, email, agents or verify
--only <steps>	Run only the steps named, as in --only verify --test-push
--timezone <tz>	Your timezone, such as Europe/Lisbon
--hours <start-end>	Your usual day: 9-17 or 08:30-17:00
--working-hours / --no-working-hours	Whether you work set hours
--organization <name>	Use this organisation (id, slug or name)
--new-organization <name>	Create an organisation with this name
--project <name> / --new-project <name>	Attach the repository to this project, or create one
--connect <how>	app, gh, manual or skip
--track-email / --no-track-email	Whether to track this checkout's git email
-a, --agent <ids>	Configure only these agents
-c, --component <names>	Install only these besides telemetry and hooks
--test-push	Push an empty commit to the current branch to verify delivery
--delete-old-hook	Delete your repository webhook when the GitHub App also delivers

Without a terminal, or with --yes, nothing is installed, pushed or deleted unless its flag says so.

Clock in and out

clocktopus clock (in|out) [--ago <duration> | --at <time>]

Records the start or end of a work session. Defaults to now.

Option	Description
--ago <duration>	Backdate by a duration from now: 15m, 1h, 1h30m. Cannot be combined with --at
--at <time>	Backdate to a wall-clock time today: HH:mm or HH:mm:ss

clocktopus clock status [-d <YYYY-MM-DD>]

Shows the clock signals for a date, defaulting to today.

What the signals actually change is covered in clock signals.

Agent telemetry

Records what your AI coding agents cost, so the cost of a piece of work is human time × rate plus agent spend. AI agents covers what is recorded and what is never collected.

clocktopus agent setup

clocktopus agent setup [--name <label>] [--force] [-a <ids>] [-c <components>]

Mints an ingest token for this machine, configures the agents you choose, installs the session hooks, and confirms the receiver accepts the token before reporting success.

In a terminal it asks two questions, each a checklist (arrow keys to move, space to toggle, enter to confirm): which agents to set up, with the ones installed on this machine already ticked, and which of the MCP server and the skills to install, both ticked. Telemetry and the session hooks are always installed: the hook is what tells Clocktopus which repository a session worked in. Anything you leave unticked is left as it is in the agent's configuration. --agent and --component answer the questions up front, and a non-interactive shell installs everything into every agent it finds.

Unless you untick them, it also installs the four agent skills and the MCP server they use. create-task notes a task for later in one line. start-work carries a task through to an open pull request, on a branch named after it, or works through a goal's tasks as stacked pull requests. refine gets a task, or a whole goal, ready for an agent to work without asking, applying only what you confirm. create-goal drafts a goal and the tasks its outcome needs, for you to confirm once. They create tasks in Clocktopus, unless your repository's agent instructions say to create them in Linear or Jira. A small SessionStart hook tells each Claude Code, Codex and Cursor session whether its branch carries a task. How they arrive depends on the agent:

Agent	Skills	MCP server	Sign in once with
Claude Code	the Clocktopus plugin	the plugin	/mcp in Claude Code
Codex CLI	~/.agents/skills/clocktopus-create-task, clocktopus-start-work, clocktopus-refine, clocktopus-create-goal	[mcp_servers.clocktopus] in ~/.codex/config.toml	codex mcp login clocktopus
OpenCode	the same four folders	mcp.clocktopus in opencode.json	opencode mcp auth clocktopus
Cursor	the same four folders	mcpServers.clocktopus in ~/.cursor/mcp.json	Cursor Settings → MCP

Cursor reports sessions through its hooks only: Clocktopus records when they ran, where, their commits, their task and the session duration Cursor reports, but not their tokens or cost. See AI agents.

Updating the CLI and re-running agent setup updates them. Cost tracking never depends on them: disabling the plugin or removing the skills leaves telemetry and hooks reporting.

Run it from a checkout of the repository you work in — it also checks that repository is attached to a project, since spend from an unattached repo lands in the unattributed row rather than against a client.

Option	Description
--name <label>	Label for this machine's token. Defaults to the hostname. Keep it recognisable, since revocation is per token
--force	Mint a replacement token instead of reusing the one already installed
-a, --agent <ids>	Configure only these agents: claude, codex, opencode, cursor. Repeatable or comma-separated
-c, --component <names>	Install only these besides telemetry and hooks: mcp, skills, or none. Repeatable or comma-separated

Re-running without --force is safe and idempotent. Restart your agent afterwards — the exporter and the hooks read their configuration once, at startup, so an open session picks up none of it. On Codex, also approve the hooks trust prompt in its own interface, or telemetry arrives without any repository context.

clocktopus agent status

Shows what the receiver has actually received, not what this machine believes it sent.

clocktopus agent doctor

Checks every link in the chain — token, exporter config, hooks, repository mapping — and names the one that is broken. Start here when the report is empty.

clocktopus agent disable

clocktopus agent disable [--revoke] [-a <ids>]

Removes this machine's telemetry configuration, the Clocktopus plugin from Claude Code, the MCP server entries setup added for Codex, OpenCode and Cursor, and the shared skills once no agent left on the machine uses them. Add --revoke to invalidate the token everywhere, which is what you want if the machine is lost rather than just being turned off. -a narrows it to one agent, with the same ids as setup.

A lost machine can't run the command, so the web app lists every machine's token under Agents and CLI in your avatar menu, where you can revoke any of them.

Common errors

Clock commands exit with code 1 on failure and print to stderr.

Message	Cause
You are not logged in. Use 'clocktopus login' to authenticate first.	No credentials on this machine
Session expired. Use 'clocktopus login' to authenticate again.	The stored token is no longer valid
Cannot use --ago and --at together. Pick one.	Both backdating flags passed
Invalid duration "…". Use formats like 15m, 1h, or 1h30m.	Unparseable --ago
Invalid time "…". Use HH:mm or HH:mm:ss format.	Unparseable --at