Kimai Time Tracker EN

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 val…