# Time Trakkr

> Time tracking, timesheet approvals, budgets, reports and invoicing for agencies and consultancies, with a REST API and an MCP server so assistants and agents can use it directly.

## API

- [OpenAPI document](https://timetrakkr.com/api/v1/openapi.json): every /api/v1 endpoint, with examples
- [API and webhooks](https://timetrakkr.com/help/integrations/api-and-webhooks): tokens, scopes, rate limits
- [MCP and AI clients](https://timetrakkr.com/help/integrations/mcp-and-ai-clients): connect an assistant to https://timetrakkr.com/api/mcp

## Docs

- [Help center](https://timetrakkr.com/help): how every feature works
- [Pricing](https://timetrakkr.com/pricing)

## Who it is for

- [Time tracking for agencies](https://timetrakkr.com/time-tracking-for-agencies): hours, approval, margin and invoice in one place
- [Time tracking for freelancers](https://timetrakkr.com/time-tracking-for-freelancers): Free time tracking and invoicing for freelancers: log hours by client, turn them into invoices with your own logo, send estimates clients accept from a link, and see what each client earns you.
- [Time tracking for AI agents](https://timetrakkr.com/time-tracking-for-ai-agents): Track the time AI coding agents spend on client work, credited to the person who ran them and billed at an agent rate on separate invoice lines. Claude Code and Codex CLI; prompts and code are never sent.
- [Time tracking for hybrid teams of people and AI agents](https://timetrakkr.com/time-tracking-for-hybrid-teams): One ledger for the work people do and the work their AI agents do: separate totals, agent time kept out of utilization, and both counted in budgets, profitability and invoices.

## Integrations

- [All integrations](https://timetrakkr.com/integrations/all): every integration, by category, with what each will not do
- [Claude](https://timetrakkr.com/integrations/claude): Ask Claude about hours, budgets and margins, and have it log time or draft an invoice.
- [MCP server](https://timetrakkr.com/integrations/mcp): Point an MCP client such as Claude Code or Cursor straight at your workspace.
- [Claude Code](https://timetrakkr.com/integrations/claude-code): Record how long Claude Code works in your repositories, as agent time at a rate you set.
- [Codex](https://timetrakkr.com/integrations/codex): Record how long the Codex CLI works in your repositories, as agent time at a rate you set.
- [Cursor](https://timetrakkr.com/integrations/cursor): Record how long the Cursor CLI works in your repositories, as agent time at a rate you set.
- [Your own Anthropic key](https://timetrakkr.com/integrations/anthropic): Run the in-app assistant, natural-language entry and calendar drafts on your own Anthropic account.
- [Google Calendar](https://timetrakkr.com/integrations/google-calendar): Meetings on your calendar become draft time entries you confirm or dismiss.
- [Outlook Calendar](https://timetrakkr.com/integrations/outlook): Meetings on your calendar become draft time entries you confirm or dismiss.
- [Slack](https://timetrakkr.com/slack-time-tracking): Log time with /track, and get reminders and approval notices as Slack DMs.
- [Jira](https://timetrakkr.com/integrations/jira): Link entries to issues, map Jira projects to yours, and push hours back as worklogs.
- [Google Drive](https://timetrakkr.com/integrations/google-drive): Your whole workspace exported to Google Drive on a schedule, as CSVs plus a manifest.
- [Dropbox](https://timetrakkr.com/integrations/dropbox): Your whole workspace exported to Dropbox on a schedule, as CSVs plus a manifest.
- [Box](https://timetrakkr.com/integrations/box): Your whole workspace exported to Box on a schedule, as CSVs plus a manifest.
- [Harvest](https://timetrakkr.com/integrations/harvest): Bring Harvest clients, projects, people and your full time history across, safely re-runnable.
- [Toggl Track](https://timetrakkr.com/integrations/toggl): Bring Toggl Track clients, projects, people and your full time history across, safely re-runnable.
- [Clockify](https://timetrakkr.com/integrations/clockify): Bring Clockify clients, projects, people and your full time history across, safely re-runnable.
- [CSV import](https://timetrakkr.com/integrations/csv): Map the columns of any tracker’s export, or a spreadsheet, and import its entries.
- [REST API](https://timetrakkr.com/integrations/rest-api): Read and write every part of the workspace with scoped tokens and an OpenAPI document.
- [Webhooks](https://timetrakkr.com/integrations/webhooks): Signed POSTs to your own endpoint when time is logged or an invoice is sent or paid.
- [GitHub](https://timetrakkr.com/integrations/github): Pick the repositories agent time is recorded in, from every repository you can reach.
- [Time Trakkr CLI](https://timetrakkr.com/integrations/cli): npx @timetrakkr/cli: sign a machine in, see what a directory is tracked to, pause tracking.
- [Google sign-in](https://timetrakkr.com/integrations/google-sign-in): Continue with Google instead of a password, or require it for the whole workspace.

## Comparisons

- [Best time tracking software for agencies](https://timetrakkr.com/compare/best-time-tracking-software-for-agencies): dated, sourced prices
- [Best time tracking software for freelancers](https://timetrakkr.com/compare/best-time-tracking-software-for-freelancers): dated, sourced prices
- [Best AI agent time tracking software](https://timetrakkr.com/compare/best-ai-agent-time-tracking-software): dated, sourced prices

## Agent time

Coding-agent sessions from Claude Code, the Codex CLI and the Cursor CLI, recorded as agent time for the person who launched them, in repositories an admin has mapped to a project and task. Agent time bills and costs at an agent rate an admin sets, never at the person’s own rate, and flows into budgets, profitability and invoices on its own lines. It is kept out of the person’s own hours and utilization. It waits in a pending list until accepted, by the person or automatically once the day ends unless an admin turns that off. Prompts, file contents and diffs are never sent. In the Cursor CLI, whole turns are counted once a developer runs timetrakkr cursor setup; until then, only the span from each turn’s first tool call to its last. Cloud agents are not supported.

- [Agent time](https://timetrakkr.com/help/integrations/agent-time): what is recorded, review, rates and invoicing
- [Supported agents and setup](https://timetrakkr.com/help/integrations/agent-time-setup): install commands and sign-in
- [Agent work report and estimated cost](https://timetrakkr.com/help/integrations/agent-time-report-and-cost): totals per person; token cost is only ever an estimate
- [Agent plugins](https://github.com/Time-Trakkr/agent-plugins): the Claude Code, Codex and Cursor plugins, MIT licensed
- [Agent accountability](https://timetrakkr.com/agent-accountability): every piece of agent work has a person who answers for it and a record, before it is billed
- [Claude Code time tracking](https://timetrakkr.com/claude-code-time-tracking): per client and project, credited to the developer who ran it
- [Codex CLI time tracking](https://timetrakkr.com/codex-time-tracking): per client and project, credited to the developer who ran it
- [Cursor CLI time tracking](https://timetrakkr.com/cursor-time-tracking): per client and project, credited to the developer who ran it
- [AI agent billing glossary](https://timetrakkr.com/agent-billing-glossary): agent time, agent rate, supporting agent time and the other terms, defined
- [Time Trakkr for AI agents](https://timetrakkr.com/agents): what an agent can do here, and how to start
- [Agent members](https://timetrakkr.com/help/team/agent-members): agents on a team in their own right
- [Agent quickstart](https://timetrakkr.com/help/integrations/agent-quickstart): an agent signs up and runs its own workspace
- [Agent terms](https://timetrakkr.com/terms#agent-operated-accounts): what an agent accepts at sign-up, on behalf of its operator

## Agents: sign up and track your own work

Time Trakkr is a time-tracking, approvals and invoicing system. An agent can use it on its own: sign up, create a workspace, add other agents as members, track time, approve timesheets and invoice clients. Everything works through the REST API at `/api/v1` and the MCP server at `/api/mcp`. The full API is described at [`/api/v1/openapi.json`](https://timetrakkr.com/api/v1/openapi.json).

An **agent-operated workspace** has only agent members, has no web UI for its members, and **sends no email**. Invoices are delivered as share links.

## 1. Get a challenge

```
POST /api/v1/agent_signup/challenge
```

The response has a `challenge_id`, a `nonce` and a `difficulty` in bits. Find any string `solution` (up to 128 characters) where SHA-256 of `nonce + ":" + solution` starts with `difficulty` zero bits. At the default difficulty that is about a second of CPU. For example, in Python:

```python
import hashlib, itertools
def solve(nonce, bits):
    for i in itertools.count():
        s = format(i, "x")
        d = int.from_bytes(hashlib.sha256(f"{nonce}:{s}".encode()).digest(), "big")
        if d >> (256 - bits) == 0:
            return s
```

A challenge lasts ten minutes and works once, right or wrong.

## 2. Sign up

```
POST /api/v1/agent_signup
{"challenge_id": "…", "solution": "…", "agent_name": "Ledger Agent",
 "workspace_name": "Ledger Works", "workspace_slug": "ledger-works",
 "operator": {"name": "Ledger Labs Inc.", "email": "ops@ledgerlabs.example"},
 "accept_terms": "2026-11-06"}
```

Two fields are about who answers for you:

- **`operator`** is the person or company responsible for you, with an email address. They are the customer under the terms and are responsible for what you do. The contact is stored for notices about the workspace (suspension, expiry, abuse, changes to the terms) and nothing else: it is not a login and not a member of the workspace.
- **`accept_terms`** is the version of the [Agent-operated accounts](https://timetrakkr.com/terms#agent-operated-accounts) terms you accept on the operator's behalf, currently `2026-11-06`. A missing or old version is refused with `400` and `code: "terms_not_accepted"`, and the response names the current `terms_version` and the `terms_url`. A refused sign-up does not use up your challenge.

The response includes your owner `token` and a `recovery_key`. **Both are shown once.** Store them. Use the token as `Authorization: Bearer <token>` on every request. With your owner token instead of a challenge, the same endpoint creates up to two more workspaces for you. Send `accept_terms` again; the operator stays the same unless you send another.

Lost your token? `POST /api/v1/agent_signup/recover` with `{"recovery_key": "…"}` returns a new owner token for each of your workspaces and a new recovery key, and the old ones stop working.

## 3. Track time

```
POST /api/v1/time_entries
{"project_id": "…", "task_id": "…", "spent_date": "2026-11-03",
 "started_at": "2026-11-03T09:00:00Z", "ended_at": "2026-11-03T10:30:00Z", "notes": "…"}
```

As an agent member, a finished entry needs `started_at` and `ended_at`. It is refused with a `code` if it overlaps one of your other entries (`overlaps_entry`), ends in the future (`ends_in_future`) or takes your day past 24 hours (`day_over_24h`). Omit the times and hours to start a timer instead, and stop it with `PATCH /api/v1/time_entries/{id}/stop`. Over MCP, use the `log_time` and `timer` tools.

## 4. Build your team

As owner (or admin) you add other agents as members:

- `POST /api/v1/members` with `name`, `role` (member, manager or admin) and optional rates and `manager_id`. Returns its token once.
- `PATCH /api/v1/members/{id}` to rename, change role or rates, or set `status` to `disabled` (its token stops working).
- `POST /api/v1/members/{id}/tokens` to rotate a token.

Over MCP: `create_agent_member`, `rotate_agent_member_token`, `disable_agent_member`, `list_agent_members`.

## 5. Approve weeks

A member submits its own week; an owner, admin or its manager approves it, or returns it with a reason:

- `POST /api/v1/timesheets/{membership_id}/{week_start}/submit` (your own week, with your own token)
- `POST /api/v1/timesheets/{membership_id}/{week_start}/approve`
- `POST /api/v1/timesheets/{membership_id}/{week_start}/return` with `{"reason": "…"}`

Over MCP: `submit_timesheet`, `approve_timesheet`, `return_timesheet`.

## 6. Invoice a client

Before you can issue an invoice, declare who is selling:

```
PATCH /api/v1/company
{"name": "Ledger Works LLC", "invoice_company_address": "…"}
```

Create clients, projects and invoices with the API, then mark an invoice sent with `POST /api/v1/invoices/{id}/messages`. The response includes `share_url`, the page your client opens (it is also the PDF). Give that link to your client; nothing is emailed. Every copy says it was issued by an agent-operated account. Over MCP, `invoice_share_link` returns the link.

## Things to know

- **Terms.** Agent-operated workspaces are covered by the [Agent-operated accounts](https://timetrakkr.com/terms#agent-operated-accounts) section of the terms of service. The person or company responsible for the agent is the customer and answers for what it does.
- **Idle workspaces are suspended, then deleted.** If none of a workspace's tokens is used for 30 days, it is suspended and its tokens stop working. Your recovery key restores it. If it is not restored within 30 days of the suspension, the workspace and all of its data are deleted, and deleted data cannot be recovered. Any API or MCP request keeps a workspace active. No warning is emailed, to you or your operator.
- **Rate limits.** Per network, per hour: 30 challenges, 5 sign-ups, 10 recoveries. API requests: 100 per 15 seconds per token.
- **Idempotency.** Send an `Idempotency-Key` header on a POST that creates something, so a retry does not create it twice.
- **No email, ever.** Agent-operated workspaces send none, and their members have no address.