clockify-desk

Review local Clockify Desktop autotracker activity and sync work sessions to Clockify workspaces.

Local autotracker is never deleted. Each profile has its own whitelist/blacklist; filters apply only when syncing to that profile's workspace.

Requirements

• macOS with Clockify Desktop
• Python 3.11+ (stdlib tomllib; 3.10 needs pip install tomli)
• sqlite3

Install

git clone <repo-url> clockify-desk
cd clockify-desk
cp config.example.toml config.local.toml
# edit config.local.toml — never commit this file
./install.sh

Architecture

Clockify Desktop SQLite (one local DB, shared)
        │
        ├── review --profile tale   → report include/skip/undecided for Tale filters
        ├── review --profile activ  → same rows, different filter result
        │
        └── sync --profile tale     → POST only rows Tale's profile includes
            sync --profile activ    → POST only rows Activ's profile includes

Blacklist for profile A does not remove rows from the DB or affect profile B.

Config

default_profile = "tale"

[timing]
row_limit_minutes = 60    # skip idle rows at sync (ZIDLETIME)
session_gap_minutes = 10  # merge rows when gap ≤ this

[profiles.tale]
label = "Tale"
api_key = "..."
workspace_id = "..."
user_id = "..."
project_id = "..."
whitelist_apps = ["Code", "Google Chrome"]
blacklist_apps = ["Spotify"]
whitelist_domains = ["github.com"]
blacklist_domains = ["youtube.com"]

Profile selection: --profile → CLOCKIFY_PROFILE env → default_profile.

Usage

# See what a profile would sync (read-only)
clockify-desk review --profile tale -d 60
clockify-desk review --profile tale -d 7 -v

# Sync to Clockify API (profile filters applied here only)
clockify-desk sync --profile tale --dry-run
clockify-desk sync --profile tale --date 2026-07-11
clockify-desk sync --profile tale --range 2026-07-01 2026-07-12

# Profiles
clockify-desk profiles list
clockify-desk profiles show tale

Commands

Command	Action
review	Read-only report: include / skip / undecided for the active profile
sync	POST grouped sessions to Clockify API (profile filters applied)
profiles	List or show configured profiles

Safety

• Never deletes local autotracker rows
• sync skips sessions that overlap existing API entries for that profile
• sync skips blacklist, idle, and undecided rows per profile config

See docs/migration.md for migrating from clockify-clean and ~/clockify/sync.

License

MIT