Snag help › Snag for the desktop
The timer
One timer runs at a time. It is controlled from keybinds, the tray menu or the timer window, and all three drive the same timer.
Starting and stopping
| Command | Does |
|---|---|
snag start | starts the timer on the task last worked on |
snag stop | stops the running timer |
snag toggle | stops it if running, starts it if not |
snag show | raises and focuses the timer window |
snag status | prints what the timer is doing |
These talk to the running daemon (snag run). With no daemon they say so and exit with code 1; they never start one.
To start on a different task, open the task picker.
The timer window
Open it with snag show, or Open in the tray menu. Its title is Snag.
It shows the elapsed time, the task and project, and three actions:
| Action | Does |
|---|---|
| Start / Stop | starts or stops the timer |
| Pick a task | opens the task picker |
| Billable | a switch on the running timer; on by default |
Billable is set while working rather than at the end.
The task picker
A filterable list of tasks. Type to filter; Enter starts a timer on the highlighted task. What Enter will do, including stopping the current timer, is shown above the list.
The list comes from a local copy of your projects and tasks, refreshed from the server every 15 minutes, so the picker opens instantly and works offline. Before the first refresh it shows only tasks this machine has already logged time against.
snag tasks prints the same list as JSON, for a bar or a script.
About
Press ? in the timer window, or choose About in the tray menu, for the version and the paths Snag is using.
The tray
The tray icon is grey when stopped and a red dot when running. An amber mark means something needs attention: changes waiting to sync, an expired token, or a question waiting for an answer.
The menu, top to bottom:
- what is running, if anything
- Stop timer, or Resume: (last task) when stopped
- Choose a task... when stopped
- idle spans still waiting for an answer (click to answer)
- Open
- About snag (version)
- Sync now (N queued, N failed), when there is anything to sync; it shows the count and cannot be clicked
- Quit
Some desktops hide tray icons in a collapsed drawer (Omarchy's default bar does). Everything in the tray is also reachable from the timer window and the keyboard.
The status bar
The tray cannot put text in Waybar, so Snag writes the running time to a status file once a minute and a bar module reads it. Set up the module from contrib/waybar/README.md (Waybar) or contrib/quickshell/ (Omarchy 4).
The module shows nothing while stopped. While running it shows the duration, and optionally an abbreviated project name, depending on the label setting:
label | Shows |
|---|---|
off | nothing |
duration | 1:23 |
duration+project (default) | 1:23 and the project abbreviation |
The module carries a CSS class for theming: stopped, running, queued, attention or auth. In the Waybar module, left click opens the timer window and right click toggles the timer.
Offline and suspend
- Every change is written to the local database first and sent to the server afterwards. Starting or stopping with no network works; the queue catches up when the connection returns.
- A start and stop made while offline are sent as one finished time entry.
- Each entry carries a key, so an interrupted send never files the same time twice.
- The clock counts time the machine spent suspended. A timer left running over a closed lid includes the time the lid was shut.
When two timers disagree
If the server has a different timer running (started from the web or another machine), Snag does not pick one. The timer window and the tray menu ask which to keep:
- Keep this machine's
- Keep the server's
Nothing changes until one is chosen.
Next: Idle time