AI agents

Commits stop being proportional to effort once an agent is involved. A session that costs eleven dollars can produce one commit, and an afternoon of your attention can produce none.

Clocktopus records what your agents cost alongside the hours you work, so the cost of a piece of work is human time × rate plus agent spend.

This feature is experimental. The recording side is solid; the reporting on top of it is still moving.

Agent time is never added to your hours

One person steering three agents for an hour is one human hour and three agent hours. Adding them gives four, which describes nothing. Agent runtime therefore never touches a timesheet total, and no screen in Clocktopus will combine them.

Money does combine. Once your hours are priced at your cost rate, that figure and agent spend are both dollars, and the sum is the true cost of delivery.

What gets recorded

Your agent reports its own usage over OpenTelemetry, and a pair of session hooks report which repository it was working in. Two channels, joined on the agent's session id.

Recorded	Where it comes from
Token usage and cost in USD	The agent's own telemetry
Active time — time spent working, not time idle	The agent's own telemetry
Model, and whether the run was headless	The agent's own telemetry
Repository, branch and working directory	Session hooks; telemetry carries no paths at all
The commits a session produced	git rev-list, run on your machine at session end

What is never collected

No prompts, no responses, no transcripts, no code. The receiver does not parse the signal those would travel in, and only an explicit list of fields — model, query source, timings, counts — is ever stored. Your agent's transcript file stays on your machine and is never read or uploaded.

Which agents are supported

Three, wired up by clocktopus agent setup. They look alike and are not: what each one can tell you depends on what its telemetry carries.

Agent	-a id	Reports	Configured in
Claude Code	claude	Tokens and real dollars	settings.json
Codex CLI	codex	Tokens only — no cost	config.toml + hooks.json
OpenCode	opencode	Tokens, via a plugin	a generated plugin file

Only Claude Code reports money. It exports OpenTelemetry metrics natively and gives real dollars, so its spend is measured rather than estimated. Codex exports logs carrying token counts and no price, and a session with no price shows as cost unknown, never as $0.00 — which is why the report's Agents used bar is a share of runtime rather than of spend.

Cursor and Grok are on the way. Other agents can already reach the receiver through the OpenTelemetry hooks bridge, but that path is built from the bridge's documented span vocabulary rather than a captured session, so they are labelled generically until one has been recorded end to end.

Two agent-specific things worth knowing:

Codex needs a trust prompt. Codex refuses to run a hooks.json it has not been shown, and the prompt is part of its own interface — there is no way to approve it from the CLI. Until you do, telemetry arrives and repository context never does, which looks exactly like a broken install. clocktopus agent setup and agent doctor both tell you when this is outstanding.

OpenCode has no session-end event. The plugin maps session.idle to session end, and that fires every time the agent stops and waits for you, so a five-turn conversation reports five of them. Commits are still declared correctly; you may just see more sessions than conversations.

Setting it up

One command, from a checkout of the repository you work in:

clocktopus agent setup

It mints an ingest token for this machine, configures every agent it finds installed, installs the session hooks, and checks the receiver accepts the token before saying it worked. Pass -a claude (or codex, opencode) to do one at a time.

Restart your agent afterwards. Both the exporter and the hooks read their configuration once, at startup. A session that is already open picks up none of it — this is the most common reason a correct setup appears to do nothing. On Codex, approve the hooks trust prompt as well.

The CLI reference covers status, doctor and disable.

How spend reaches a project and a ticket

The working directory gives a git remote, the remote is matched against the repositories attached to your projects, and the commits a session produced inherit the ticket of the entries they created. No issue-tracker integration is involved — tickets come from conventional-commit scopes, the same rule the Features report uses.

Outcome	What it means
Attributed	Exactly one project owns the repository
Unattributed	The agent ran outside any repository attached to a project. Recorded anyway — spend nobody can account for is worth seeing
Ambiguous	Several projects claim the same repository, so nothing is guessed. A wrong guess bills the wrong client
No ticket	The session produced no commits, so there is nothing to inherit a ticket from

Agents can start your day

A commit arriving on a day with no clock-in already opens one. An agent session you were sitting at is at least as good evidence that you were working — a commit can be pushed by CI, an interactive terminal means a person was there — so it does the same, at the time the session started.

It only happens when the session was attended (never a headless or CI run), ran in a repository attached to a project, and actually produced something — commits, or more than trivial spend. Opening a terminal, asking one question and going to breakfast does not start your day, and neither does an agent in your dotfiles or a scratch clone.

The signal is written as automated and shows as such on your timeline, and becomes a manual one the moment you edit it. A wrong one is a row you drag, not a number you have to hunt down.

Agent sessions also rescue entries that would otherwise price at zero. When a commit lands with nothing earlier to measure from, Clocktopus records it flagged and at 0h — the start of the work is unknown. An agent already running supplies that missing starting point.

Reading the report

Reports → Summary → AI agents groups spend by project, with tickets underneath, over whatever range and filters you have selected.

Column	What it tells you
Per human hour	Agent dollars carried by each hour you worked. The only figure that means the same thing across projects of different sizes, and so the one that moves a pricing decision
Agent runtime	How long agents were actually working, not how long a terminal sat open. Two agents steered through one hour is two agent hours, so this can exceed the length of your day
Unattributed	Spend against no project at all. Usually a repository not attached to one yet
unsteered	Agent spend with no human hours beside it. A finding, not a blank
Sessions / Commits	How many times an agent ran, and how much of it reached your repository. Sessions with no commits are the ones worth asking about

Above the table, Agents used shows every agent that ran in the period as a share of total agent runtime — runtime rather than spend, because tools that report no dollars would otherwise read as 0% of work they actually did. Tick one or several to narrow the report to the projects and tickets those agents worked on.

Human hours do not narrow with it. A time entry carries no agent, so the hours shown against a filtered ticket are the ticket's whole human time, not one agent's share of it. That makes per human hour read as "what this agent cost per hour of human work on the tickets it touched".

For the shape of a period rather than its totals, the dashboard's Daily Time Tracking chart draws agent runtime as a second line beside your tracked hours. The lines are never stacked: where runtime rises above your hours, agents ran in parallel, or ran on a day you logged nothing at all.

Per-ticket figures are an apportionment

A session's cost and runtime are both split across the commits it produced, on the same share. The telemetry knows what a session cost and how long it ran in total, not which of its commits was the expensive one. Treat per-ticket figures as a fair share, not a measurement — project totals stay measured, only the breakdown underneath them is shared out.

Nothing showing up?

Run the doctor. It checks every link in the chain and names the one that is broken, rather than telling you that something is:

clocktopus agent doctor

The usual causes, in order: the agent was not restarted after setup; on Codex, the hooks trust prompt was never approved; the repository is not attached to a project, so spend is landing in the unattributed row; or the reporting period does not cover when the sessions actually ran.