Heildamm Time Tracker

A coding time tracker that never leaves your machine — no account, no cloud, no data limits.

Heildamm Time Tracker monitors your coding activity automatically, records time spent per file/project/branch/language, and gives you a rich, real-time dashboard right inside VS Code. Unlike most time trackers in this space, nothing is ever sent to a server: every entry is written, encrypted, and read from your own disk.

Why Heildamm over WakaTime, Code Time, RescueTime, etc.

Two features you won't find anywhere else

• Privacy Audit — Heildamm doesn't just protect your own data, it scans your other installed VS Code extensions for telemetry/analytics signals (known tracking dependencies, suspicious config keys, keywords, publisher reputation) and gives each one a risk score (high / medium / low / safe), plus a pointer to the setting that disables its telemetry when one exists.
• Software Archaeology Report — correlates your tracked time with git commit history to show cost-per-commit, productivity score, and which commits took unexpectedly long. Turns raw time data into a forensic view of where effort actually went.

Key Features

• Real-time Dashboard: KPIs, daily activity chart, project/branch/language/file breakdowns, a GitHub-style contribution heatmap, monthly view, top days, an hour-of-day "most productive hour" chart, and a week-over-week comparison — all updating live as you code, with no page reloads or flicker
• Heildamm Wrapped: a shareable, Spotify-Wrapped-style recap (total hours, favorite language, top project, longest streak, peak hour) exportable as a PNG, generated entirely on your machine
• Accurate Idle Detection: won't count time while you're away from the keyboard, even if the window stays "focused" (screen locked, laptop lid closed without sleeping, etc.)
• Language, Project & Branch Tracking: every session records language, git branch, and project automatically
• Daily Goals & Streaks: set a daily coding goal with a notification on completion, and track your current/longest streak
• Break Reminders: optional configurable reminder after N minutes of continuous coding
• Encrypted Local Storage: AES-256-GCM at rest, automatic backup/recovery with integrity verification, and gzip consolidation of old data so files don't pile up forever
• Status Bar Widget: quick glance at today's time (toggle: total vs. current project)
• Export Formats: CSV, Markdown, and JSON exports for reporting and sharing
• Bilingual UI: Portuguese/English toggle in the dashboard

Installation

Prerequisites

• VS Code version 1.80.0 or higher
• Git configuration (for author name detection)

Quick Start

1. Build the extension:

cd .vscode-time-tracker
npm install
npm run esbuild

2. Install the extension:

npm run package

3. Open VS Code and install from VSIX:
   • Press Ctrl+Shift+P
   • Type: "Install from VSIX"
   • Select the generated .vsix file

Or for development:

npm run esbuild-watch
npm run test

Usage

Commands

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) and type any of the following commands:

Analytics & Reporting

• Show All Stats: View total time, top files, and language breakdown
• Show Today: Display today's tracking summary
• Generate Software Archaeology Report: Analyze time investment per git commit

Data Management

• Open Dashboard: Open the interactive dashboard for visual analytics
• Export Data to CSV: Export tracking data in spreadsheet-friendly format
• Export Data to Markdown: Export as markdown report with summaries
• Open Data Directory: Access tracking files directly (in ~/.heildamm-time-tracker/)
• Clear Data: Remove all tracking data (with confirmation)

Display

• Toggle Status Bar: Switch between total time and per-project time display

Status Bar

A time widget appears in the status bar showing today's total tracked time. Click it to toggle between:

• Total time: Total hours tracked today across all projects
• Project time: Hours tracked in the current project today

Software Archaeology

The "time-to-commit ratio" feature is what transforms Heildamm from a tracker into a software archaeology tool.

What It Does

It analyzes the relationship between time investment and git commits to show:

• Cost per Commit: Average time spent before each commit
• Productivity Score: Time vs. actual changes (commits without thrashing)
• Effort Patterns: Daily/hourly peaks and productivity trends
• Optimization Opportunities: Commits that took unexpectedly long

Example Report

## Summary
- Total Time Invested: 42h 15m
- Total Commits: 87
- Average Time per Commit: 29m
- Commit Velocity: 2.9 commits/day

## Optimization Opportunities
- abc1234: Refactor auth system → 2h 45m (vs 29m average)
  Files: 12 | Changes: +450-320

Use Cases

• Portfolio: Show the real effort behind projects
• Retrospectives: Data-driven team discussions
• Freelance Invoicing: Transparent hour breakdown by feature
• Performance Analysis: Identify productivity patterns and bottlenecks

→ See SOFTWARE_ARCHAEOLOGY.md for full documentation.

Data Storage

Location

~/.heildamm-time-tracker/

Format

Daily JSON file: YYYY-MM-DD.json

{
  "date": "2026-04-05",
  "entries": [
    {
      "timestamp": 1712282880000,
      "duration": 1800,
      "file": "extension.ts",
      "language": "typescript",
      "project": "create-heildamm",
      "author": "gabriel glatz"
    }
  ]
}

Architecture

Modular Design

• extension.ts - Main entry point and command registration
• tracker.ts - Activity recording and session management
• storage.ts - Data persistence layer
• context.ts - VS Code environment context
• stats.ts - Analytics and metric calculations
• constants.ts - Configuration and command definitions

Security

Data Encryption

All tracking data is encrypted automatically using AES-256-GCM to prevent unauthorized access or modification:

• Random Encryption Keys: Each user's data is protected with a cryptographically random 256-bit key
• Machine-Locked Storage: Keys are stored locally in ~/.heildamm-time-tracker/.encryption-key (never committed to repositories)
• Tampering Detection: GCM authentication ensures data integrity
• Transparent Encryption: Automatic encryption/decryption on read/write operations

Important Notes

• The .encryption-key file is sensitive - do not share or backup without proper security measures
• Data is encrypted at rest and cannot be manually edited without the encryption key
• Different users on the same machine get different encryption keys
• Encryption is automatic - no configuration needed

Privacy

• All data remains on your local machine
• No tracking data is sent to external services
• Git integration only reads local git history (no external API calls)

License

MIT