hourdial

hourdial guide

Everything hourdial does, in detail. The README covers install and the first day.

Sections:

Privacy in detail

TUI keys

You don’t need to learn the keys:

1-7 / tab        today · week · inbox · focus · rules · plan · labels
: / ctrl+k       command palette
?                all keys
r · q            refresh · quit

today            enter label the row (accepts a ★ suggestion, or labels time away)
                 t tag · p project only · T tag and learn a rule · i why this score
                 a label the latest time away · A leave it idle
                 s split (label part of the row) · d delete its time · + add time
                 j/k move · h/l previous/next day · . today · / filter
                 c every window ↔ compact rows (labelled rows in a row merge)
week             enter open day · h/l week · . this week · m month trends
inbox            enter accept the suggestion, else learn a rule · T pick a label
                 o tag once · x ignore
anywhere         u undo the last change (tag, rule, ignore, time away, edit)
focus            s start a session · x stop · z snooze or resume distraction notices
                 enter take the pending suggestion · d not now
rules            e edit rules.toml · J/K move a rule down/up
plan             enter/space/x done ↔ not done · a add · d delete · e edit the file
                 f focus session · u undo the tab's last edit
labels           a add a category · m add a module under it · e rename · K kind
                 w afk window · f file a project under a category · l other names
                 x archive · M merge into another · d delete · enter fold
pickers          ★ suggested and ↺ recent labels come first · type to filter · enter · esc

Colours follow the kind of time, the same in the TUI, the dashboard and the menu bar: blue for deep work, slate for shallow, mauve for browsing, brick red for distraction, grey for the rest, and hatched grey for time nobody labelled yet. The palette has light and dark variants and follows your terminal’s background.

The first time you run tock without rules, it offers to write the starter rules.

The mouse works everywhere. Anything that shows a key is a button: the footer, the help, a dialog’s enter ok, the a label of time away, the u undo after a change. Click a tab to switch, a row to select it and the selected row again for enter. Right-click a row for a menu of what you can do with it. Hovering shows what a thing is in the footer.

On the today tab, the strip under the score is the day: one cell per slice of time, coloured by its kind (faint dots are idle). Click a cell, a work block or an hour of the heatmap to jump to that time; click a category or a module in Where it went to show only its rows, and again to show all; the score opens its breakdown. A terminal 130 columns wide or more puts Where it went, with every module, the goals and the work blocks in a sidebar.

The labels tab (7) is where your categories and modules live: each with its kind, AFK window and 30 days of time. Click a kind or an AFK window to change it. The label picker (t) offers a module as you type its name or an alias: ana → Study / Analyse 1.

While hourdial has the mouse, dragging no longer selects text. Hold Shift (WezTerm, kitty, most terminals) or Option (Terminal.app, iTerm2) while you drag to select text anyway.

Commands

tock help shows the ones most days need; tock help all lists them all, as below, and tock <command> --help shows one.

Every day:
tock                                   open the TUI (today, week, inbox, focus, rules, plan)
tock today [--date YYYY-MM-DD] [--keys]
tock inbox [--days N] [--all | --auto]  unlabelled activity, numbered; --auto: what tock labelled itself
tock tag [--once] <n> [<Category>[/<Project>]]   (no label: accept the → suggestion)
tock tag --span <id> <Category>[/<Project>]
tock ignore <n> | tock ignore --undo <key>
tock away [--date D] [<HH:MM> <Category>[/<Project>] | --skip <HH:MM>]
                                       label time away (idle or asleep) or leave it idle
tock edit [add | label | delete] <HH:MM-HH:MM> [<Category>[/<Project>] [note]]
                                       fix the timeline: add missing time, label part of it, delete some
tock edit [--date D] | tock edit remove <id>   list the day's edits | drop one
tock undo [--list]                     reverse the last tag, rule, ignore, away label or edit
tock web [--port N] [--no-open] [--idle D]
                                       the dashboard in your browser, served on 127.0.0.1
tock status                            one line for a status bar

Focus:
tock session [start [MIN] [--paper] [--goal TEXT] | stop]
                                       focus session: show, start (default 25; --paper: idle is paper work; --goal: what it is for), stop
