Skip to content

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. 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. As you type, it suggests earlier entries (last 90 days) that match the description or project name. Pick one with a click or the arrow keys and Enter to fill in its project, tags and links as well.
  • 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. The description suggests earlier entries the same way the timer bar does.

Start and end are typed in your chosen date and time format (placeholder shows the pattern) and invalid dates block Save. Change the format in Settings → Appearance.

Calendar tab ​

The Calendar tab draws the week as a grid: one column per day, Monday to Sunday, with the date and the day's total in the header and the hours down the left. Each entry is a block in its project's color, placed by its start and end, showing its description, project and duration. Entries that overlap sit side by side, an entry that crosses midnight shows on both days, and a running timer grows until now. A red line marks the current time.

  • Add time - drag on empty space to book that range, or click (tap on a phone) to book your quick log length from that point. The entry editor opens with the times filled in; nothing is saved until you click Save.
  • Move - drag a block to another time or day.
  • Resize - drag a block's bottom edge to change its end.
  • Edit - click a block, or focus it and press Enter.

Drags snap to 15 minutes. A running timer cannot be dragged; click it to edit its details. On a touch screen, long-press a block (or empty space) before dragging, so a normal swipe still scrolls.

The toolbar shows the ISO week number (for example W43), a Today button and zoom buttons for the hour height; the zoom is remembered on this device. The grid opens scrolled to the first entry of the week, or to 7:00. On a phone the calendar shows one day (three on a wider screen): use the arrows or swipe sideways to page through the week and on to the next one.

Suggest entries from activity ​

Suggest (sparkles icon, in the Time view header) finds the work you did but did not time and proposes it as entries. Open it from the button, or press F1 and run Suggest time entries from activity. It is free on every plan (Personal included) and sits behind the same time.tracking flag.

  1. Pick the days to search. The picker has one toggle for each day of the shown week and the shortcuts Weekdays, Whole week and Clear. By default it selects today when today is in the shown week, else the week's weekdays. One request covers all picked days; days you left unpicked between them are skipped. A range is at most 8 days.
  2. Choose whether to Name the entries with AI. It is on by default. With it on, the Instructions for the AI box appears (see below).
  3. Click Find work.

Where the evidence comes from ​

