Claude Code knows which repository it is working in. A client's work usually lives in that client's repositories. So the simplest way to track Claude Code time per client is to let the repository decide: map each repository to a client project once, and every session in it is recorded there without anybody choosing a project.
This guide sets that up in Time Trakkr, from the admin's side and then the developer's. The same steps work for the Codex CLI, with one extra step noted below. For what is recorded for each agent and what is not, see Claude Code time tracking and Codex CLI time tracking.
Before you start
You need:
- an admin or owner on the Time Trakkr workspace;
- the clients and projects already set up, with a task for agent work on each, such as Development;
- Node 20 or later on each developer's machine.
1. Enable agent time
Under Settings → Add-ons, an admin enables Agent time. That opens Settings → Agent time → Setup, a checklist of what is done and what is left. Until an admin enables it, nothing is recorded for anybody.
2. Set a default agent rate
This is the one required step. Until the workspace has a default agent rate, nothing is recorded, and each developer's agent says agent time is not set up yet. Time from before the rate was set is not sent later.
A rate has an hourly bill rate and an hourly cost rate. Set the workspace default first, then add client or project rules where an agreement differs. Agent rates covers how to choose the numbers.
3. Map repositories to client projects
Under Settings → Agent time → Repositories, connect your GitHub account to pick from the repositories you can reach, or type a repository's remote for GitLab, Bitbucket or any other host. For each one, choose the project and task its sessions belong to.
Say a studio has three clients:
| Repository | Project | Task |
|---|---|---|
| github.com/acme/storefront | Acme Rebrand | Development |
| github.com/northbeam/reporting | Northbeam Retainer | Development |
| gitlab.com/cartwright/audit-tools | Cartwright Audit | Tooling |
A few details are worth knowing:
- Any form of the remote works.
[email protected]:acme/storefront.git,https://github.com/acme/storefrontandgithub.com/acme/storefrontare the same repository. - Rules can be limited to branches, with a pattern such as
release/*. A branch rule beats the rule for every branch. - A repository with no rule is not tracked. The plugin sends nothing for it, not even its name. Internal tools and side projects stay out of client billing unless you map them.
The same page has a What does this remote map to? check, which shows the rule that wins for a remote and a branch.
A repository can also carry its own mapping in a .timetrakkr.json file at its root, which overrides the admin's rules for that repository.
4. Decide about automatic accepting
Accept automatically is on unless an admin turns it off. With it on, sessions from mapped repositories become agent time entries once the day has ended, and people correct them afterwards. With it off, every session waits in its person's pending list until they accept it.
If your policy is that a person looks at agent time before it can be billed, turn it off here.
5. Install the plugin
Each developer runs this once:
claude plugin marketplace add Time-Trakkr/agent-plugins && claude plugin install timetrakkr@timetrakkr
Or, inside a Claude Code session, /plugin marketplace add Time-Trakkr/agent-plugins and then /plugin install timetrakkr@timetrakkr.
For the Codex CLI the command is codex plugin marketplace add Time-Trakkr/agent-plugins && codex plugin add timetrakkr@timetrakkr. Then start Codex and trust the plugin's hooks with /hooks: Codex does not run a plugin's hooks until you have.
An admin who would rather not rely on everybody remembering can make the plugin required instead, with managed settings for Claude Code. The setup article has the details.
6. Sign in through the browser
Start a Claude Code session in one of the mapped repositories. On a computer that is not signed in yet, your browser opens on a Time Trakkr page that names the computer asking and lists exactly what it will and will not be able to do. Pick the workspace and press Allow access. Tracking starts at your next prompt.
If you closed that window, type /timetrakkr:login in the session. From a terminal, npx @timetrakkr/cli login does the same.
The sign-in can do two things: report how long your agents worked, and read the repository rules that apply to you. It cannot read or change your time entries, accept agent time, or read reports, budgets or invoices. It is listed under Connected apps, where it can be revoked.
On a machine without a browser, create a personal access token with Agent time only ticked and set it in TIMETRAKKR_TOKEN.
7. Check it works
At the start of each session, Claude Code prints one line: the client, project and task the session is tracked to, or that it is not tracked. /timetrakkr:status says the same and whether sign-in works.
Then work as usual. A turn starts when you submit a prompt and ends when Claude Code stops, and agent time is the sum of the turns. Time between turns, and time waiting for you to approve a tool, is not counted.
The next day, the sessions are on the developer's timesheet: as pending time to accept, or as agent time entries if automatic accepting is on.
What this will not do
It records Claude Code and the Codex CLI on your own machine. Claude Code cloud sessions, Codex cloud tasks and the Codex IDE extension are not recorded, and the Cursor plugin has never been run against a real Cursor session, so treat Cursor as unsupported. It never sends your prompts, file contents or diffs. A problem shows up as missing time, never as an error in your agent; ~/.timetrakkr/hook.log has anything the plugin could not do.
Common questions
Does every developer need to pick a project for each session?
No. The repository rule picks it. A developer can change the project or task on a pending session before accepting it, or move an entry afterwards.
What if two clients share a repository?
Use branch rules, so that client-a/* maps to one project and client-b/* to another. When two patterns both match, the narrower one wins.
Can I pause tracking for one session?
Yes. timetrakkr off stops tracking the current session and timetrakkr on resumes it. Time already sent stays in your pending list for you to discard.
Is my session time visible to my manager?
Your manager sees how many sessions you have waiting and how much time, not what they were. Accepted agent time is on your timesheet like other entries, marked as agent time.