tock session snooze [MIN|off]          snooze distraction notices of the running session (default [focus] snooze), or resume them
tock session list | weights            this week's finished sessions with quality and rating | the quality weights
tock session rate [#ID|last] N [note...]  rate a finished session 1 to 5, with a one-line note
tock session note [#ID] [text...]      set or (no text) clear a session's note
tock session refile [#ID|last] PROJECT  relabel a finished session's active time to a project (tock undo reverts)
tock break [MIN]                       take a break now (default 5 min)
tock goal [set <label> <time>[/week] [--max] | rm <label> [week] [--max]]
                                       goals per day or week, on a category or module
tock recap [YYYY-MM-DD|start|midday]   the daily recap, or a routine notice now

Rules and names:
tock rules check | tock rules stats [--days N]
                                       validate the rules | time each rule decided (default 30 days)
tock rules dupes | tock rules merge [--project] <from> <into>
                                       look-alike names | fold one name into another everywhere
tock category [add <name> <kind> [--afk D] |
              set <name> [--kind K] [--afk D] [--interrupt on|off] |
              rename <name> <new> | rm <name>]
                                       list or change your categories (rules.toml)
tock project [add <name> [--category C] [--alias a,b] [--rate N] | set <name> ... |
             rename <name> <new> | rm <name> | scan <dir> --category C]
                                       projects; filed under a category they are modules

Looking back:
tock top [--days N | --week | --month] [--by category|app|site|project] [--limit N]
                                       where the time went: top categories, apps and sites
tock commits [--days N | --week] [--project P]
                                       each commit with the project time behind it
tock agents [--days N | --week]        what coding agents worked on, and your time in their windows
tock budget                            each project budget: spent, pace and when it runs out
tock trends [--month YYYY-MM] [--hours]  a month against the one before; --hours: focus by weekday and hour
tock blocks [--date D]                 the day's work blocks: stretches of work on one thing
tock review [--week YYYY-MM-DD] [--plan TEXT]
                                       weekly recap, then next week's focus
tock report [--week YYYY-MM-DD] [-o FILE] [--open]
                                       the week as one HTML page to keep or mail
tock export [--from D] [--to D] [--format csv|json] [--by project]
                                       labelled spans, default the last 7 days as csv
tock model [why <app> "<title>" [<label>]]
                                       how well the local model labels; why it labels a window so

Setup and data:
tock init                              write starter ~/.config/tock/rules.toml
tock doctor [--wait] [--open] [--deep] [--json]
                                       check trackd, permissions, rules, config and snapshots;
                                       --deep: a full check of the database
tock bug-report [-o FILE] [--include-rules]
                                       a file to attach to an issue, without titles or URLs
tock update [trust <fingerprint>]      Linux: the key trusted for the Mac's builds; trust one
tock version                           the version of this build
tock choice [<feature> on|off]         turn features on and off (screen text, wake screen, Slack…),
                                       open the dashboard; piped: each feature and whether it is on
tock backup [--out FILE]               archive tock.db and the rule, config and shell files
                                       (default ~/.local/share/tock/backups/)
tock restore [<n|path> [--yes]]        list snapshots of the database, or put one back
                                       (stops and starts trackd)
tock stop | tock start                 stop recording until tock start or your next login
tock prune [--days N] [--dry-run]      delete window titles (and URL paths) older than N days
                                       (default [privacy] keep_titles); labels stay
tock import activitywatch <export.json>
                                       ActivityWatch history (Export all buckets, or
                                       curl localhost:5600/api/0/export); again replaces it
tock setup [--check] [--no-doctor]    after brew install: make the signing certificate, install
                                       and start trackd and the menu bar app (safe to run again)
tock setup --template NAME[,NAME] [--past] [--yes]
                                       NAME: developer, designer, writer, client, own;
                                       add the categories and rules a template has and you lack;
                                       they label from now on unless --past (tock undo takes back)
tock uninstall [--purge]              stop trackd and the menu bar, remove the apps and tock;
                                       --purge also deletes your data, rules and config
tock shell-init zsh                    shell hook for terminal projects; in ~/.zshrc:
                                       eval "$(tock shell-init zsh)"

Extras (optional; some need a setting, Claude or Slack):
tock plan                              the TUI on the plan tab ([plan] todo.txt); piped: the open tasks
tock suggest [--dry-run | --force]     Claude label suggestions for the inbox (claude CLI or ANTHROPIC_API_KEY)
tock summary [--date D] [--dry-run]    what you worked on: Claude writes it, else the work blocks
tock ask [--dry-run] "<question>"      ask about your time in plain words; answered on this machine
tock recommend [accept | dismiss]      the pending suggestion: show it, take it, or not now
tock ocr test [--now] | grant          read the front window's text once (in 3 s) | ask for Screen Recording
tock invoice --project P [--from D] [--to D] [--client NAME] [-o FILE]
                                       preview an invoice from the project's rate (DRAFT PDF; default last month)
tock invoice issue|void|list|show|check|verify|recover …
                                       issue and keep invoices (tock invoice help)
tock sync [--days N]                   write this machine's last N days (default 2) to the
                                       [sync] folder now and read the other machines'
tock slack [login | logout | status]   Slack status and do-not-disturb during focus sessions

Names match on a unique prefix: tock tag 2 stu/atl. /Project sets only the project.

The export has one row per span: id,start,end,duration_s,app,bundle_id,title,url,private,category,kind,project,category_source,project_source,rate,amount. Times are RFC 3339 with your local offset. rate and amount are empty (null in JSON) unless the row’s project has a rate (see Billing).

Choices

tock choice lists the features you can turn on and off, by group. Three groups have a switch of their own, on by default:

Turning a group off turns its members off without touching their own settings: they show on (waits for Focus) and come back as they were when the group is on again. Nothing is deleted. With Focus off there is no focus tab in the TUI, no score or session in the dashboard, the menu bar or the notch, and trackd starts no session, guard or break notice; a session running when Focus goes off ends as if you stopped it. With Billing off the dashboard shows no rates or invoice preview, exports carry no rate, and tock invoice issue refuses; tock invoice list, show and check still work on what you issued. Tracking and labelling are the same whatever the groups say.

The other features have no group: local model labels, notifications and the notch; Claude; calendar meetings, screen text and Slack. Space turns the feature under the cursor on or off, enter saves, q quits (changes not saved are said so). Each one is a setting in config.toml ([ocr] enabled, [focus] break_screen…); tock choice changes that line only and keeps your comments and every other line, and the old file stays as config.toml.bak. The running apps pick the change up by themselves.

Turning screen text on asks for the Screen Recording permission; turning Slack on with no token tells you to run tock slack login.

The last row, Open dashboard, starts the web dashboard and opens it in your browser after asking (Open, Not now, or Always to stop asking). It stops after 30 minutes unused.

Not on a terminal, tock choice prints each feature and whether it is on; tock choice <feature> on|off sets one, for scripts and SSH:

$ tock choice break_screen on
Break screen: on
$ tock choice focus off
Focus: off

A group is one key ([focus] enabled, [routine] enabled, [billing] enabled). Turning it off writes enabled = false; turning it on again removes that line, so the file is as it was.

Files

Path What
~/.config/tock/rules.toml your categories, projects and rules; first match wins
~/.config/tock/learned.toml rules written by tock tag, checked before rules.toml
~/.config/tock/config.toml optional settings, see below
~/.config/tock/slack.token the Slack token, when you use Slack
~/.local/share/tock/tock.db the spans (SQLite)
~/.local/state/tock/trackd.log trackd’s log
~/.local/state/tock/*-crash.log crashes of trackd, tock and the menu bar app, if any: the panic and its stack, written by the program as it dies; empty when nothing crashed. A file over 256 KB is moved to .1 at the next start
~/.local/state/tock/shell.log working directories from the shell hook, see docs/shell-hook.md
~/.local/state/tock/agents.index times, directories and titles read from coding agents’ session logs (see Agents); safe to delete

TOCK_CONFIG_DIR, TOCK_DATA_DIR and TOCK_STATE_DIR override the three directories.

config.toml sections. All keys are optional and the values below are the defaults:

[focus]
enabled = true           # the Focus group; false turns sessions and every focus feature off
presets = [25, 50, 90]   # session lengths in minutes; the first is the default
break_after = 50         # minutes of focus before a break reminder
break_repeat = 10        # minutes between reminders
distract_grace = 60      # seconds on a distraction before a nudge
distract_repeat = 120    # seconds between nudges
snooze = 10              # minutes a snooze holds distraction notices back (1 to 240)
urge_surf = false        # the distraction notice asks you to pause and counts your answer
auto_min = 25            # minutes of deep work that count as an unplanned session
recap = "21:00"          # daily recap notification, "" to disable
notify = true
notice_budget = 8        # nudges a day tock sends unasked (break, away, start, midday,
                         # overworking, suggestions); 0 = no limit (0 to 100)
notice_gap = 20          # least minutes between two nudges; 0 = none (0 to 240).
                         # Nudges wait out calls and meetings; session, Break over,
                         # plan and recap notices are never held back
break_screen = false     # a break you took that runs over covers the screens until
                         # you click Back to work or 5 more minutes, or press Esc;
                         # never locks, never during a call, not once back at deep work
break_screen_grace = 5   # minutes past the break's end before it shows (1 to 60)
wake_screen = false      # a session gone off task (distraction, browsing, long idle)
                         # gets a banner at wake_warn minutes, then covers the screens
                         # at wake_after: Back to work, This is work (files the site
                         # under your work label; tock undo takes it back), I'm on
                         # paper (idle stops counting), Snooze, End session. Two a
                         # session at most; never during a call; Esc closes it
wake_warn = 5            # minutes off task before the banner (1 to 60)
wake_after = 10          # minutes off task before the screen, and between two (2 to 120)
wake_idle = 15           # minutes idle before idle counts as off task (1 to 120)
hotkey = true            # ⌥⌘F from any app: what you are working on and how long,
                         # then start (Stop or Keep going while one runs); menu bar app
# meeting_apps / meeting_hosts replace the built-in lists of meeting apps
# (bundle ids) and hosts during which break and distraction nudges stay quiet
block = false            # close distracting tabs and hide distracting apps in sessions
block_apps = []          # bundle ids (window classes on Linux) blocked besides distractions
block_hosts = []         # sites blocked besides distractions; subdomains too
block_grace = 10         # seconds a distraction may stay in front
focus_on = ""            # Shortcuts shortcut run when a session starts
focus_off = ""           # ... and when it ends

[hours]                  # off unless set; see Work hours
days = ["mon", "tue", "wed", "thu", "fri"]
start = "09:00"          # start and end are both required
end = "18:00"
over_grace = 30          # minutes of work past end before the overworking notice (5 to 240)
over_repeat = 60         # minutes between overworking notices while you keep going (15 to 480)

[inbox]
min_minutes = 2          # a key needs this much time in the window for its own inbox row; 0 lists all (0 to 60)
auto_accept = 85         # % a same-site or same-app guess needs to be applied without asking; 0 = off (60 to 100)

[routine]                # notices that mark the day; see Routines
enabled = true           # the Day routine group; false turns every routine notice off
start = true             # start of day notice on the first activity of a work day
midday = "13:00"         # midday check-in time, "off" to disable
end = true               # false turns the recap notice off whatever [focus] recap says
overwork = true          # overworking notice past the end of the work hours

[recommend]              # focus suggestions and the adaptive break; see Recommendations
enabled = true           # false: no suggestions, and the break reminder is the plain one
max_per_day = 2          # focus suggestions a day (0 to 10, 0 = none)
adaptive_break = true    # break reminder after your usual focus stretch
min_days = 7             # active days of the last 28 the profile needs (3 to 28)

[ocr]                    # read on-screen text of unclear windows, on this Mac only; see Screen reading
enabled = false          # off unless set
apps = ["com.apple.Terminal", "com.googlecode.iterm2", "com.mitchellh.ghostty", "net.kovidgoyal.kitty", "com.github.wez.wezterm", "com.apple.Preview", "net.sourceforge.skim-app.skim", "com.readdle.PDFExpert-Mac", "net.ankiweb.launcher", "com.apple.Safari", "com.google.Chrome", "org.mozilla.firefox", "company.thebrowser.Browser", "app.zen-browser.zen"]
interval = 60            # seconds between reads of one window (15 to 3600)
min_dwell = 20           # seconds a window stays in front before its first read (5 to 300)
deny_apps = []           # bundle ids never read, on top of [llm] deny_apps
deny_hosts = []          # RE2 patterns on the URL host, on top of [llm] deny_hosts
deny_titles = []         # RE2 patterns on the title (any case), on top of [llm] deny_titles

[notch]                  # the menu bar app's panel in the notch; see The notch
enabled = true           # false: banners instead, as before
show_in_recordings = false # true lets screen sharing and recordings see it
all_displays = true      # a notch on every display; false: only the built-in one
open_on_hover = false    # true: resting the pointer opens it, no click needed

[model]                  # the local model; see The model
enabled = true           # false: no model labels, only rules and tags

[privacy]
keep_titles = 30         # off unless set: days window titles are kept
hide_apps = []           # bundle ids recorded as private time only: no title, no URL
hide_sites = []          # hosts recorded the same way; subdomains too

[backup]
keep = 7                 # daily copies of tock.db trackd keeps; 0 = none

[billing]
enabled = true           # the Billing group; false hides rates and stops tock invoice issue

[display]
week_start = "monday"    # or "sunday", "saturday": the first day of every week
clock = "24h"            # or "12h": times of day as 5:20pm instead of 17:20
date = "dmy"             # or "mdy" (Tue Nov 3), "iso" (Tue 2026-11-03); dmy is Tue 3 Nov
numbers = "1234.5"       # or "1,234.5", "1.234,5", "1 234,5", "1234,5": decimals and grouping

[invoice]                # for tock invoice; all optional
name = "Your Name"
address = ["1 Main Street", "City"]
tax_id = ""              # your tax or VAT number
currency = "EUR"         # a code or a symbol, printed with amounts; "" by default
note = "Payment within 30 days."
round = "1s"             # round each day's time, e.g. "6m" or "15m"; "1s" = none
round_mode = "nearest"   # or "up"; nearest rounds a half step up
minor_units = 2          # decimals of amounts, 0 to 3
currency_position = "after" # or "before": €1234.50 instead of 1234.50 EUR
# date = "dmy"           # or "mdy", "iso" for new invoices; unset: [display] date, else iso
# numbers = "1.234,5"    # as [display] numbers, for new invoices; unset: [display] numbers
tax_label = ""           # e.g. "VAT"
tax_rate = ""            # a percentage such as "20" or "5.5"; none = no tax line
tax_note = ""            # e.g. "Reverse charge"

[[invoice.client]]       # details for a project's client = "Acme"; repeat per client
name = "Acme"
address = ["2 Road", "Paris"]
tax_id = "FR123"

[slack]                  # see Focus guard
enabled = false
status = "In a focus session"
emoji = ":dart:"
dnd = true               # pause Slack notifications for the session

[llm]
enabled = true                # default false: Claude is opt-in; still needs Claude Code (claude) or ANTHROPIC_API_KEY
model = "claude-haiku-5-5"
min_minutes = 2               # inbox time a key needs before it is sent
deny_apps = []                # bundle ids added to the built-in deny list
deny_hosts = []               # host regexes added to the built-in list
deny_titles = []              # title regexes

[shell]
terminals = [...]             # bundle ids that get shell dirs; replaces the built-in list
agents = true                 # coding agents' session logs give terminal dirs too (see Agents)

[away]                        # which absences tock asks about
min = 10                      # minutes; at least 5
max = 240                     # minutes; at most 720

[afk]                         # when time in front of an app stops counting, see AFK
video = 180                   # minutes without input while a video plays; trackd reads it at start
stale = 20                    # minutes; see "Machines that report no input"
trust = 180                   # minutes; the longest unchanged window hypridle is trusted with

[calendar]                    # meetings from macOS Calendar, see Calendar
enabled = false               # true: trackd asks for calendar access once
calendars = []                # calendar names to read; empty = all
auto_open = false              # open a Meet/Zoom/Teams link by itself when its event starts

[score]                       # weights of the focus score; they sum to 1
depth = 0.5                   # "deep time": focus against your target
blocks = 0.3                  # "long blocks": time in blocks of 25m or more
calm = 0.2                    # "few switches": app switches an hour, none at 20
stretch = 0.0                 # "longest run": longest run without a switch, full at 1h30

# [plan] and [sync] are under Plan and Sync between machines.

Plan

The plan tab (6, or tock plan) shows a todo.txt file by day: Overdue, Today, Tomorrow, Later, No date, and what you ticked today. Inside a day, tasks go by the time in a context (@07h30, @mon-07h30, @07:30). Ticking writes x DATE and keeps the priority as pri:A; unticking puts it back. A future t:YYYY-MM-DD hides a task until that day. Piped, tock plan prints the open tasks.

[plan]
file = "~/todo.txt"
# optional: run when the tab opens, after each change and once a minute
command = "my-planner --tock"
notify = true        # upcoming and starting-now notices for timed plan items and calendar events
notify_before = 5    # minutes ahead; 0 = no upcoming notice (0..60)
auto_start = false   # a module-tagged plan item starts a focus session of its slot length

The last three keys make timed tasks announce themselves, see Planned sessions and meetings.

The command gets TOCK_PLAN_FILE and may rewrite the file (a planner that rolls missed tasks over, imports ticks). Its output shows above the list: plain lines, or JSON {"lines": ["…"], "seen": {"project": seconds}}, where seen puts the time you spent on a +project next to its first open task today. Edits re-read the file and find the line by its text, so a command rewriting the file never makes hourdial tick the wrong task.

Focus guard

A focus session can do more than nudge you.

Focus level. While a session runs, the focus tab, the menu bar and tock session show focus 84% ↗ next to deep 62%. Deep % is the session’s record: deep time over its length so far. The focus level is how focused you are now: deep work counts fully, light or unlabelled work half, browsing a quarter, distraction and time away nothing, and a glance away under a minute between deep work is forgiven. Recent minutes weigh most (half as much every five minutes back), so after a drop the level climbs back as soon as you settle in again: five focused minutes win back half the gap. ↗ or ↘ shows where it moved in the last minute.

Blocking. With block = true under [focus], a distraction that stays in front for 10 seconds (block_grace) during a session is taken away:

A distraction is time whose category has kind = "distract", plus the apps in block_apps and the sites in block_hosts. Nothing is blocked during a call or a meeting, and Finder and hourdial never are. A notification names the app, never the site. Closing a tab uses the same Automation permission trackd already has for reading URLs.

Answering a distraction notice. The notice has buttons (Options in Notification Center). The menu bar offers the same snooze while a session runs.

Focus mode. macOS has no command for Focus, but Shortcuts does. In the Shortcuts app, make a shortcut named Focus On with the action Set Focus (Do Not Disturb, or your Work focus, On), and a Focus Off shortcut that turns it off. Then:

[focus]
focus_on = "Focus On"
focus_off = "Focus Off"

trackd runs them when a session starts and when it ends, whether you started it in the TUI, the menu bar or tock session. tock doctor checks that both shortcuts exist.

Slack. hourdial can set your Slack status and pause Slack notifications for the session:

  1. Create a Slack app for your workspace at api.slack.com/apps, add the user token scopes users.profile:read, users.profile:write and dnd:write, install it and copy the user token (xoxp-…).
  2. tock slack login and paste it. It is stored in ~/.config/tock/slack.token (owner-only); TOCK_SLACK_TOKEN overrides it.
  3. [slack] enabled = true in config.toml. tock slack checks the token.

The status expires on its own at the planned end. When the session ends, hourdial clears it only if it is still hourdial’s status, so a status you set yourself in the meantime stays. trackd never talks to the network itself: it runs tock slack start and tock slack stop.

Goals

[[goal]] tables in rules.toml set goals (at_least) and limits (at_most) per day or week, for a category, a project or both:

[[goal]]
category = "Study"
at_least = "2h"
per = "day"            # the default; or "week" (Monday to Sunday, see week_start)

[[goal]]
project = "tock"
at_least = "10h"
per = "week"

[[goal]]
category = "Entertainment"
at_most = "45m"

The today tab and tock today show a goals line, the week tab shows each goal over the week (met 3 of 5 days for a day goal), and tock status adds goals 2/3 plus over Entertainment when a limit is passed. tock rules check lists the goals.

You don’t have to edit the file. tock goal set ana1 6h/week sets a goal on a module (by name or other name), tock goal set Entertainment 45m --max sets a limit, tock goal rm ana1 week removes one, and tock goal lists them with this week’s progress. On the labels tab, o (or a click on a row’s goal) sets a module’s weekly goal or a category’s daily one. The week tab has a Modules bar per module, filled out of its weekly goal (“1h40 of 6h00 · 4h20 to go”); click one to change its goal.

Each goal keeps a streak: days in a row it held (met, or under a limit), or weeks for a week goal. Days with no activity and days off (see Work hours) neither count nor break it. Today counts once a goal is met; a limit counts once the day’s hours are over, and breaks the streak as soon as it is passed. The goals line shows · 5d from two days on, the week tab and tock review add streak 5d (best 12d), and the dashboard shows 5d streak.

Work hours

With [hours] in config.toml, the focus score only looks at your work hours:

[hours]
days = ["mon", "tue", "wed", "thu", "fri"]   # the default
start = "09:00"
end = "18:00"

trackd still records everything, and totals, categories and goals still cover the whole day; only the score, the focus numbers and the adaptive target are limited to the hours. A day not in days is a day off: it is not scored and the target skips it. tock today adds 09:00–18:00 and 1h20 outside hours to the score line (or says day off · not scored), and the today tab and dashboard show the same.

The recap closes the day: it goes out when the hours end, unless [focus] recap sets its own time, and is skipped on days off.

The overworking notice (see Routines) uses end. over_grace and over_repeat alone do not turn the schedule on.

Routines

trackd marks the day with up to four notices.

Start of day comes with the first activity of a work day, once a day, even if trackd restarts. It looks back and ahead:

Yesterday: 6h12 tracked, score 74, goals 2/3 met. Today: 10:00 Standup.

The “Today” part lists the timed items of your plan file.

Midday check-in comes at [routine] midday (13:00 by default). It is skipped once the work hours have ended, or more than 3 hours after its time.

3h05 tracked, 64% of 4h50 target · top: Coding · focus 1h40.

The recap is unchanged: it comes at [focus] recap, or when the hours end.

Overworking needs [hours]. It comes once you have worked over_grace minutes past end and are still active, and repeats at most every over_repeat minutes while you keep going. If you stopped before the grace ran out, it never comes.

Past work hours: 9h40 tracked today, 1h05 after 18:00. Time to stop.

Switch each one off in [routine]: start = false, midday = "off", end = false (the recap notice), overwork = false. The notices wait until a call or meeting ends, and they have no buttons. [focus] notify = false silences all of them. Days off (outside [hours] days) get no start of day, midday check-in or overworking notice.

tock recap start and tock recap midday print what the notice would say now.

Time away

An absence is idle time, or time with no record at all (asleep, locked), between two stretches of activity: 10 minutes to 4 hours by default ([away] in config.toml). When you come back, trackd sends one notification. Label the absence with a on the today tab, t on its idle row, or tock away 12:10 Meeting; A or tock away --skip 12:10 leaves it idle. When the time before the absence had a label (often reading with no input past its AFK window), hourdial asks whether you were still on it: y, the notification’s first button or tock away 12:10 same gives the absence that label. A labelled absence counts towards totals and goals, but not towards focus blocks, context switches or break reminders. Absences that cross midnight are never asked about.

When trackd was not recording

trackd notes once a minute that it is running, whether or not anything is in front, and why it stopped when it stops. Time it should have recorded and did not shows as not recording, with the reason: a line under the day in the TUI, a lane under the timeline in the dashboard, and a “Not recorded” line under the week’s bars.

When trackd stopped that way and the computer restarted before trackd ran again, the time up to the restart is shown with (until the restart; the computer may have been off for part of it): nothing records when the computer went off, so hourdial does not hide that time.

Logging out, restarting and shutting down are not “not recording”: as trackd stops, macOS (loginwindow, or kern.willshutdown for shutdown and reboot) or systemd (the user service manager stopping) says the session is ending, and trackd notes it. A stop with no such word is treated as a stop by hand.

Apps only. While trackd has no Accessibility permission it still records which app is in front, but not window titles. That time shows apart, as apps only, and does not count as “not recorded”.

Sleep, a locked screen and nothing in front are not “not recording”. Gaps under a minute are not shown. This time is never counted as tracked or idle; the time-away prompt still covers it, so you can label what you did. hourdial has no record of trackd before this version, so older days show nothing here.

Categories

Categories are yours: rules.toml declares them, and tock category changes them without opening the file.

tock category                              each category, its projects and 30 days of time
tock category add Podcasts neutral --afk 30m
tock category set Reading --kind deep      or --afk 15m, --afk none
tock category set Entertainment --interrupt off   no distraction notices for it (on undoes)
tock category rename Communication Messages
tock category rm Podcasts                  only when nothing names it

A rename reaches everything: both rule files, goals, [calls], projects filed under the category, and in tock.db the time you tagged by hand, away labels and timeline edits. To fold one category into another, use tock rules merge. Every change keeps the previous file as rules.toml.bak.

Each category has a kind:

kind what it is counts as
deep focused work focus blocks and the score’s depth
shallow email, planning, looking things up work, not focus
neutral utilities, reading for pleasure neither
browse search, feeds, shopping a third of it weighs on the score like a distraction; never nudged or blocked
distract entertainment the score’s penalty, nudges and blocking in sessions

The starter rules have Reading (neutral, for books and long reads), Research (shallow: encyclopedias, papers, dictionaries) and Browsing.

Templates

A fresh tock setup asks what the computer is for and applies one or more templates on top of the starter rules:

template adds
developer IDEs, terminals and dev tools beyond the starter’s, docs and package sites, localhost (Code, Research)
designer Figma, Sketch, Adobe, Affinity, Blender, GIMP, Inkscape, design files in the browser (Design), reference sites (Research)
writer iA Writer, Ulysses, Scrivener, Word, Bear, Typora, Zotero, dictionaries (Writing, Research)
client Code, Meeting, Admin & Planning: editor, call and invoicing apps
own Code, Writing, Research: editor, writing and reference apps

Off a terminal, or with --no-prompt, setup applies own. Pick one without the question, on a fresh install or later, the same way:

tock setup --template developer --yes  starter rules (if none yet) plus the pack
tock setup --template client          shows the plan, asks, applies
tock setup --template client,own --yes
tock setup --template own --past      also label past days (the plan says how much)

A template only appends what you lack, after your own text, behind a # from template "client work", 2026-11-20 comment. Your categories keep their kind, your rules stay first and win, and applying again changes nothing. Its rules carry since = <now>, so the days before keep their labels; --past leaves since out after showing what it would relabel. tock undo takes an apply back. Templates never write config.toml: if the template’s group (Billing, Focus) is off, the plan says how to turn it on.

Rules from a date

Any rule can start on a date with since. It then labels only time from that moment on, and the time before keeps whatever labelled it:

[[rule]]
url = 'github\.com/acme'
project = "Acme"
since = 2026-11-20T14:05:00     # local time; 2026-11-20 means midnight

tock rules stats and the dashboard’s Rules view show the date.

The model

Rules see the app and the site; the title often says more. A small classifier, trained on this machine from the labels you already have, reads the title too. It never sends anything anywhere.

tock model                                 how often it is right on labels it did not see
tock model why chromium "Apprendre à conjecturer - Chromium" [Entertainment]
                                           the categories it sees, and the words behind them

[model] enabled = false in config.toml turns it off.

Modules

A project filed under a category is a module: a course, a client, a side project, whatever groups your time inside that category.

[[project]]
name = "Analyse 1"
category = "Study"
aliases = ["ana1", "Nombres réels", "Suites numériques"]
tock project scan ~/Licence/S1 --category Study   a module for each folder
tock project add Thermodynamique --category Study --alias thermo
tock project set ana --alias ana1,AF               --category none unfiles it
tock project rename "Analyse 1" "Analyse I"
tock project refile Licence                        hand tags of a catch-all go to the module in their title
tock project                                       categories with their modules

A module named in a window title also wins over the label another machine synced for it, so an older machine with a catch-all project can’t undo your modules.

Projects without a category work as before: rules set them, and they can list repos and a rate.

AFK

Time counts while you are at the machine. trackd notices when there has been no key or mouse input for 5 minutes, and the time since your last input becomes idle. Some things need longer: give a category its own window in rules.toml:

[[category]]
name = "Reading"
kind = "deep"
afk = "10m"          # 5m to 2h; the default is 5m

A pause shorter than the window of what was in front stays with it: eight minutes on one page of a book is still Reading. A longer one is AFK, and all of it, back to your last input, is idle. This is decided when hourdial reads the day, so changing afk changes past days too.

While a video plays in the front app (it keeps the display awake), trackd waits [afk] video minutes (3 hours by default) before it goes idle. Music does not count. During a call you are never AFK (see Calls).

Machines that report no input. On Hyprland and Sway trackd only learns about input through the hypridle or swayidle hook (see Linux); X11 and i3 report it themselves. Without it, and for another machine whose sync folder doesn’t say it reports input (an older hourdial), hourdial guesses: one window left unchanged for longer than [afk] stale minutes (20) keeps its category’s window and the rest is idle. A page turn in a PDF reader changes the title, so reading still counts. tock doctor names those machines.

tock today says what did not count: · 7h18 cut (no input) for windows cut by these rules, · 47m to other machines for time you spent on another machine while a window stayed open here (see Sync between machines).

hypridle (or swayidle) can miss idle even when it is hooked in: it stops, crashes or is held off by a player. So on Linux, and for another machine whose sync folder doesn’t say its input comes from macOS, one window left unchanged for longer than [afk] trust minutes (180) keeps its category’s window and the rest is idle. A Mac’s own input is always trusted. trackd also checks on every sync whether hypridle still runs; while it doesn’t, the machine reports no input. tock doctor names a machine whose windows ran over [afk] trust in the last 7 days.

Editing the timeline

What trackd recorded never changes; edits sit on top of it and every view uses them (today, the week, the score, goals, the inbox, exports).

--date YYYY-MM-DD edits another day, and the end may be now. tock edit lists the day’s edits and tock edit remove <id> drops one. When edits overlap, the newest wins. In the TUI’s today tab, s splits the row (type where the labelled part starts and ends), d deletes the row’s time and + adds time (an idle row’s range is filled in); t on an entry relabels it. In tock web, click a bar or drag across the timeline to pick a range: the sheet shows its times (type to change them) and Label, Add entry or Delete. Add time above the timeline adds an entry.

Undo

tock undo reverses the last change: a tag, a learned rule (learned.toml goes back as it was; hourdial refuses if you edited the file since), an ignore, a label for time away, or a timeline edit. Run it again to go further back; tock undo --list shows the last 20 changes. u does the same in the TUI and in tock web. hourdial keeps the last 200 changes. tock rules merge is not in the list: it keeps rules.toml.bak instead.

Work blocks, summaries and questions

A work block is a stretch of work on one thing: a project, else a category. A break of 10 min ends a block, and so does other work that lasts 10 min; shorter detours stay inside the block around them. Blocks under 15 min are not listed. tock blocks lists the day’s blocks with their focus share and top apps; the TUI’s today tab shows them on the work line and tock web in the Work blocks card.

tock summary asks Claude what the day was about and saves one line for the day and one per block. Every view shows them from then on (the ✎ line in the TUI). Run it again to replace them; --date summarizes another day. Without Claude, it prints the day’s work blocks instead, which say what, where and for how long without leaving your machine.

tock ask "how much video last week?" answers questions about your time: totals by category, project, app, site, kind or day, over a range. Claude only turns the question into a query; hourdial runs it on your data.

Both need Claude turned on (tock choice claude on) and Claude Code (the claude command, logged in) or ANTHROPIC_API_KEY; see Privacy for what they send.

tock trends (and m on the week tab) compares a month with the previous one: the whole month for a past month, the same days so far for the current one. It shows tracked and focus time, the average workday score with a daily sparkline, switches per hour and each category’s change. For the current month it ends with what hourdial learned about you: see Recommendations.

tock review recaps a week (this week on its last two days, the weekend for a Monday week, else last week): totals, each goal, the top distractions and the best day. It then asks for next week’s focus, or takes --plan. The week tab shows the plan of the week on screen. Plans stay in tock.db.

Weeks start on Monday. week_start = "sunday" or "saturday" under [display] in config.toml moves the first day everywhere a week is counted or drawn: the week tab and the dashboard, tock review, tock report, --week on tock top, tock commits and tock agents, week goals and their streaks, focus sessions of the week, tock ask about this or last week, and the notch’s week page. A week’s plan is saved under its first day, so plans written before a change show up in the week that starts on that day only.

Times of day show on the 24-hour clock. clock = "12h" under [display] shows them as 5:20pm (hour marks as 5pm) in the commands, the TUI, the dashboard, reports, notices, the menu bar and the notch. Times you type, such as the range for tock edit or tock away, can be in either form. Exports, --json, logs, file names and the summary sent to Claude stay 24-hour.

Dates are written day first, Tue 3 Nov. date = "mdy" under [display] writes them month first (Tue Nov 3, Nov 3, 2026), and date = "iso" as Tue 2026-11-03. Decimals, such as switches per hour and the score breakdown, are written as 1234.5; numbers takes how 1234.5 should look: "1,234.5", "1.234,5", "1 234,5" or "1234,5". Both apply in the commands, the TUI, the dashboard, reports, notices and the notch, and to new invoices unless [invoice] sets its own (see Invoices). Day and month names stay English, and durations such as 7h39 do not change. Dates you type stay 2026-11-03. Exports, --json, CSV, logs, file names and the summary sent to Claude keep their fixed forms.

tock top ranks the last 7 days (or --week, --month, --days N): categories with their kind, apps and sites (URL hosts) with the category most of their time went to, each with its share of tracked time. --by project lists projects.

Web dashboard

The menu bar’s Open dashboard shows the dashboard in its own hourdial window. While the window is open hourdial has a Dock icon and a menu (⌘W closes it, ⌘R reloads, ⌘+ and ⌘− zoom and ⌘0 sets the size back; the window keeps the size you pick); closing it puts hourdial back in the menu bar only. Links that leave the page open in your browser. tock web serves the same page to your browser and runs until you press ctrl-c.

The sidebar has three groups. Ledger is what the time came to: Agents, Projects and Invoices. Record is the time itself: Timeline and Inbox. Setup is Rules. Agents and Projects take a range in the top bar: Day, Week, Month, or Custom for any days up to a year. Links to the old tabs (#today, #week, #trends, #top, #library) open the view that took them over.

The top bar’s date steps by the range: a day on Timeline, and a day, week or month on Agents and Projects; click it for a calendar, and Today (or t) comes back. Under the views in the sidebar, a focus box starts a session at one of your preset lengths, or counts down the running one and ends it; below that, whether trackd is recording (hover for when it last wrote) and whether rules.toml and config.toml load (click to fix them).

A new install has nothing to show, so it shows a sample day instead, under a line that says so: “Sample data. Your own day replaces it after your first hour.” The sample can’t be changed, exported or invoiced, and Rules and Settings stay your own. It goes as soon as hourdial has recorded anything.

Timeline opens on three cards: the whole day as a 24-hour dial (your time in kind colours, your work hours round the outside, a hand at now; click an hour to zoom the timeline there), the focus score, and a Focus card where you name what you are about to work on, pick a length and start (f puts the cursor there from anywhere). A running session shows its countdown ring and End session in that card instead. Under the cards, a row of next moves says what is worth doing about today: unlabelled time waiting in the Inbox, how much more reaches a goal, a limit nearly or already spent. Each one opens where you deal with it. Keys 1–6 switch views, ← → step the date, ⌘K opens a palette for views, dates, settings and the theme, and ? lists every key and gesture. Every change shows a toast with Undo. The page refreshes itself every minute.

The server listens on 127.0.0.1 only, on a free port (--port N to choose one). The link it prints carries a random token after the #. Browsers never send that part to a server, and the page keeps it for the tab only. Every request needs the token, so other sites open in your browser can neither read nor label anything, and requests that name another host are refused. The page, its styles, scripts and fonts are built into tock and load nothing from the internet. trackd is not involved. --no-open prints the link without opening a browser. --idle 30m stops the server after 30 minutes with no request; the menu bar’s Open dashboard uses it.

For working on the page: its source is in web/ (React, shadcn/ui, Recharts). With the demo server below running, cd web && npm run dev serves it with hot reload at http://localhost:5173/# followed by 64 zeros; make web tests it and rebuilds internal/web/static, which is committed so Go builds need no Node. TOCK_DEMO_PORT=7788 go test -tags demo -run TestDemo -timeout 0 ./internal/web serves synthetic data at http://127.0.0.1:7788/# followed by 64 zeros. cd web && npm run e2e (after npx playwright install chromium once) builds the showcase server, serves a month of made-up data from a temp folder, and runs axe-core on every view plus a few flows in headless Chromium, as CI does.

Duplicate names

tock rules dupes lists categories, and projects, whose names differ only by case, punctuation, & for “and”, a plural ending or a typo, with the time each labelled in the last 30 days. tock doctor mentions them. tock rules merge Studies Study (or --project) removes the first name’s table from rules.toml, renames it in rules.toml and learned.toml, and renames manual tags, away labels and suggestions in tock.db. The old rules.toml is kept as rules.toml.bak. A project with repos or a rate must have them moved by hand first. Merges and renames are logged at the end of rules.toml as [[renamed]] tables (kind, from, to), so your other machines follow them (see Sync).

Calls

trackd notices when a camera or microphone is in use, in any app. It only reads whether a device is running, so it needs no camera or microphone permission and records no audio or video, just start and end times. During a call, break and distraction nudges stay quiet.

A call is context, not an activity: what is on screen decides the label. With this table in rules.toml (the starter rules have it), calls of at least two minutes label the time that has no label of its own (including time you only listened and would otherwise be idle) and the time a call app or a Meet, Zoom or Teams page is in front. Chess, study or a video chat site your rules already label keep that label with the camera on.

[calls]
category = "Meeting"   # a declared category
# apps = ["us.zoom.xos", "com.apple.FaceTime"]   # call apps; default: the
#   common ones (FaceTime, Zoom, Teams, Discord, Telegram, WhatsApp, Skype,
#   Signal). [] for none.

A calendar event is more specific than a call: call time inside it is the meeting. A manual tag still wins. tock rules check says whether calls are labelled.

Commits

List a project’s local git repositories in rules.toml and hourdial counts your commits beside its time:

[[project]]
name = "tock"
repos = ["~/tock"]

The today tab and tock today show commits tock 4 · ATLAS 1, and the week tab and tock review show the week’s commits. hourdial runs git log --all --no-merges and counts only commits by the repo’s user.email, including ones fetched from another machine. It reads author times only and never fetches. tock doctor checks every repo.

tock commits puts each commit beside the time behind it: yours, the time labelled with its project since that project’s previous commit (idle left out, looking back at most 8 hours), and, when coding agents worked on the project then, theirs (see Agents). The last line is the time since each project’s last commit.

$ tock commits
                         you  agent
09:30  tock  a1b2c3d    30m    12m  Fix inbox count after undo
10:05  tock  e4f5a6b    35m    48m  Tidy score panel spacing
2 commits · 1h05 of your time behind them, 1h00 of agents'
since last commit  tock 35m

--days N and --week widen the range, --project P keeps one project. To show them, tock commits reads each commit’s short hash and subject; it prints them and keeps them nowhere.

Agents

tock agents is the agent ledger: what coding agents worked on and how much of it you sat through. It reads Claude Code’s session logs in ~/.claude/projects (nothing to set up) and files each session under the project whose repos hold its working directory.

$ tock agents --week
project   agent     you  prompts  sessions
tock       4h36    1h51       54         7
agents worked 4h36 · you 1h51 in their windows · 2.5× leverage

--days N and --week widen the range. The dashboard’s Agents view shows the same for a day, a week, a month or any days.

The sessions also label your terminal time. A terminal window whose title holds a session’s title, in front while the session ran, works in the session’s directory, and a directory inside a project’s repos gives the project (below your rules and tags, like a shell hook directory does). agents = false under [shell] in config.toml turns that off.

hourdial reads each entry’s type, time and directory and the session’s title, never the text of a prompt, reply or tool result. It keeps those in agents.index in its state folder so the next run reads only new lines; delete the file to read everything again.

Budgets

Give a project the time it may take, and tock budget shows how much is gone and when the rest runs out at this week’s pace:

tock project set ATLAS --budget 40h --budget-since 2026-11-01
$ tock budget
ATLAS    31h20 / 40h      78%  ███████████████░░░░░  2h10/day · runs out Thu 19 Nov
tock      9h05 / 8h      113%  ████████████████████  over by 1h05

It writes budget = "40h" and budget_since = "2026-11-01" under the project in rules.toml. Without budget_since the budget counts all recorded time. The pace is the project’s average a day over the last 7 days; under a minute a day gives no run-out day. --budget none drops it.

The dashboard’s Projects view and Timeline show each budget as a bar. When a project reaches 80% of its budget, and again when it runs out, the menu bar app (or a plain notification) says so, once for each; changing the budget or its start date lets it speak again.

Billing

Give a project an hourly rate and tock export bills its time:

tock project set ATLAS --rate 80     # or: tock project add ATLAS --rate 80

That writes rate = 80 under the project in rules.toml; the dashboard’s Rules view does the same. --rate none drops it.

Each span row gets rate and amount (rate × hours, to the cent). tock export --by project --from 2026-10-01 --to 2026-10-31 writes one row per project instead: project,duration_s,hours,rate,amount, with the amount computed from the total time. Time without a project is left out. tock export has no currency: amounts are in the rate’s unit.

A project bills when it has a rate. --billable false (billable = false) keeps the rate but bills nothing (its time gets no amount in export, and invoices refuse it). --client Acme (client = "Acme") names who its invoices go to.

[[project]]
name = "ATLAS"
rate = 80
client = "Acme"

Invoices

tock invoice --project ATLAS previews last month’s invoice: it prints the days, hours and totals, and writes a PDF marked DRAFT to a temporary file (or -o FILE). Nothing is stored. --from and --to pick other days, --client names someone other than the project’s client.

tock invoice issue --project ATLAS (same flags) issues it, once [invoice] name is set (the preview says when it isn’t: an issued invoice never changes, so one without your name would only be voided):

An issued invoice never changes. Editing rules, retraining the model, relabelling time, a new rate or a new address change nothing in it: tock invoice show 2026-0004 prints what was issued: days, hours, rate, totals and the PDF’s hash. --json prints the stored record byte for byte, then its status; --pdf writes the PDF as it was issued (-o FILE, else to stdout). The database refuses any other change to it, from hourdial or anything else using SQL. It does not stop someone editing the file, restoring an older copy or a disk fault; tock invoice verify notices those (exit 4) by comparing each invoice with the hashes stored when it was issued and with its files.

To correct one, void it and issue a replacement:

tock invoice void 2026-0004 --reason "wrong client"
tock invoice issue --project ATLAS --supersedes 2026-0004
# or both at once:
tock invoice issue --project ATLAS --supersedes 2026-0004 --void-old --reason "wrong client"

Both stay on record, linked both ways in tock invoice list [--year Y]; a number is never used twice.

Time on an issued invoice is underlined on the dashboard’s timeline, and the week says how much of it is billed. Relabelling it, with tock tag, tock edit, the TUI or the dashboard, works as usual and says On invoice 2026-0004; the invoice stays as issued.

tock invoice check 2026-0004 bills the invoice’s days again with today’s labels, the invoice’s rounding and its rate, and prints issued 40.00 h / now 41.50 h with the days that differ (exit 3; 0 when nothing differs).

Rounding is per day: with round = "15m", 61 minutes bill 60 (nearest) or 75 (round_mode = "up"). Amounts are exact: a rate of 95.50 for 3 h 20 min is 318.33, rounded half away from zero; a rate with more decimals than minor_units is refused by tock rules check. Tax is one rate per invoice, on the subtotal. Your name, address, tax number, currency and note come from [invoice], the client’s address and tax number from [[invoice.client]]; all of it is copied into the invoice when it is issued.

Amounts are written 1234.50 EUR and dates 2026-11-03, as on every invoice so far. Under [invoice], currency_position = "before" puts the currency first: a symbol right before the number (€1.234,50), a code with a space (MAD 1 234,50). date ("dmy", "mdy", "iso") and numbers (as under [display]) set how dates, amounts, hours and the tax rate are written; left out, they follow [display] date and numbers, and with those unset too the invoice looks as before. minor_units = 0 suits currencies without cents, such as JPY, and 3 those with three, such as KWD; amounts are rounded in those units, never through floating point. The layout is stored with the invoice when it is issued: changing these settings later changes only new invoices, and tock invoice show, list and the dashboard print each invoice the way it was issued.

If invoice files go missing, any tock invoice command and tock doctor write them again from the database. After restoring an older copy of the database, tock invoice recover imports the invoices whose files are there but not in the database.

Numbers and fields are sensible defaults, not any country’s invoicing rules. The PDF is plain A4 in Helvetica; characters outside Western European alphabets print as ?.

Week report

tock report writes a week as one HTML page to stdout: tracked time, average score, each day with its score, focus and a bar by kind, categories, projects, apps and sites, distractions, goals with streaks, the plan and commits. It defaults to the week tock review shows; --week D picks another. -o week.html writes a file and --open opens it in the browser. The page has no scripts and loads nothing, so it can be mailed or archived as it is; window titles never appear in it. The dashboard’s week view has the same page under Export, next to the week’s entries as CSV or JSON and its hours by project (what tock export and tock export --by project write). In the hourdial window a save sheet asks where each file goes.

Deleting old titles

[privacy]
keep_titles = 30

Once an hour trackd deletes the window titles of activity older than 30 days and cuts its URLs to the host (mail.google.com/mail/u/0/#inbox becomes mail.google.com). Each span keeps the category and project its rules gave it, so no report changes; a later rule on the app or the URL host still fills a label it had left empty. Other machines’ activity and this machine’s own files in the sync folder older than that are cleaned too. tock prune --dry-run counts what would go, tock prune does it now and tock prune --days 7 uses another age once. Saved Claude summaries (tock summary) are kept. Deleted titles cannot be brought back, except from a backup made before.

Calendar

Calendar events can label the time you spend away from the Mac in a meeting. hourdial reads them through macOS Calendar, so a Google Calendar works once its account is added under System Settings › Internet Accounts (Calendars on). No Google credential ever reaches hourdial.

  1. In config.toml: [calendar] enabled = true (and optionally calendars = ["Work"]).
  2. In rules.toml:

    [[category]]
    name = "Meetings"
    kind = "shallow"
    
    [calendar]
    category = "Meetings"
    
  3. make install (or restart trackd) and allow the calendar prompt. tock doctor shows the state and the last sync.

trackd copies timed events from two days back to one day ahead every 10 minutes, skipping all-day, free and declined ones. An event only labels time when you were not at the Mac: idle time and gaps inside it become Meeting rows titled with the event. What you did at the Mac during an event keeps its own label. Rules can set a meeting’s project:

[[rule]]
bundle = ["tock.meeting"]
title = '^ATLAS'
project = "ATLAS"

t on a meeting row relabels it. Answered time away wins over an event, and hourdial does not ask about time an event explains.

Planned sessions and meetings

A slot is a timed plan item for today (a time context such as @14h00 and a due: of today, not yet ticked) or, with [calendar] on, a timed calendar event. A plan item ends at the next timed item of that day, at most 3 hours later. hourdial tells you about each slot twice:

Notice When Title Body
up next notify_before minutes ahead (5 by default) Up next 14:00 Review · in 5 min
starting now at the start Starting now 14:00–14:50 Review

An event reads 14:00 Standup (Work) · in 5 min, with its calendar name in parentheses. notify_before = 0 leaves out the up-next notice. A slot that trackd first knows less than a minute before its start gets only the starting notice, and a trackd that starts more than 2 minutes after a start sends nothing for it. Calls and meetings do not delay these notices: telling you is their point. [focus] notify = false silences them, and so does [plan] notify = false.

Each notice comes once. trackd keeps what it sent, so a restart repeats nothing, and a slot keeps its notice when the calendar is synced again. When several machines share a sync folder, only the one with the latest input sends the notices; a machine that has been quiet for more than 15 minutes is not counted. Nothing about slots is synced.

Starting a session. With auto_start = true, the starting notice of a plan item tagged with a module (+ana1) starts a focus session as long as the slot, never below 5 minutes. It starts none while a session already runs or during a call or meeting, and the notice carries a Stop session button. It reads 14:00–14:50 Review · focus session started · 50 min · Analyse 1, naming the module (the session itself has no project; its time is classified as usual). With [plan] notify = false the session still starts, without a notice. With auto_start off, that same notice offers Start focus (50 min), which starts the session when you press it. Events never start a session.

Joining. When the URL, location or notes of an event hold a Google Meet, Zoom or Microsoft Teams link, both notices offer Join (first button), which opens it in your browser. The link must be https on meet.google.com, zoom.us (or a subdomain), teams.microsoft.com or teams.live.com; anything else is ignored, with no button and no log line. With [calendar] auto_open = true, tockbar opens the link itself when it shows the starting notice, once, but only for an event you organize or accepted (or that has no other attendee): an invite you have not answered, or answered “maybe”, still offers Join and waits for your click. trackd never opens anything, and hourdial never blocks.

The menu bar menu shows Next: 14:00 Review (in 12 min) when a slot starts within the hour (now while it runs), and Join Standup when that slot is an event with a link starting within 10 minutes or running.

Recommendations

hourdial learns from your own history when you focus best and for how long, and uses it for two things: a suggestion to start a focus session at a good moment, and a break reminder that follows how long you usually keep focus. Everything is computed on this machine from your own data, with no network and no AI. It only ever notifies: nothing is blocked or covered.

What it learns. The profile is built once a day from the days before today.

tock trends shows all three after the month, then how you answered:

Best focus hours
Mon  09–10 · 10–11 · 14–15
...
Typical session: 45 min (from 12 good sessions)
Sustained focus: 52 min before a break
Suggestions: 5 of 8 accepted · muted at 16–17
Breaks: 3 of 6 taken · muted at 15–16

With a thin profile the title says Best focus hours (not enough history: 4 of 7 days) and lists no hours. Typical session reads 25 min (default, not enough sessions yet) and Sustained focus reads (not enough history) when there is too little to learn from; Suggestions: none answered yet and Breaks: none answered yet stand until you have answered one. tock trends --hours prints the table behind it: the mean focus minutes of each weekday and hour of the last 28 days. A past --month shows the month alone.

A focus suggestion comes when all of these hold:

The session is your typical session, shortened to fit before the next plan item or event and before the end of the work hours, rounded down to 5 minutes. Under 15 minutes nothing is suggested. The notice is Good time to focus with Your best focus hour · start a 45 min session now? and the buttons Start focus (45 min) and Not now. Pressing the first starts a manual focus session of that length.

The adaptive break. With adaptive_break = true and a sustained focus length, the break reminder comes after that much activity in a row, kept between 25 and 120 minutes, instead of [focus] break_after. The break it suggests is a fifth of the run so far, rounded to 5 minutes and kept between 5 and 20: 52 min without a break. Stand up for 10 min. The reminder repeats every break_repeat minutes, as before. Without a sustained focus length, or with adaptive_break = false, the reminder keeps break_after and suggests 5 minutes. [recommend] enabled = false restores the earlier reminder, which has only the Snooze 30 min button.

The reminder offers Take a break (10 min), Not now and Snooze 30 min. Take a break holds the reminders back for the length of the break, shows Break · until 10:20 in the menu bar menu, and counts as a break: the next run is measured from its end. When the break ends, trackd sends one Break over notice (10 min break done. Back to it.); a trackd that first sees the end more than 5 minutes late, because it was not running, sends none. Not now changes nothing about when the next reminder comes. Snooze closes the suggestion without an answer: it is not counted when hourdial learns which hours you refuse.

Answering. Every suggestion and break reminder is kept as a row in tock.db with your answer. You can answer from the notification buttons, the menu bar menu (Suggested: focus now (45 min) with Start focus (45 min) and Not now), the focus tab (enter to take it, d for not now) or the shell. A row stays open for 30 minutes; after that it is ignored and counts for nothing.

tock recommend              # Suggested: focus now (25 min) · open until 09:55
tock recommend accept       # start the session, or take the break
tock recommend dismiss      # not now

Learning from answers. The answers of the last 30 days are counted separately for focus suggestions and break reminders, by the hour they were sent:

On Linux the notices come through notify-send without buttons; answer with tock recommend accept or tock recommend dismiss.

Screen reading

Some windows say little in their title: a terminal reading zsh, a PDF viewer, Anki, a browser tab named after a site. With [ocr] enabled = true trackd reads the text of such a window on screen, keeps a few keywords and lets the local model (see The model) label the time from them. It is off by default and macOS only.

Which windows. A window is read when nothing labels it, or only a rule that names the app or site alone, or when its app is in [ocr] apps (terminals, PDF viewers, Anki and browsers by default). It is read once it has stayed in front min_dwell seconds (20), then at most every interval seconds (60) while it stays.

Never read: private or incognito windows (and a browser window whose title trackd cannot see, in case it is private), anything in the [llm] or [ocr] deny lists, a locked screen, time away, and sign-in or password windows: a title or host with sign in, log in, password, 2FA and the like, or any moment a password field holds the keyboard (secure input). Each skip is counted in tock doctor.

What is kept. The screenshot exists only in a short-lived worker (trackd ocr-worker) that trackd starts for one read and kills after 5 seconds: nothing is written to disk, and trackd itself never holds the image or Vision’s memory. Of the text, only plain words are kept: 3 to 24 letters, no stop words, nothing with a digit, no emails, links, tokens or hex, nothing your deny title patterns match. At most 32 words per read and 48 per span, newest first. They are deleted with their span and when [privacy] keep_titles deletes titles, and they are never sent to Claude, synced or exported.

How it labels. Words read on screen count half as much as title words in the local model. A span the rules left unlabelled can get a category from them; when only the screen words decided it, tock export shows its source as screen.

Permission. Screen reading needs Screen Recording for trackd. Run tock ocr grant: trackd asks macOS, which shows a prompt or opens System Settings › Privacy & Security › Screen & System Audio Recording, where you allow trackd. macOS asks you to confirm it again from time to time; until you do, reads are skipped as no permission. trackd never asks on its own.

tock ocr test waits 3 seconds so you can switch to a window, then has trackd read it once and prints the keywords, or why it was skipped (--now reads at once). A test read is never stored. It needs trackd running.

$ tock ocr test
capturing the front window in 3 s (switch to it now)...
Ghostty · keywords: kubectl deployment rollout namespace pods · 142 ms
$ tock doctor
...
ok  ocr: on · permission granted · today 37 reads, avg 138 ms · skipped: away 12, private window 4

One read of a browser window took about 0.8 s in the worker when measured (Vision’s accurate mode; its fast mode took 0.1 s but got a fifth of the words right, against over half) and costs nothing in trackd’s memory. At most one read a minute while an unclear window stays in front; raise interval to read less. Nothing runs while enabled = false.

make install also installs tock.app, a small menu bar app that runs at login. The first time it starts, macOS asks whether hourdial may send notifications; allow it.

The menu bar shows today’s tracked time (◷ 2h54), or the countdown while a focus session runs (◉ 18:42). A ! means trackd is not running. The menu stays short and shows a row only when it matters:

Set up hourdial replaces all this while there are no rules yet (it writes the starter rules, as tock init does).

A hidden app or site goes to [privacy] hide_apps and hide_sites in config.toml. From then on trackd records it as private time only, with no title or URL, and never sends it to Claude or screen reading. Past spans stay as they were (tock prune deletes old titles, see Deleting old titles).

⌥⌘F ([focus] hotkey, on by default) asks what you are working on and for how long, from any app, and starts the session; while one runs it offers Stop and Keep going. The goal shows in the menu and on the break screen. Shortcuts, Raycast and scripts can do the same with links: tock://start?min=50&goal=…, tock://stop, tock://prompt and tock://dashboard. tock session start --goal "…" sets it from the terminal.

With the app running and allowed to notify, focus notifications come from hourdial with buttons:

Notification Buttons
distracted in a session Stop session
session done Start again
good time to focus Start focus (N min), Not now
break due Take a break (N min), Not now, Snooze 30 min
time away your recent away labels, then Leave idle
up next Join (meetings with a link)
starting now Join, then Start focus (N min) or Stop session

Routine notices (start of day, midday check-in, recap, overworking) and Break over come without buttons. Up-next notices of plan items come without buttons too.

Without the app, or with its notifications turned off, trackd sends plain notifications as before. tock doctor says which is in use. Quit hourdial menu bar keeps it closed until the next login; make install starts it again. Its log is ~/.local/state/tock/tockbar.log, and it never logs notification text.

The notch

The menu bar app also draws a panel in the notch. A display without a notch, such as a monitor beside the MacBook or a Mac without one, gets a notch drawn at the top of its menu bar, as tall as the menu bar. Every display shows the same island; moments open on the display your pointer is on, and a click on any notch opens it there ([notch] all_displays = false keeps it on the built-in display, else the main one).

Nothing shows while nothing runs. Rest the pointer on the notch and it grows a little (and ticks the trackpad); click it, or swipe down on it with two fingers, to see today’s time, score and how much is left to label. A quick pass of the pointer on its way to a menu does nothing. With [notch] open_on_hover = true the rest alone opens it. With Focus on, the open notch starts a session in one click: Focus 25m (your default length) and the next preset sit beside Open Today.

The open notch has pages you swipe between. Today opens on the day as a 24-hour dial, as on the dashboard: your time in kind colours, your work hours round the outside, a hand at now, with the score, deep focus and time tracked beside it. A running session gets a page of its own first: a large ring counting down the time left, with your focus level and the start and end times beside it.

Esc, a swipe up, a click on its top band or a click elsewhere sends an open panel back, and so does moving the pointer away from a panel you opened. The panel never takes the focus from the app you work in: keys reach it only after you click it. When an app is in full screen, a drawn notch steps aside while nothing runs. A session ending and a saved label tick the trackpad once. With Reduce motion on, the panel fades instead of moving.

While the panel is on, these notices come only through the notch, not as banners. If a more important moment is open, a less important notice still comes as a banner. The panel is left out of screen sharing and recordings, because it shows window titles: [notch] show_in_recordings = true lets them see it. [notch] enabled = false (or Settings › Notch) turns it off and brings the banners back.

tockbar notch-demo plays made-up moments in the notch, with no database, for recording a demo.

Linux

On Linux, trackd reads the focused window from Hyprland’s sockets, from Sway’s or i3’s IPC socket, or from the X server (any X11 window manager that sets _NET_ACTIVE_WINDOW, which nearly all do). It needs no cgo, no bundle and no permissions. It finds the session by itself: the session’s variables first, then the sockets on disk. TOCK_DESKTOP=hyprland, sway, i3 or x11 in trackd’s environment picks one by hand, and tock doctor says which it sees. GNOME and KDE on Wayland are not supported: trackd has no way to read their front window. Windows is experimental (see Stability and support).

make install-linux   # trackd and tock in ~/.local/bin, trackd.service enabled

Without Go, take tock-<version>-linux-amd64.tar.gz (or arm64) from a GitHub release, check it against SHA256SUMS, and install the two binaries. From v1.0.0 every tarball, tock.rb and the .dmg also carry signed build provenance; gh attestation verify tock-<version>-linux-amd64.tar.gz -R confuserdotcom/hourdial checks that GitHub’s release workflow built that file from the tag, not someone’s laptop:

tar xzf tock-v*-linux-amd64.tar.gz && cd tock-v*-linux-amd64
install -m 755 trackd tock ~/.local/bin/ && ~/.local/bin/trackd install && tock init

No Go on the Linux machine? Build and install it from the Mac over ssh instead; this also updates it later:

make deploy-linux LINUX_HOST=box                  # LINUX_ARCH=amd64
make deploy-linux LINUX_HOST=box LINUX_ARCH=arm64

trackd runs as the systemd user unit trackd.service and starts with your graphical session. Its log is ~/.local/state/tock/trackd.log, and systemctl --user status trackd shows the unit.

The desktop gives a window’s title but no browser’s address. A small hourdial extension sends the tab in front to trackd through the browser’s native messaging (trackd is started by the browser and reads its stdin; nothing goes over the network). Run

trackd browser install

and follow what it prints: in Chromium, Chrome or Brave, Load unpacked the extension it wrote, then turn on “Allow in Incognito”. The address is kept the same way as on the Mac (host and path; no query, no fragment). An incognito window, or a browser window the extension cannot see, counts as private: no title and no address. Firefox loads it only for one session (unsigned add-ons). tock doctor says when the extension last reported.

Hyprland

Wayland gives no app the idle time, so hypridle tells trackd. Add this to hypridle’s config, keeping your other listeners. That is ~/.config/hypr/hypridle.conf, or the file hypridle runs with when it is started with -c (some shells do this); tock doctor checks the one that is running:

general {
    before_sleep_cmd = trackd idle
    after_sleep_cmd = trackd active
}

listener {
    timeout = 300
    on-timeout = trackd idle --after 300
    on-resume = trackd active
}

Keep --after equal to the timeout. While hyprlock (or swaylock) runs, the session counts as locked.

When your desktop writes hypridle’s config itself (some Hyprland shells render it from their own settings and restart hypridle), an edit there does not last. Run a second hypridle just for trackd instead, under another name so the desktop leaves it alone:

ln -s /usr/bin/hypridle ~/.local/bin/tock-hypridle
# ~/.config/tock/hypridle.conf: the general and listener blocks above, and in
# general: ignore_systemd_inhibit = true and ignore_dbus_inhibit = true, so a
# caffeine mode cannot hide that you left (a video's Wayland inhibitor still
# counts as watching)
cat > ~/.config/systemd/user/tock-idle.service <<'EOF'
[Unit]
Description=tock: tell trackd when you are idle (a hypridle of its own)
PartOf=graphical-session.target
After=graphical-session.target
ConditionEnvironment=WAYLAND_DISPLAY

[Service]
ExecStart=%h/.local/bin/tock-hypridle -c %h/.config/tock/hypridle.conf
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical-session.target
EOF
systemctl --user daemon-reload && systemctl --user enable --now tock-idle

tock doctor finds the hook in the config of any running hypridle, renamed or not.

An always-on idle inhibitor (a “caffeine” or keep-awake mode) also stops a shared hypridle from ever reporting you idle; a separate one for trackd with those two lines does not have that problem.

Sway and i3

trackd reads the focused window from the IPC socket ($SWAYSOCK, $I3SOCK, or the newest sway-ipc.*.sock in $XDG_RUNTIME_DIR). Sway does not start graphical-session.target by itself, so start trackd from Sway’s config and hand it the session’s variables:

exec systemctl --user import-environment SWAYSOCK WAYLAND_DISPLAY DISPLAY XAUTHORITY
exec systemctl --user start trackd

Idle comes from swayidle, the same two commands as hypridle’s:

exec swayidle -w \
    timeout 300 'trackd idle --after 300' \
    resume 'trackd active'

Keep your other timeouts on the same swayidle line. tock doctor finds the hook on a running swayidle’s command line or in its config (~/.config/swayidle/config). Under i3 (X11) the window comes from i3’s socket and idle from the X server, so no swayidle is needed there. When blocking hides an app, its windows go to the scratchpad (scratchpad show brings them back).

X11

Any other X11 session works through the X server itself: the active window’s WM_CLASS and title, and the screensaver extension’s idle time, so there is no idle hook to set up. trackd connects over the local socket (DISPLAY=:0 and the like; a remote display is not supported) with the cookie in $XAUTHORITY or ~/.Xauthority. When your desktop does not start graphical-session.target (a bare window manager from startx), add to ~/.xinitrc before the window manager starts:

systemctl --user import-environment DISPLAY XAUTHORITY
systemctl --user start trackd

Blocking cannot hide windows on X11; the drift notice still goes out.

On every desktop

Sync between machines

hourdial can merge the time you spend on two machines, for example the Mac and a Linux desktop, into one view on each. hourdial does not move any data itself. Pick a folder that your own tool keeps in sync, such as Syncthing or a network share, and name it on both machines in config.toml:

[sync]
dir = "~/Sync/tock"
machine = "mac"        # optional; default: the host name
rules = true           # optional; share rules.toml (see Rules below)
update = true          # optional, off by default; Linux: install the Mac's builds (see Updates)

Every minute, trackd writes this machine’s last two days to <dir>/<machine>/<YYYY-MM-DD>.jsonl, and reads the other machines’ files.

The day files hold titles and URLs (never those of private windows). Keep the folder private.

Updates

With a sync folder, the Mac keeps itself and a Linux machine up to date. You do not run make install or copy files.

Backup

trackd keeps a copy of tock.db every day, while you’re away from the computer, in ~/.local/share/tock/backups/auto/. It keeps the newest 7; [backup] keep in config.toml changes that, and keep = 0 turns the daily copies off. Before a new version changes the database, hourdial also keeps a copy of it as it was (pre-v0023-to-v0024.db.gz) for 14 days. If that copy can’t be made, for example because the disk is full, the new version doesn’t change the database and says why.

Each copy is checked as it is made. If the check finds damage, tock doctor and tock status say so, and the menu bar shows a notice once a day. tock doctor --deep checks the whole live database now.

tock backup still writes one archive with the database, your rules and your config, for keeping somewhere else: ~/.local/share/tock/backups/tock-YYYYMMDD-HHMMSS.tar.gz (owner-only), with tock.db, rules.toml, learned.toml, config.toml, shell.log and the files of your issued invoices (invoices/) when they exist. --out FILE writes elsewhere; an existing file is never overwritten.

Copies on this machine don’t help if the disk dies: Time Machine, or the sync folder, covers that. The copies and archives hold your titles and URLs, so keep them out of git and shared folders. The daily copies keep titles up to 7 days past [privacy] keep_titles.

When something went wrong

tock status starts with a word and ! when trackd needs a look:

tock doctor names each with when it happened and what to do. After 24 hours a failure is history: doctor still counts it, status no longer marks it.

When a program crashes, the panic and its stack also go to ~/.local/state/tock/trackd-crash.log (or tock-crash.log, tockbar-crash.log), next to the logs. Nothing is sent anywhere; tock bug-report puts them in its file, redacted, for you to attach.

Restore

tock restore lists the daily copies, the copies made before updates and your tock backup archives, newest first. tock restore 2 puts the second one back:

  1. It checks the copy, and refuses one made by a newer hourdial.
  2. It says what you lose (activity recorded after the copy was made) and asks; --yes skips the question. If the copy lacks invoices you issued since, it names them and goes on only with --yes. Their files stay in ~/.local/share/tock/invoices/, and tock invoice recover puts them back in the database.
  3. It stops trackd (and the menu bar on a Mac), keeps the current database as tock.db.before-restore-<time>, puts the copy in its place, and starts them again.
  4. If anything else still has the database open, such as a tock web or terminal UI you started yourself, it changes nothing, starts trackd again and names what to close: close these first: tock web (pid 4123).

From a tock backup archive only the database is restored; your rules and config are in the archive, to copy back by hand if you want them.

Import

tock import activitywatch <export.json> reads your ActivityWatch history into hourdial. Get the file from ActivityWatch’s web UI (Raw Data ▸ Export all buckets as JSON), or with ActivityWatch running:

curl -s http://localhost:5600/api/0/export > aw.json
tock import activitywatch aw.json

Uninstall

tock uninstall           # stop trackd and the menu bar, remove the apps and tock; data stays
tock uninstall --purge   # also delete tock.db, rules and config (asks you to type yes)

On a Mac, the signing certificate stays in your login keychain; delete tock-local-codesign in Keychain Access if you want it gone. make uninstall only unloads the background agents.