Agent time: supported agents and setup

Agent time is recorded by a small plugin that runs beside your coding agent on your own computer. Which agents are supported:

• Claude Code is supported, on your own machine.
• Codex is supported for the Codex CLI, interactive and codex exec. Installing it as a Codex plugin has not been tested end to end; what was tested is its hooks loaded into a project.
• Cursor has a plugin that has never been run against a real Cursor session. Treat Cursor as not supported until somebody has checked that time arrives.

Not supported, and nothing is recorded for them:

• Agents that run in the cloud: Claude Code cloud sessions, Codex cloud tasks and Cursor cloud agents. The plugin is not on that machine and neither is your sign-in.
• The Codex IDE extension, which does not load plugins.
• Any other agent or editor. There is no plugin for it.

There is no way to add agent time by hand. If your agent is not supported, log your own time as usual; an assistant you talked to is your time, not agent time.

Setting it up, for an admin

You do this once.

1. Enable it. Under Settings → Add-ons, enable Agent time. You are taken to Settings → Agent time → Setup, a checklist that says what is done and what is left.
2. Set a default agent rate. This is the one required step. Until the workspace has a rate for all its work, agent time records nothing, and each developer's agent says it is not set up yet. Time from before the rate was set is not sent later. Rates for a client, a project or one agent are set under Rates and prices, but they do not count as the default.
3. Connect repositories. Under Repositories, pick each repository and the project and task its time belongs to. Agent time is only recorded in a connected repository; anywhere else nothing is recorded or sent.
4. Accept automatically is on unless you turn it off. Time from connected repositories becomes time entries once the day has ended, without anybody accepting it. People can still reduce or delete an entry, and deleting one puts its time back in their pending list. Reducing one does not. Turn it off and agent time waits in each person's pending list until they accept it.
5. Roll out to your team (optional). Once the plugins are published, the Setup page shows the install command for each agent, and how to make the plugin required for everyone: managed settings for Claude Code, the Installed policy in the ChatGPT admin for Codex, and a team marketplace set to Required for Cursor. Codex's requirements.toml cannot require a plugin, so there is no file for that.

The plugins are not published yet. Until they are, the Setup page says so instead of showing a command, and developers load a plugin from a local copy as described below.

Installing the plugin, for a developer

You do this once, and not at all if your admin made the plugin required.

You need Node 20 or later on your PATH.

Once the plugins are published, copy the install command for your agent from your admin's Setup page, or ask them for it. The first session you start in a connected repository then opens your browser to sign in: pick the workspace and press Allow access.

Until then, each plugin is a folder (plugins/claude-code, plugins/codex, plugins/cursor) that you load from a local copy. Its README has the exact steps for that agent, and they differ:

• Claude Code: start it with claude --plugin-dir <path to plugins/claude-code>. Inside a session the plugin puts the timetrakkr command on the path; run it by typing ! timetrakkr status at the prompt.
• Codex: add the folder through a local plugin marketplace, then review and trust its hooks with /hooks. Codex does not run a plugin's hooks until you have. Put the timetrakkr command on your PATH yourself.
• Cursor: follow the plugin's README, and expect to have to check that it works.

Every day

Nothing. Work as usual in a connected repository. With accepting automatically on, the day's agent time becomes time entries after the day ends; your pending list is only for corrections. With it off, accept or discard your sessions from your timesheet's day view.

Signing in by hand

timetrakkr login signs in at any time; add --url https://<your workspace address> if it asks which workspace. Your browser opens on a Time Trakkr page that names the computer asking and lists what it will and will not be able to do. Press Allow access. On a machine with no browser, create a personal access token with Agent time only ticked under Developer → Personal access tokens and set TIMETRAKKR_URL and TIMETRAKKR_TOKEN.

Either way the plugin 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 anything else. The details, and how to revoke a sign-in, are under Signing in in Agent time.

Checking that it works

• timetrakkr status says what the current directory is tracked to and why, whether you are signed in, and the last error if there was one.
• When a session starts, Claude Code prints one line: what the session is tracked to, or that it is not tracked. Codex may not show it and Cursor does not.
• timetrakkr off stops tracking the current session and timetrakkr on resumes it. Time already sent stays in your pending list for you to discard.
• A problem shows up as missing time, never as an error in your agent. ~/.timetrakkr/hook.log has anything the plugin could not do.

How the agents differ

• Waiting for a permission prompt is left out of agent time on Claude Code. On Codex and Cursor it is counted, because those agents do not report it reliably.
• Token counts are sent by Claude Code and Codex when they can be read. Cursor sends none, so its sessions always show token cost as "not captured".
• No agent sends a summary of what a session was about yet. A pending session is named by its agent and branch.