Time is not tokens
If you use Claude Code every day, you have probably asked two different questions, and noticed that tools tend to answer only one of them.
- How much did it cost? Tokens, dollars, which model. Usage tools such as ccusage answer this well.
- How long did I work, and on what? Hours per repository and per ticket: the number on a timesheet or an invoice. A cheap session can take an afternoon of your attention; an expensive one can finish while you make coffee.
This guide is about the second question: tracking the time you spend working with Claude Code and Codex on a Mac, accurately enough to bill, without handing anyone your prompts.
Why ordinary trackers get agent work wrong
Most automatic trackers decide you're working by watching the keyboard and mouse. After a few minutes of stillness you're idle, and that time disappears or gets flagged.
With an agent, stillness is the job. You've handed Claude Code a task and you're watching it plan, edit and run tests. You may not type for fifteen minutes. A tracker that docks that time undercounts exactly the work you're doing more of.
Manual timers have the opposite problem: you forget to stop them, or to switch them when you jump to another repository while the first agent finishes.
What Hourbrook reads, exactly
Hourbrook is a Mac time tracker. Every two seconds it notes the app in front, its window title and, in most browsers, the page you're on. That record stays in a database on your Mac. For agent work there are two more things, and it's worth being precise about each.
1. Whether an agent is busy
When you sit still, Hourbrook checks whether Claude Code, Codex or something you started in a terminal (tests, a build, a deploy) is using the CPU. If it is, you're not marked away, for up to three hours. An agent sitting at its prompt waiting for you doesn't count; one thinking, streaming or running tools does. It looks at whether those processes are busy, and when their session files were last written, never at what they do. It's a switch in Settings › Tracking: “Not while Claude or a command is working”.
2. Coding agent sessions, if you say yes
Claude Code keeps session logs in ~/.claude/projects and Codex in ~/.codex/sessions. Reading another app's logs is something you should choose, so this is off until you turn it on. When those logs are on your Mac, the Day asks you once; after that it's one switch, Settings › Privacy › Coding agent sessions, for both agents.
With it on, Hourbrook reads from those logs when each session worked, the folder it worked in (and so the repository), the git branch, how many prompts it had, and which kinds of tools it used: edits, commands. Never the text: not your prompts, not the answers, not what a tool read or printed. It doesn't keep a chat's name either, because Claude usually writes it from your first message; only a fingerprint of it, enough to join a resumed chat's logs.
That's the whole list. No prompts, no code, no screenshots, no keystrokes. None of it is sent anywhere: sync carries only the entries you choose to log. The details are on the privacy page.
Agent time per repository, and issue keys from branches
With coding agent sessions on, the Day gets a lane for each agent, named by agent, repository and branch: “Claude Code · client-a-api · kes-512-retry-uploads”. A session in client-a-api and another in client-b-web show as two, not as one blur of “Terminal”. The Week shows a quiet line under each day with how long the agents worked, and Reports has Agent time by repo. That one stays on screen: agent time is never in the PDF or CSV you send a client.
Hourbrook also notices issue keys like KES-512 or #34 in branch names, window titles and the issue pages you open, and offers them in Tasks with the time they were on screen. If your branch is kes-512-retry-uploads, the entry can say KES-512.
When you log, you pick stretches of your day (Hourbrook calls them memories) or accept a drafted entry. A stretch's card can offer “Log to Lumen” when a repository rule or your history names the project. Drafts come from a small model on your Mac that learns from entries you've logged; each draft shows its reasons.
The local MCP server: ask Claude what you did
Hourbrook comes with a small MCP server, hourbrook-mcp, that runs on your Mac. It talks to the running app over a private Unix socket only your user can open. It isn't reachable from the network, and it holds no data itself.
Connect it from Settings › AI. For Claude Code the app shows you the line it will run before it adds anything, with the right path filled in. It looks like this:
claude mcp add --scope user hourbrook -- /Applications/Hourbrook.app/Contents/MacOS/hourbrook-mcp
(If Hourbrook is still running from the disk image, it asks you to move it to Applications first, so the setup never points at a place that goes away.) Claude Desktop and Cursor connect from the same screen. Then ask in plain words:
- “What did I do yesterday?”
- “How long has KES-431 taken so far?”
- “Log an hour to Lumen for the export bug.”
- “Plan two hours for the migration on Thursday.”
There are 18 tools: reads such as what_did_i_do, search_entries and task_time, and changes such as log_time, start_timer and plan_time. Every change Claude makes shows in the Hourbrook window with Undo, so a wrong guess costs one click. The full list is on the developers page.
What Claude gets back is limited on purpose: entries you logged, your projects and tasks, totals, and agent time per repository. Minutes per app only if you turn that on in Settings › AI. Never window titles, web addresses or prompts. Text that people or other services wrote, such as an entry's title, comes back inside marked blocks so the model treats it as data, not instructions.
One honest caveat: whatever Hourbrook answers goes to the AI app's model, usually in the cloud, under that provider's terms. The server limits what it answers with.
Optional Claude Code hooks
Settings › AI can also add two Claude Code hooks to ~/.claude/settings.json, SessionStart and UserPromptSubmit. They run hourbrook-mcp hook, which tells the app on your Mac the session's id and folder, the repository and branch, and on a prompt its first line, cut to 120 characters, so the app can match the session to the right task.
The prompt line is used for matching and isn't kept. If you'd rather not send even that, skip the hooks: with coding agent sessions on, agent time per repository works without them.
Other tools, and when they fit better
There are good tools near this, and some may suit you better.
- ccusage counts Claude Code and Codex tokens and cost from local logs. If your question is spend, use it. It doesn't track your working day.
- WakaTime tracks coding time through editor plugins and reports AI usage for Claude Code, Codex and Cursor. For language and editor stats across Mac, Windows and Linux it's more mature. Its data lives in its cloud.
- Small CLIs and hook scripts read Claude Code's logs and print a worklog. If you only want agent hours in a terminal, they're lighter than a whole tracker.
- Toggl Track, Timing and Rize have their own MCP servers, so an agent can log time there too. Timing's is on its Connect plan and Rize's on Pro. Toggl runs on every platform, phones included.
Hourbrook's difference is the combination: a whole-day automatic tracker on the Mac, agent waits counted as work, agent time per repository, and a local MCP server, without the raw record leaving the machine. The comparisons go further: Timing, Rize, all of them.
Set it up
- Download Hourbrook for a Mac with Apple silicon and macOS 14 or later. The beta isn't notarized by Apple yet, so macOS asks you to confirm it once; How to install shows where. During the beta it asks you to sign in before it opens.
- Allow Accessibility when asked, so it can read window titles, and Automation for each browser whose addresses you want.
- Say yes to coding agent sessions when the Day offers it (or turn it on in Settings › Privacy).
- Connect Claude Code in Settings › AI, plus Claude Desktop or Cursor if you use them. Add the hooks if you want them.
- Work as usual. At the end of the day, open the Day, look at the agent lanes, and log.
If you bill clients for this time, the next question is how. That's how to bill clients for AI agent time.