Kimai Time Tracker por Jürgen Haas

Kimai Browser Plugin (kimai-bp)

Cross-browser extension for Kimai time-tracking. Injects widgets into web pages so you can start and stop timesheets without leaving your browser tab.

Features

• Start/stop timers from any web page via a floating widget or the extension popup
• Platform profiles — automatic detection of tasks and issues on supported platforms:
• GitLab (18.0+)
• GitHub (2024.1+)
• Jira (9.0+)
• Drupal.org (7.0–11.x)
• Inline track buttons injected next to detected issues/tasks on supported platforms
• Cascading task picker — Customer > Project > Activity dropdowns with data fetched from your Kimai instance
• Tag autocomplete — search and add tags from your Kimai instance
• URL pattern memory — remembers which customer/project/activity you used for a given URL scope and pre-fills settings on future visits
• Profile auto-updates — installed platform profiles are checked for updates every 6 hours
• Debug mode — YAML profile editor with live validation and color-coded DOM overlays for profile development
• Cross-browser — Chrome (Manifest V3) and Firefox (Manifest V3, 145.0+)

How It Works

The extension has two modes depending on the page you visit:

1. Profile matched — When the current page matches an installed platform profile (e.g. a GitLab issue page), compact "Track" buttons are injected next to each detected issue. Clicking a button opens a dialog to select or confirm customer/project/activity settings and starts a Kimai timer with the issue ID and title as the description.
2. No profile matched — A floating widget overlay appears in the corner of the page with a full timer interface: task picker, description field, tag input, and start/stop controls.

The extension popup provides the same timer controls accessible from the toolbar icon on any page.

All Kimai API communication is handled by the background service worker. Content scripts and the popup never call the API directly — they send typed messages to the background, which centralizes authentication and state management.

Installation

From Source

pnpm install
pnpm build:chrome # Production build for Chrome
pnpm build:firefox # Production build for Firefox


Chrome: Open chrome://extensions, enable Developer mode, click "Load unpacked", select .output/chrome-mv3.

Firefox: Open about:debugging#/runtime/this-firefox, click "Load Temporary Add-on", select .output/firefox-mv3/manifest.json.

Configuration

1. Click the extension icon and go to Settings (or right-click the icon > Options)
2. Enter your Kimai URL (e.g. https://kimai.example.com)
3. Enter your API token (generated in Kimai under Settings > API)
4. Click Save, then Test Connection to verify

Installing Platform Profiles

1. Open the extension settings page
2. Scroll to Platform Profiles
3. Click Browse Available to see profiles from the registry
4. Click Install next to the profiles for platforms you use
5. Add custom domains if your instance uses a self-hosted URL (e.g. gitlab.mycompany.com)

Development

pnpm install # Install dependencies
pnpm dev # Dev mode with HMR (Chrome)
pnpm dev:firefox # Dev mode (Firefox)
pnpm build # Production build (all browsers)


Testing

pnpm test # Run all tests
pnpm test:unit # Unit tests only (Vitest)
pnpm test:e2e # E2E tests (Playwright)


Linting & Type Checking

pnpm lint # ESLint check
pnpm lint:fix # ESLint auto-fix
pnpm format # Prettier format
pnpm format:check # Prettier check
pnpm typecheck # TypeScript type checking


Architecture

src/
├── entrypoints/
│ ├── background.ts # Service worker — API calls, timer state, profile management
│ ├── content.ts # Content script — profile detection, track buttons, floating widget
│ ├── popup/ # Extension popup — timer controls, task picker
│ └── options/ # Settings page — connection config, profile & pattern management
├── components/ # Vanilla web components (Shadow DOM)
│ ├── kimai-widget.ts # Floating overlay (timer + task picker + tags)
│ ├── kimai-popup.ts # Popup UI
│ ├── kimai-timer.ts # Live elapsed-time display with start/stop
│ ├── kimai-task-picker.ts # Customer > Project > Activity dropdowns
│ ├── kimai-tag-input.ts # Tag autocomplete input
│ ├── kimai-options.ts # Settings form
│ ├── kimai-profile-manager.ts # Profile browse/install/update UI
│ ├── kimai-pattern-manager.ts # URL pattern management UI
│ └── kimai-debug-profile-editor.ts # YAML profile editor with live validation
├── lib/
│ ├── api/ # Typed Kimai REST API client
│ ├── storage/ # Cross-context state (WXT storage)
│ ├── messages.ts # Typed message protocol (background <-> content/popup)
│ ├── profiles/ # Profile parsing, matching, and management
│ ├── patterns/ # URL pattern matching and storage
│ └── context/ # Page context analysis (stub)
└── assets/ # Icons


Key Design Principles

• Background owns all API calls — content scripts and popup communicate via typed messages; no direct API calls from page context.
• Shadow DOM isolation — all web components use attachShadow({ mode: 'open' }) with inline <style> elements; the floating widget and track dialog are fully isolated from host page styles.
• Zero innerHTML — all DOM is built with document.createElement(), textContent, and appendChild(). No innerHTML assignments anywhere in the build output, ensuring AMO validation compliance.
• Profile-driven detection — platform support is defined in downloadable YAML profiles, not hard-coded. New platforms can be supported without a new extension release.
• URL pattern memory — customer/project/activity settings are stored per URL prefix and looked up by walking up the URL path hierarchy.

Tech Stack

| Layer | Technology |
| ------------------- | --------------------------------------------------- |
| Extension framework | WXT (Vite-based, Manifest V3) |
| UI components | Vanilla web components (HTMLElement + Shadow DOM) |
| Language | TypeScript (strict mode) |
| Package manager | pnpm |
| Testing | Vitest + Playwright |
| Linting | ESLint + Prettier |
| State | @wxt-dev/storage |

Note: The extension was originally built with Lit but migrated to vanilla HTMLElement-based web components to eliminate all innerHTML usage from the build output, which is required for Mozilla Add-ons (AMO) validation compliance.

Platform Profiles

Profiles are YAML files that define CSS selectors for detecting trackable items on task/issue management platforms. Each profile specifies:

• Domains — hostnames where the platform is deployed (supports subdomains)
• Selector sets — one or more contexts (e.g. "detail view", "list view"), each with:
• isSupported — gate selector that determines if the page has trackable items
• issueId — extracts the issue/task identifier
• issueTitle — extracts the issue/task title
• itemContainer — (optional) wraps individual trackable items for multi-item pages
• widgetAnchor — (optional) where to inject the track button

Profiles support multi-version platforms via multiple selector sets with different gate selectors. The matcher tries each context in order and uses the first one whose gate matches.

Writing a Profile

Enable Debug Mode in the extension settings to access the profile editor. Write YAML, set a target domain, and navigate to a page on that domain. Matched elements are highlighted with color-coded overlays:

| Color | Selector |
| ------ | -------------------- |
| Green | isSupported (gate) |
| Blue | issueId |
| Purple | issueTitle |
| Amber | itemContainer |
| Red | widgetAnchor |

Release Process

# 1. Bump version in package.json
# 2. Commit and tag
git add package.json
git commit -m "chore: bump version to X.Y.Z"
git tag vX.Y.Z
git push && git push --tags

# 3. CI pipeline runs: lint → test → build → package → release
# 4. Manually trigger publish jobs in GitLab CI for Chrome Web Store / Firefox AMO


License

This project is licensed under the GNU General Public License v3.0 or later.