Chrontic Time Tracker for VS Code

A VS Code extension that automatically tracks time spent on JIRA tickets by detecting ticket names from Git branch names and integrates with the Chrontic time tracking service.

Features

• Automatic Time Tracking: Tracks time spent on projects at configurable intervals (default: 1 minute)
• Smart Activity Detection: Only tracks when you're actively coding (typing, moving cursor, switching files)
• Inactivity Timeout: Automatically stops tracking after 5 minutes of inactivity
• JIRA Integration: Automatically detects JIRA ticket IDs from Git branch names using regex pattern
• Branch Name Fallback: Uses branch name (prefixed with project name) when no JIRA ticket is detected
• Local Timezone Support: Sends timestamps in your local timezone (not UTC)
• Configurable Settings: Customize API endpoint and tracking intervals
• VS Code Notifications: Get notified when time entries are recorded
• Duration Limits: Minimum 2 minutes, maximum 25 minutes per entry (prevents accidental long sessions)

Installation

From VSIX File

1. Download the latest .vsix file from the releases
2. Open VS Code
3. Go to Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
4. Click the ... menu → Install from VSIX...
5. Select the downloaded .vsix file

From Source

cd chrontic-vscode-extension
npm install
npm run compile

To package the extension:

npm run package

Configuration

Open VS Code Settings (Ctrl+, or Cmd+,) and search for "Chrontic":

Essential Settings (Always Visible)

• API Key: Your Chrontic API authentication key (required)
• Enable Auto Tracking: Toggle to enable/disable automatic time tracking (default: true)
• Activity Timeout: Minutes of inactivity before tracking stops (1-60, default: 5)

Advanced Settings (Development Build Only)

These settings are hidden in production builds and use hardcoded defaults:

• API Base URL: The base URL of your Chrontic API (default: http://localhost:8086 dev, https://api.chrontic.com production)
• Tracking Interval: How often to check and send time entries in minutes (1-60, default: 1)
• Min Trackable Duration: Minimum minutes required to create an entry (1-60, default: 2)
• Max Trackable Duration: Maximum minutes per entry to prevent runaway tracking (1-120, default: 25)

Settings JSON (Development)

{
  "chrontic.apiKey": "your-api-key-here",
  "chrontic.enableAutoTracking": true,
  "chrontic.activityTimeoutMinutes": 5,
  "chrontic.apiBaseUrl": "http://localhost:8086",
  "chrontic.trackingIntervalMinutes": 1,
  "chrontic.minTrackableDurationMinutes": 2,
  "chrontic.maxTrackableDurationMinutes": 25
}

Settings JSON (Production)

{
  "chrontic.apiKey": "your-api-key-here",
  "chrontic.enableAutoTracking": true,
  "chrontic.activityTimeoutMinutes": 5
}

How It Works

1. Extension Activation: Activates when you open a workspace (with or without Git)
2. Activity Detection: Monitors your activity by tracking:
   • Text document changes (typing)
   • Cursor movements (keyboard/mouse)
   • File switching
   • ❌ Ignores: window focus, output logs, programmatic changes
3. Timer Check: Every minute (configurable), the extension checks:
   • Are you active? (activity within last 5 minutes)
   • If inactive → stops tracking, resets state
   • If active → retrieves current Git branch and JIRA ticket
4. Time Entry Creation: When duration reaches minimum threshold (2 minutes):
   • JIRA ticket found: Uses ticket ID as description (e.g., PROJ-123)
   • No JIRA ticket: Uses workspace name + branch name (e.g., MyProject_feature/add-authentication)
   • Sends entry with local timezone timestamps and rounded hours (2 decimals)
5. Duration Limits:
   • Minimum: 2 minutes (prevents spam)
   • Maximum: 25 minutes (prevents runaway tracking if you forget to switch branches)
6. Notifications: Success/error messages shown in VS Code

JIRA Ticket Detection

The extension uses the regex pattern ([A-Z]{2,10}-\d+) to detect JIRA tickets from branch names.

Examples of supported branch names:

• feature/PROJ-123-new-feature → PROJ-123
• bugfix/ABC-456 → ABC-456
• hotfix/TICKET-789-urgent-fix → TICKET-789

Development

Prerequisites

• Node.js (v20 or higher)
• npm or yarn
• VS Code

Setup

cd chrontic-vscode-extension
npm install

Build

npm run compile

Watch Mode

npm run watch

Testing

Press F5 in VS Code to launch the Extension Development Host with the extension loaded.

Packaging

Development Build (All Settings Visible)

npm run package

This creates a development .vsix file with ALL settings visible in VS Code UI. Use this for:

• Local development and testing
• Internal testing with configurable API endpoints
• Debugging with custom timing parameters

Production Build (Minimal User Settings)

npm run package:prod

This creates a production .vsix file for marketplace/end-user distribution with:

• ✅ Essential settings visible: API Key, Enable Auto Tracking, Activity Timeout
• ❌ Advanced settings hidden: API Base URL, Tracking Interval, Min/Max Duration
• 🔒 Hardcoded production defaults to prevent misconfiguration

Production defaults (hidden from users):

• API Base URL: https://api.chrontic.com
• Tracking Interval: 1 minute
• Min Trackable Duration: 2 minutes
• Max Trackable Duration: 25 minutes

The production build automatically restores development configuration after building.

Manual Configuration Restore

If needed, restore development configuration:

npm run restore-dev

See BUILD.md for detailed build documentation.

Troubleshooting

Extension not tracking time

1. Check that Enable Auto Tracking is enabled in settings
2. Verify your API Key is correctly configured
3. Ensure your API Base URL points to your Chrontic backend
4. Check the Output panel (View → Output → Select "Chrontic Time Tracker")
5. Verify you're in a Git repository with a valid branch

JIRA ticket not detected

1. Verify your branch name matches the pattern (e.g., PROJ-123)
2. Default pattern matches formats like: PROJ-123, ABC-456
3. Check the Output panel for Git-related errors

Time entries not appearing in Chrontic

1. Verify the Chrontic API is running and accessible
2. Check that the API endpoint URL is correct
3. Ensure the API key is valid
4. Review the Output panel for API errors

Requirements

• VS Code 1.80.0 or higher
• Git repository in your workspace
• Running Chrontic backend service

License

[Add your license information here]

Support

For issues and questions, please refer to the project's issue tracker.