---
url: https://clusto.app/docs/time-tracking.md
description: >-
  Clusto time tracking (Labs) - a Toggl-style Time view with a timer bar, weekly
  entries, a Week dashboard with stat tiles, a stacked bar chart and a
  timesheet, projects with colors and clients, a running-timer pill, links to
  Azure DevOps work items and connector tasks, time connectors with a Sync tab,
  Toggl import, F1 commands, and cluster-wide replication. Free on every plan.
---

# Time tracking

The **Time** view is a Toggl-style time tracker built into Clusto. Start a timer
for what you are working on, book past time by hand, group the time by project,
and read the week as totals, a chart and a timesheet. It is free on every plan
(Personal included).

Time tracking ships behind the `time.tracking` release flag (cluster scope,
default off, added in 1.15.19). Turn it on in **Settings > Labs**; see
[Feature Flags](/feature-flags). With the flag off there is no **Time** item in
the navigation and the daemon refuses the time messages.

Open it from the **Time** item in the navigation, or press F1 and run
**Go to Time**. The view is at `/time`.

## Tracking tab

The top of the tab is the **timer bar**:

* **Description** - what you are working on.
* **Project** - a picker. Type a name that does not exist yet and choose it to
  create the project on the spot. Archived projects do not appear in the picker.
* **Tags** - comma-separated, for example `review, backend`.
* **Elapsed time** - live while a timer runs.
* **Start / Stop** - starts a timer, or stops the running one.

While a timer runs, the same fields edit the running entry: change the
description, project or tags and the entry follows.

Below the bar, the entries of the week you are viewing are grouped by day,
newest first, with a total for each day. Each entry has three actions:

* **Continue** - starts a new timer with the same description, project and tags.
* **Edit** - opens a dialog to change the description, project, tags, and the
  start and end through date-time inputs.
* **Delete** - removes the entry after a confirmation.

**Add entry** books past time manually: give a description, project and tags,
and the start and end of the entry.

## Week tab

The Week tab is the dashboard for the week you are viewing.

* **Stat tiles** - total tracked time, days worked, the average per day worked,
  and the top project.
* **Bar chart** - hours per day, each bar stacked by project color. The seven
  biggest projects stay apart; the rest fold into one **Other projects** slice.
* **Timesheet** - a table with one row per project and a column for each day,
  Monday to Sunday, plus a total per row and column and each project's share of
  the week. Click a project row to edit that project.

Weeks start on Monday and are computed in your local time. The previous, next
and **This week** buttons sit above the tabs and apply to all three of them.

## Projects tab

The Projects tab lists every project with its color, client, an **Archived**
badge when it is archived, and its total for the shown week.

**New project** and editing a project open a dialog with:

* **Name**
* **Client**
* **Color** - one of 8 colors
* **Archive** - archived projects leave the picker, but the entries already
  booked to them keep showing.
* **Delete** - deleting a project keeps its entries; they then show without a
  project.

## Running timer pill

While a timer runs, a pill shows its elapsed time in the sidebar footer on
desktop and in the header on the phone layout. Click it to stop the timer in
place, from any view.

## F1 commands

| Command | What it does |
| --- | --- |
| Go to Time | Opens the Time view |
| Start timer / Stop timer | Starts a timer, or stops the running one |
| Add entry | Opens the Add entry dialog (in the Time view) |
| New project | Opens the New project dialog (in the Time view) |
| Previous week / Next week / This week | Moves the shown week (in the Time view) |
| Show Tracking / Week / Projects / Sync | Switches tab (in the Time view) |
| Start a timer on work item #N | Starts a linked timer on the open Azure DevOps work item |
| Sync time to `<name>` now | Runs the sync of one time connector at once |
| Quick log N minutes | Books what the timer bar describes as a finished entry ending now (in the Time view) |

## Quick log

Quick log books a short finished entry that ends now, for work you did not
time. The clock button next to Start in the timer bar books what the bar
describes (description, project, tags, links), and stops a running timer
first. F1 has the same command.

Length and rounding are set per device under **Sync > Quick log** (default 30
minutes, the end rounded to the nearest 15). An Undo button on the
confirmation removes the entry again.

### From other apps

The desktop app opens two links, so a browser extension, bookmark or script
can book time without holding any Clusto credentials:

* `clusto://time/quick-log?description=B%23123%20Title` books a quick log
  (add `&minutes=45` to override the length).
* `clusto://time/start?description=TR%23456%20Title` starts a timer.

`B#` and `TR#` references in the description become links as usual. A link
that launches the app waits up to 20 seconds for it to connect.

## Links

An entry can link Azure DevOps work items and connector tasks (tasks from a
plugin [time connector](/plugins#time-connectors)). A **Link** picker sits under
the timer and in the entry dialog. It:

* searches the work items the Azure DevOps view has already loaded,
* takes a typed work item number, and
* searches connector tasks.

You can also type a reference in the description. `B#123` links work item 123 and
`TR#456` links connector task 456; the links are added when the timer starts or
the entry is saved. `B#` resolves in the Azure DevOps snapshot, or in the only
account when there is exactly one. `TR#` links only when the cluster has exactly
one time connector. The entry rows show the links as chips.

### Start a timer from a work item

The Azure DevOps work item pane has **Start timer** and **Stop timer** buttons. The
F1 twin is **Start a timer on work item #N**. The entry is named
`B#<id> <title>` and carries the work item link.

## Sync tab

The Sync tab lists the time connectors that plugins provide. For each connector
you set:

* **Node** - the node that runs the connector. The plugin must be installed there.
* **Every N minutes** - how often to sync. `0` means on changes only. The interval
  also retries failed entries.
* **Look back** - how many days of entries to consider, 1 to 365.
* **Sync my entries** - the on/off switch for that connector.

**Sync now** runs a sync at once. A log shows the last runs and failures. Only
finished entries of the signed-in account are sent, and a sync runs 30 seconds
after a change. Each entry row shows a status icon: synced, waiting, failed (with
the message) or skipped. The F1 command is "Sync time to `<name>` now".

### Import from Toggl

The Sync tab can import entries from Toggl. You give:

* an **API token**, used once and never saved,
* a **date range**, and
* where `B#` and `TR#` references link (the Azure DevOps account and the
  connector).

Imported entries keep their Toggl id, so importing the same range again skips
entries you already have. A connector can also adopt the worksheet it wrote for
that Toggl entry before (the TaskSync `{togglId}||` notes), so a new import does
not create duplicates there. When Toggl answers with a quota error, the message
says when to retry.

## How it syncs

* **Cluster-wide.** Projects and entries replicate to every node. The newest
  `updated_at` wins when two nodes disagree, and deletes are kept as tombstones
  so a removed project or entry does not come back. A change shows live on every
  connected device.
* **One running timer per account.** Starting a timer stops the running timer of
  the same clusto.app account.
* **Per account.** An entry belongs to the signed-in clusto.app account that
  created it, and the view shows only that account's entries. Projects are shared
  by the cluster.
* **Admin only.** Session credentials (`cst1.`, see
  [Session Credentials](/session-credentials)) are refused, so an agent running
  in a session cannot read or change your time data.

The wire messages are listed under [Time tracking messages](/protocol#time-tracking-messages).

## Not yet

These are planned and not in the current build:

* CSV export
* Automatic suggestions from agent activity