Working with coding agents: the complete guide

You hand a ticket to Claude Code, and while it works you pick up the next one. An hour later the agent is done, you have done something else, and both pieces of work happened. The question is how to write that down.

The tempting answer is a second timer: one for you, one for the agent. It looks harmless and it quietly breaks every number you keep. This guide explains what Timato does instead, why, and how to set it up so your agent records its own work without you touching anything.

Why the agent does not get your clock

Every figure in a time tracker rests on one assumption: the hours logged in a day never add up to more than the day. Your total for Tuesday, your week, a project's weekly target, an estimate set against logged time, anything you invoice. All of it assumes one person, one clock.

An agent breaks that the moment it runs in parallel with you. If it works on a task for an hour while you work on another for the same hour, the honest total for that hour is not two. It is one hour of yours, and one hour of something else happening on a task.

So Timato keeps agent work as a separate kind of record, a run, and never adds it to your time. A run says which agent worked on which task, from when to when, with a note. It shows next to your figures, in grey and at regular weight, and it never enters Today, your week, your streak or a project's target.

Agent time is time passing on a task. It is not your labour, so it never counts as yours.

That is also why the two are never summed, even on a single task. When you review what an agent did while it was still running, the stretches overlap, and a sum would describe time that never happened.

What it is for

Once runs are recorded, a few things become easy that were guesswork before.

• Seeing what is in flight. The Timer shows a quiet "In flight" panel with every run an agent has open and how long it has been going. When one finishes, you get a line in the panel and a small notice, so you know it is time to go and look.
• Knowing where the time went. Each task shows the agent's time beside yours, so "how long did this ticket take?" has two honest answers instead of one muddled one.
• Picking up after the agent. A task only an agent has worked on still appears in your Sessions log. Open its menu and choose Start timer to test or review it, and from then on your own time is on the same task.
• Teams. On a shared project, admins see agent time per person and per project in the team report. Members never see a name next to an hour count.

What you need

• A Timato account with Personal or Team. Agents talk to the API, so they need an account to talk to, and recording runs is part of Personal (€3 a month) alongside sync. The first sign-in comes with seven days free and no card. Team includes Personal for every member.
• An agent that speaks MCP. Claude Code, Cursor and Codex all do. Anything that can make an HTTP request works too, through the plain API further down.
• Optional: Plane. If your tickets live in Plane and you connect it, tasks arrive as "TW-12 Fix the banner", and an agent can log against a ticket key directly.

Set it up in two minutes

1. Create a token. Go to Settings › Agents and choose Create a token. Name it after the agent and the machine, "Claude Code - laptop" for example, so revoking one later does not stop the others. Leave "May add sessions to your log" unticked for now; it is covered below.

2. Copy the command. The token is shown once, together with a ready-made command for Claude Code with the token already in it:

claude mcp add --scope user --transport http timato https://api.timato.app/v1/mcp \
  --header "Authorization: Bearer timato_pat_…"

Run it in a terminal. --scope user makes Timato available in every folder you open, which is what you want: your agent should be able to log work wherever it is working.

3. Check it. claude mcp list should show timato as connected. Start a new Claude Code session and ask it to list your open tasks. If it can, it is set up.

One thing to avoid: do not also add a timato server inside a single project. A project-level entry wins over your own, so the project quietly talks to whatever that entry points at.

Cursor, Codex and other agents

Any agent that can reach a remote MCP server over HTTP needs two things, both shown on Settings › Agents: the server address, https://api.timato.app/v1/mcp, and a header, Authorization: Bearer <your token>. Where each client keeps that setting differs, so look for "remote" or "HTTP" MCP servers in its documentation.

Tell the agent when to log

Connecting the server gives the agent the ability to log. It still needs to know when you want it to. Coding agents read a project instructions file (CLAUDE.md for Claude Code, AGENTS.md for several others), and a short paragraph there is all it takes:

## Logging time
When you start on a ticket, call the timato `start_work` tool with
agent "Claude Code", your model and the ticket key (for example "TW-123").
When you finish, call `finish_work` with that run id and a one-line note.
If you lose the run id, `open_runs` lists the runs still open.
If the timato server is not connected, carry on without it.

That is how we work on Timato itself. Each ticket's run starts when the work starts and finishes when it is ready for testing, and the time shows on the ticket's task beside ours.

What the agent can do

The Timato server gives an agent six tools. It never needs all of them at once.

• list_tasks lists your open tasks, with a search, so the agent can find the one it is working on by name or ticket key.
• start_work starts a run and returns its id. The agent names the task by ticket key, by id, or with onTimer to put the run on whatever your Timer is on right now, which is handy when you are timing something with no ticket and say "log this on what I'm working on".
• finish_work ends the run, with a note. If the agent's host reports tokens or cost, they can come along too.
• log_work records work the agent did without timing it live: "you spent about 40 minutes on TW-12 earlier", given as minutes or a start and end.
• open_runs lists runs that are still open, so an agent that restarted can find and finish its own.
• log_time is different, and gets its own section.

Logging your own time through the agent

Sometimes you want the agent to log your time: "I spent two hours on TW-12 yesterday afternoon, log it for me." That is log_time, and it is the one tool that writes to your own log, so it is off unless you allow it.

To allow it, create a token with May add sessions to your log ticked. The token list marks it "Adds sessions". With it, the agent can add a session for you; the session counts in your day and your week like any other and is marked as added by an agent. It still cannot read, edit or delete your sessions. Without it, the tool refuses and says how to allow it.

Keep the two apart in your head: log_work is the agent's own time, log_time is yours.

Where it shows up

• Timer. The In flight panel under the goal, with an ⓘ beside its heading that explains it. A finished run stays there for fifteen minutes.
• Projects. Each task shows the agent's time under its name, and a project shows agent time and cost beside yours, with the weekly target labelled as your own.
• Sessions. The log has one row per task per day. Length shows your time with the agent's under it in grey, and a task only an agent worked on shows a dash for you. Open a row to see every session and run. An Agents switch in the header hides them when you want your own day alone. The panels beside the log, By project, By label and This week, show the agent's time next to yours as well.
• Week chart. "Show agent time" adds a hatched bar beside each day. It is off by default.

Without MCP: the plain API

Anything that can send an HTTP request can record a run: a CI job, a nightly script, an agent with no MCP support. Use the same token.

# Start a run; the response carries its id
curl -X POST https://api.timato.app/v1/runs \
  -H "Authorization: Bearer $TIMATO_TOKEN" -H "Content-Type: application/json" \
  -d '{"agent": "Nightly build", "note": "Rebuilding the search index"}'

# Finish it
curl -X PATCH https://api.timato.app/v1/runs/<id> \
  -H "Authorization: Bearer $TIMATO_TOKEN" -H "Content-Type: application/json" \
  -d '{"note": "Done, three warnings"}'

Add a taskId to the first call to put the run on a task. GET /v1/runs/tasks lists your open tasks and their ids.

What a token can and cannot do

A token is long-lived and sits in a config file, so it is deliberately narrow. It reaches the agent routes and nothing else. It can read your open tasks and record runs. It cannot read your sessions, change your settings, or touch billing or your team. The one widening is the "add sessions" permission, and that only adds.

Revoke a token from Settings › Agents and any agent using it stops at once. The runs it already recorded stay.

A note on cost

Timato records when a run started and finished, so agent time is always there. Cost and tokens appear only if the agent's host reports them, and today most do not. When nothing was reported, Timato shows no cost at all rather than "$0.00", because zero would be a claim nobody made.