The node you are connected to reads its own evidence and asks every online node for theirs:

  • Claude Code transcripts (~/.claude/projects/*/*.jsonl; subagent transcripts are left out).
  • Codex sessions (~/.codex/sessions).
  • The git commits you authored, in the folders those transcripts name. Clusto uses each repo's git config user.email, reads all branches and leaves merge commits out.

On a node whose daemon runs as root, Clusto reads the Default Session User's home. With no non-root Default Session User that node is skipped and named in a note.

How slots become suggestions ​

The range is split into 15-minute slots. Each slot goes to the folder with the most activity in it: a typed prompt counts 4, a commit counts 3 and each active minute counts 1. A slot needs a score of at least 2 to count.

  • Neighbouring slots of one folder join into one suggestion.
  • One quiet slot between two slots of the same folder is bridged.
  • Slots that overlap an entry you already booked, including the running timer, stay empty, so suggestions never overlap your entries.

Names and projects ​

With AI on, the connected node's Claude CLI writes a short description for each block from its prompts and commits. It runs under the Default Session User's own login with the haiku model, no tools, no MCP servers, no settings or hooks, and nothing is saved to the session history. Pasted blocks and image markers are left out of the prompts it sees.

Instructions for the AI ​

The Instructions for the AI box takes your own naming and filtering rules in free text, up to 4000 characters. It is saved and synced across your devices with your other preferences (account sync), and is used only when Name the entries with AI is on. For example:

Track only work for Acme. Name entries B#<work item id> <work item title>. Skip personal projects.

With AI naming on, the AI also sees, besides the prompts and commits:

  • Your Azure DevOps work items: open items assigned to you first, then items on the running sprint board, from every Azure DevOps account the node holds, up to 150. An account that cannot be read is named in the notes.
  • Pull request titles that match a block's git branch.
  • Your most-used entry names from the last 28 days (up to 60), so it can reuse your exact naming.

Descriptions can be up to 160 characters, enough for a work item id and its full title.

When your instructions say a block should not be tracked, the AI leaves it out. Such blocks are still returned, unticked, at the bottom under Left out by your instructions (N), so you can tick one and add it anyway.

Without AI, or if the call fails (shown as a note), a suggestion is named after its first commit, else its first prompt, else the folder.

The project is pre-filled when a time project's name matches the folder: an exact match that ignores case and punctuation, else the longest project name the folder contains. Archived projects are not matched.

Review and add ​

Each row shows the time span, the duration, an editable description, a project picker and a Based on list of the prompts and commits it came from. Rows start selected. Add N entries saves the selected rows as normal finished entries. Nothing is saved before that.

After a search, a chip per folder shows its total time. Click a chip to hide or show that folder's suggestions. Hidden folders are remembered and synced across your devices.

Notes above the list name nodes that did not answer and AI naming failures.

Privacy ​

The transcripts are read on each node. Only short excerpts (prompts and commit subjects, up to 160 characters each) travel to the connected node and, with AI on, to the provider your own Claude CLI already uses.

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 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 ​

CommandWhat it does
Go to TimeOpens the Time view
Start timer / Stop timerStarts a timer, or stops the running one
Add entryOpens the Add entry dialog (in the Time view)
New projectOpens the New project dialog (in the Time view)
Previous week / Next week / This weekMoves the shown week (in the Time view)
Show Tracking / Calendar / Week / Projects / SyncSwitches tab (in the Time view)
Time calendar: today / zoom in / zoom outShows today in the calendar, or changes its hour height (in the Time view)
Start a timer on work item #NStarts a linked timer on the open Azure DevOps work item
Sync time to <name> nowRuns the sync of one time connector at once
Suggest time entries from activityOpens the Suggest dialog (in the Time view)
Quick log N minutesBooks what the timer bar describes as a finished entry ending now (in the Time view)

Ask an agent ​

Every agent Clusto sets up (Claude Code, Codex, Gemini CLI) gets three timer tools through clusto mcp, so you can say "start a timer on the Shoptet import" or "stop my timer" in any session or chat:

ToolWhat it does
clusto_timer_statusThe running timer, today's entries and total, and the time projects
clusto_timer_startStarts a timer with a description, a project (id or exact name) and tags, stopping the account's running one
clusto_timer_stopStops the account's running timer, or one entry by id

An agent has no clusto.app account of its own, so the tools act for the account that owns the running timer, else the one that saved the newest entry. The timer they start shows in the app like one started there. Editing or deleting entries stays in the app.

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.

An entry can link Azure DevOps work items and connector tasks (tasks from a plugin time connector). 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.

Two-way sync with Toggl ​

The Toggl Track plugin adds a two-way connector, for when you keep using Toggl alongside Clusto. Under the connector in the Sync tab, save your Toggl API token (Toggl > Profile settings) and, optionally, a workspace id (default: your default workspace). Test connection checks the token.

  • Clusto to Toggl. Finished entries are created, updated or deleted in Toggl, with their project (created in Toggl by name when missing) and tags. Entries imported from Toggl update their original Toggl entry instead of copying it.
  • Toggl to Clusto. Every interval run and Sync now also brings back what changed in Toggl within the look-back window: new entries, edits and deletions. A timer still running in Toggl comes over once it stops.
  • Conflicts. When an entry changed on both sides, the newer change wins.
  • The connector shows a Two-way badge, and the run's message counts the entries it pulled.

Toggl Free allows about 30 API requests an hour, and each created, changed or deleted entry is one request. Keep the interval at 15 minutes or more; when the quota runs out, the remaining entries fail and are retried on the next run.

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, except the timer. Session credentials (cst1., see Session Credentials) cannot edit or delete entries, projects or connectors. An agent may read the time data and start or stop the timer through the clusto mcp timer tools (see Ask an agent).

The wire messages are listed under Time tracking messages.

Not yet ​

These are planned and not in the current build:

  • CSV export
  • Automatic suggestions from agent activity

Clusto - remote AI coding agents over WebSocket.