{"id":50325298,"url":"https://github.com/testy-cool/toggl-linux","last_synced_at":"2026-05-29T05:30:58.545Z","repository":{"id":357875155,"uuid":"1210409179","full_name":"testy-cool/toggl-linux","owner":"testy-cool","description":"Toggl Track tray timer for Linux — Ctrl+Shift+T to toggle, offline queue, single instance","archived":false,"fork":false,"pushed_at":"2026-05-14T15:51:19.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T17:44:28.303Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testy-cool.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-14T11:43:58.000Z","updated_at":"2026-05-14T15:52:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/testy-cool/toggl-linux","commit_stats":null,"previous_names":["testy-cool/toggl-linux"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/testy-cool/toggl-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Ftoggl-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Ftoggl-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Ftoggl-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Ftoggl-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testy-cool","download_url":"https://codeload.github.com/testy-cool/toggl-linux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Ftoggl-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33639050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T05:30:58.476Z","updated_at":"2026-05-29T05:30:58.539Z","avatar_url":"https://github.com/testy-cool.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Toggl Track Tray Timer for Linux\n\nA lightweight system tray app that lets you start and stop [Toggl Track](https://toggl.com/track/) time entries with a single keyboard shortcut. Built for Linux desktops (GNOME, Cinnamon, MATE, XFCE) running X11.\n\n**Press `Ctrl+Shift+T` anywhere to toggle time tracking on or off.** That's it.\n\n![Python](https://img.shields.io/badge/Python-3.11+-blue)\n![License](https://img.shields.io/badge/License-MIT-green)\n![Platform](https://img.shields.io/badge/Platform-Linux%20X11-orange)\n\n## Why This Exists\n\nToggl's official desktop app doesn't work on Linux anymore. This replaces it with a single Python file that does the one thing you actually need: **toggle tracking with a hotkey**.\n\nThe tray icon shows the Toggl logo in **pink when tracking** and **grey when stopped**, so you always know at a glance.\n\n## Features\n\n- **Global hotkey** (`Ctrl+Shift+T`) — works everywhere, overrides all apps (X11 key grab)\n- **Tray icon** — pink = tracking, grey = stopped\n- **Tooltip** — hover to see elapsed time and description\n- **Offline mode** — works without internet, syncs to Toggl when back online\n- **Single instance** — launching twice won't create duplicate icons\n- **Sound feedback** — subtle system sounds on toggle (no popup notifications)\n- **View today's entries** — right-click menu shows your timesheet\n- **Edit \u0026 delete** — modify entries directly from the tray menu\n- **Persists across restarts** — remembers state and running timers\n- **Rate limit handling** — respects Toggl's API limits (30 req/hr on free plan)\n\n## Requirements\n\n- **Python 3.11+**\n- **Linux with X11** (Wayland is not supported — uses `XGrabKey` for the global hotkey)\n- **GTK 3** system libraries (usually pre-installed on most Linux desktops)\n- A free [Toggl Track](https://toggl.com/track/) account\n\n### System packages\n\nOn Debian/Ubuntu/Linux Mint:\n\n```bash\nsudo apt install libgirepository-2.0-dev gir1.2-ayatanaappindicator3-0.1 libsecret-tools\n```\n\nOn Fedora:\n\n```bash\nsudo dnf install gobject-introspection-devel libappindicator-gtk3 libsecret\n```\n\n## Installation\n\n### 1. Clone the repo\n\n```bash\ngit clone https://github.com/testy-cool/toggl-linux.git\ncd toggl-linux\n```\n\n### 2. Create a virtual environment and install dependencies\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\nOr with [uv](https://docs.astral.sh/uv/) (faster):\n\n```bash\nuv venv .venv\nsource .venv/bin/activate\nuv pip install -r requirements.txt\n```\n\n### 3. Add your Toggl API token\n\nGet your API token from your [Toggl Profile page](https://track.toggl.com/profile) (scroll to the bottom).\n\n**Option A** — Store in GNOME Keyring (recommended, persistent):\n\n```bash\nsecret-tool store --label='Toggl API Token' service toggl username api_token\n# Paste your token, press Enter, then Ctrl+D\n```\n\n**Option B** — Environment variable (per-session):\n\n```bash\nexport TOGGL_API_TOKEN=your_token_here\n```\n\n### 4. Run it\n\n```bash\nsource .venv/bin/activate\npython3 toggl_tray.py\n```\n\n## Usage\n\n| Action | How |\n|---|---|\n| **Start/stop tracking** | `Ctrl+Shift+T` (anywhere on your desktop) |\n| **Set description** | Right-click tray icon \u003e \"Set description...\" |\n| **View today's entries** | Right-click tray icon \u003e \"Today's entries\" |\n| **Edit/delete entries** | From the \"Today's entries\" window |\n| **Check elapsed time** | Hover over the tray icon |\n\n### Terminal recovery commands\n\nThese do not need the tray window to be visible:\n\n```bash\npython3 toggl_tray.py status          # show current state and local pending entries\npython3 toggl_tray.py local           # list today's local/offline entries\npython3 toggl_tray.py entries         # list today's Toggl + local entries\npython3 toggl_tray.py start \"Task\"    # start tracking from a terminal\npython3 toggl_tray.py stop            # stop tracking from a terminal\npython3 toggl_tray.py set-start 09:00 # correct the current timer start time\npython3 toggl_tray.py sync            # push pending local entries to Toggl now\npython3 toggl_tray.py install-app     # add Toggl Tray to your app launcher\n```\n\n## Autostart on Login\n\nTo make the app searchable from your desktop app launcher:\n\n```bash\npython3 toggl_tray.py install-app\n```\n\nTo also start it automatically on login:\n\n```bash\npython3 toggl_tray.py install-app --autostart\n```\n\n## How It Works\n\n- **One file** (`toggl_tray.py`) — no complex project structure\n- Talks to [Toggl Track API v9](https://engineering.toggl.com/docs/track/) using basic auth\n- Global hotkey uses X11 `XGrabKey` — the key is grabbed at the X server level, so no other app sees `Ctrl+Shift+T`\n- If the API is unreachable (no internet, rate limited), actions are queued locally and synced automatically every 30 seconds\n- State is saved to `~/.local/share/toggl-tray/state.json`\n\n## Dependencies\n\nAll installed via pip — no compiled extensions needed:\n\n| Package | What it does |\n|---|---|\n| [pystray](https://pypi.org/project/pystray/) | System tray icon (uses appindicator on Linux) |\n| [Pillow](https://pypi.org/project/Pillow/) | Icon image loading and processing |\n| [PyGObject](https://pypi.org/project/PyGObject/) | GTK 3 dialogs (description input, entry viewer) |\n| [requests](https://pypi.org/project/requests/) | HTTP calls to Toggl API |\n| [python-xlib](https://pypi.org/project/python-xlib/) | X11 global hotkey grab |\n\n## Toggl Free Plan Limits\n\nThe free plan allows **30 API requests per hour**. This app only calls the API when you explicitly do something (toggle, view entries, edit). Normal usage is ~5 requests per hour. You won't hit the limit unless you toggle hundreds of times.\n\n## Troubleshooting\n\n**No tray icon appears**\n- Make sure your desktop has a system tray / notification area. On GNOME, you may need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/).\n- Install the appindicator library: `sudo apt install gir1.2-ayatanaappindicator3-0.1`\n\n**Ctrl+Shift+T doesn't work**\n- This app only works on X11, not Wayland. Check with `echo $XDG_SESSION_TYPE`.\n- Another app may have already grabbed that key combo.\n\n**\"Another instance is already running\"**\n- The message includes the PID from the lock file. If that process is gone, remove the lock file: `rm ~/.local/share/toggl-tray/toggl-tray.lock`\n\n**Tray entries are empty but tracking looks active**\n- Run `python3 toggl_tray.py status`. Local/offline entries are shown from `~/.local/share/toggl-tray/pending.json`.\n- Run `python3 toggl_tray.py local` to list only local pending entries for today.\n\n**No sound on toggle**\n- Sounds use `paplay` (PulseAudio). Make sure it's installed: `sudo apt install pulseaudio-utils`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesty-cool%2Ftoggl-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftesty-cool%2Ftoggl-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesty-cool%2Ftoggl-linux/lists"}