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+)

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.

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

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)

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.

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.

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

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:

Release Process

# 1. Bump version in package.json

License

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