Plasmai

A KDE Plasma 6 panel widget for time tracking — Kimai, Clockify, Toggl Track, or SolidTime.

Plugin ID: com.github.shrippen.plasmai
Repository: https://github.com/shrippen/Plasmai KDE Store: https://store.kde.org/p/2368175/

Note: This is completely vibe coded from start to finish. This is simply something I wanted for myself but might as well share here.

Features

• Live timer in the panel (project/activity + elapsed time)
• Start, stop, and switch tracking from the popup or desktop widget
• Click Recent or a favorite while tracking to confirm switching to that activity
• Edit the running entry’s start time, project, and activity
• Manual time entries (+) and a secondary statistics view with charts
• Recent activities and pinned favorites (customer colors)
• Tags and billable on new and running entries (Kimai/Toggl tags; all providers for billable)
• Edit, delete, and split stopped Recents from the overflow menu
• Create customer, project, or activity from the pickers
• Multiple profiles per service; API tokens stored in KWallet
• Backends: Kimai, Clockify, Toggl Track, SolidTime
• Searchable project/activity pickers
• Today/week work summary (Kimai work contract; remaining hours skip vacation/holidays when kimai-holiday-bundle or the official WorkContract plugin is installed)
• Day sparkline: zoomed work-hours bar, sun/moon/work arcs, overtime segments, hour ticks
• Optional color distinction when customer/project colors clash
• Shared settings across all widget instances
• Desktop notifications; optional idle auto-stop
• Translations: EN, DE, FR, ES, IT, NL, PT (BR), PL, UK, RU, JA, ZH (CN)

Requirements

• KDE Plasma 6
• secret-tool (libsecret / libsecret-tools)
• notify-send (libnotify) for desktop notifications
• xprintidle (X11) or loginctl / ScreenSaver (Wayland) for idle detection; optional
• A supported time tracker with API access

Installation (from source)

git clone https://github.com/shrippen/Plasmai.git
cd Plasmai
chmod +x contents/code/*.sh
kpackagetool6 -i . -t Plasma/Applet

Update after changes:

kpackagetool6 -u . -t Plasma/Applet
# reload Plasma if needed:
# plasmashell --replace &

Install a release package (.plasmoid):

kpackagetool6 -i Plasmai-1.6.2.plasmoid -t Plasma/Applet

Setup

1. Right-click the panel → Add Widgets → search for Plasmai
2. Right-click the widget → Configure Plasmai
3. Connection tab: choose service (Kimai / Clockify / Toggl / SolidTime), set URL if needed, save API token, test connection
4. Favorites tab: pin frequently used project/activity pairs
5. Display / Behavior tabs: recent count, panel labels, sparkline arcs, idle stop, notifications
6. Maintenance tab (optional): review color-clash groups when distinction is enabled

Use + on the widget for manual entries and the chart icon for statistics.

Shared settings

Profiles, favorites, display, and behavior settings are shared across all Plasmai instances via:

~/.config/com.github.shrippen.plasmai/shared.json

Packaging

Build a store-ready .plasmoid archive:

./scripts/package.sh

See STORE.md for publishing to store.kde.org.

Translations

UI strings use Plasma i18n. Bundled languages: en, de, fr, es, it, nl, pt_BR, pl, uk, ru, ja, zh_CN.

./translate/extract.sh   # refresh translate/template.pot from QML
# edit translate/de.po (and other languages), then:
./translate/build.sh     # compile .mo into contents/locale/

Compiled catalogs ship in contents/locale/<lang>/LC_MESSAGES/plasma_applet_com.github.shrippen.plasmai.mo.

Development

Design decisions and UI principles: DESIGN.md.
Product direction: ROADMAP.md.

plasmoidviewer -a com.github.shrippen.plasmai -l topedge -f horizontal
plasmoidviewer -a com.github.shrippen.plasmai

Testing

./tests/run.sh

QML unit tests cover the .js libraries. pytest launches plasmoidviewer, clicks applet chrome (not live Start/Stop/Continue/favorites), and fails if plasmoidviewer or plasmashell logs QML errors. See tests/README.md.

Time-tracking backends

Plasmai routes API calls through contents/code/timeTracker.js. Profiles store a provider id (kimai, clockify, toggl, solidtime). Shared UI helpers remain in contents/code/kimaiApi.js; each provider normalizes responses to that shape.

Only the Kimai backend is tested. Clockify, Toggl Track, and SolidTime are implemented against their public APIs but have not been verified with live accounts yet — treat them as experimental.

Service	Notes
Kimai	Reference implementation (Bearer token + server URL) — tested
Clockify	API key; optional regional API URL — untested
Toggl Track	API token (Basic auth) — untested
SolidTime	Bearer JWT + instance URL — untested

See contents/code/providers/NOTES.txt for implementation details.

Uninstall

kpackagetool6 -r com.github.shrippen.plasmai -t Plasma/Applet

License

GPL-3.0-or-later — see LICENSE.