⏱️ Dev Timekeeper

Private, offline-first coding time tracker for VS Code.
Automatically records your active coding time per file, directory, workspace, day, and hour—with zero cloud dependencies, zero accounts, and zero telemetry.

🌟 Highlights & Capabilities

• 🛡️ 100% Local & Offline: All data is stored locally in ~/.vscode-time-tracker/ (JSON). No data ever leaves your computer.
• ⚡ Precision Idle & Sleep Detection: Uses an OS-level background input heartbeat combined with gap-rejection algorithms so AFK time, system sleep, and laptop suspension are never counted.
• 🔄 Multi-Instance & Cross-Editor Coordination: Work seamlessly across multiple VS Code windows, Antigravity IDE instances, and separate workspaces without double-counting, race conditions, or file collisions.
• 🗂️ Project Groups & Multi-Repo Aggregation: Unify multi-folder repos, microservices, and versioned projects (frontend, backend, v2, v3) into single aggregate tracked projects with collapsible sub-repo breakdowns.
• 📊 Fluid Responsive Dashboard: Powered by CSS Container Queries, auto-reflowing stats, 24-hour radial clock, 30-day trends, weekly stacked charts, 6-month historical comparisons, language bubble map, and sortable tables.
• 📸 Visual Share Card Generator: Render and export sleek, customizable summary graphics directly to .png with one-click OS file manager integration.
• 📂 Multi-Workspace & Project Auto-Mapping: Automatically attributes active editor files to their respective git repositories or root workspace folders, while filtering out system junk (AppData, node_modules, site-packages, temp).
• 🎨 Customizable Layout: Hide or reveal dashboard sections according to your workflow preference; layout settings persist across sessions.

🧠 How the Active Tracking Engine Works

Unlike basic activity timers that continuously increment whenever VS Code is open, Dev Timekeeper enforces strict active-time verification.

1. OS-Level Idle Detection (scripts/heartbeat.ps1)

• Runs a lightweight background process monitoring user interaction timeouts via Win32 GetLastInputInfo.
• Automatically pauses active session accumulation if no system-wide keyboard or mouse input occurs for 5 minutes (300,000 ms).
• Singleton Provider: Only 1 background monitor runs across all open editor windows.

2. 20-Minute VS Code Inactivity Hard Limit

• Tracks continuous interaction timestamps for keystrokes, editor selections, tab switches, file saves, and agent code edits.
• Browser Testing Grace Period: Allows up to 20 minutes of testing outside VS Code (e.g. in Chrome or terminal).
• Auto-Pause: If 20 minutes pass without any VS Code interaction, tracking automatically pauses.

3. Window Minimization & Sleep Rejection

• Immediately pauses active session accumulation when VS Code is minimized or loses focus to prevent sleep time leakage.
• When your machine enters sleep mode or VS Code is suspended, elapsed sleep time is automatically discarded upon wakeup.

4. Cross-Editor Active Lease Coordination (active_session.json)

• When switching between editors (e.g. VS Code $\leftrightarrow$ Antigravity), the actively focused window claims the active lease. Background windows immediately yield, ensuring 1 physical hour of coding strictly registers as 1 hour.
• Atomic OS file locking (data.json.lock) prevents concurrent write collisions and Windows EBUSY errors across multiple windows.

📊 Dashboard Visual Analytics Architecture

Open the dashboard anytime by clicking the status bar item or running Time Tracker: Show Dashboard.

1. Overview Cards: Quick KPI summary of Today, Yesterday, This Week, Last Week, This Month, Last Month, Active Days, Daily Average, Lifetime Coding Time, and Top Project.
2. Time of Day (Radial 24h) Clock: Circular 24-hour polar clock chart (00:00 to 23:00) with concentric guide rings and dusk-to-dawn color gradients, visualizing your peak focus hours and daily rhythm.
3. Lifetime Per-Project Breakdown: Comparative lifetime metrics for all active projects.
4. Weekly Stacked Activity: Day-by-day stacked breakdown for the last 7 days.
5. 30-Day Trend Chart: Interactive stacked area chart detailing your top 6 primary projects alongside aggregated secondary projects.
6. 6-Month History Comparison: High-level bar chart tracking monthly totals across the last two quarters.
7. Language Distribution Chart: Automatic language detection based on extension parsing (TypeScript, Python, JavaScript, CSS, HTML, Go, Rust, C++, Java, SQL, etc.).
8. Sortable File & Project Table: Detailed breakdown of every project and file tracked, supporting column sorting and instant search filtering.

📸 Visual Share Card Generator

Transform your coding milestones into exportable PNG graphics:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
2. Run Time Tracker: Generate Share Card.
3. Select projects, customize date range (Last 7 Days, Last 30 Days, or Custom), and click Export PNG.
4. The extension opens a native OS Save Dialog and provides a Show in Folder shortcut upon save.

⌨️ Command Reference

🔒 Privacy & Data Security Architecture

Dev Timekeeper is built around strict data privacy principles:

• Zero Cloud Calls: No network requests, external APIs, telemetry, or remote analytics.
• Local Storage Directory: All persistent records are stored in your user home directory:
  • Data File: ~/.vscode-time-tracker/data.json
  • Settings File: ~/.vscode-time-tracker/settings.json
  • Idle Heartbeat File: ~/.vscode-time-tracker/heartbeat.json
• Atomic File Writes: To prevent data corruption during unexpected shutdowns, storage updates write to data.json.tmp, backup existing data to data.json.backup, and perform atomic renames.
• Automated Junk Filtering: Path normalization automatically excludes temporary files, virtual environments, system caches (AppData, site-packages, temp, .aws, .zip).

📦 Installation & Setup

Option 1: Install from Open VSX Registry (Recommended for VSCodium / VS Code / Cursor / Gitpod)

1. Search for Dev Timekeeper (DebjyotiGhosh.dev-timekeeper) in your editor's Extensions view (Ctrl+Shift+X / Cmd+Shift+X).
2. Click Install.
3. Direct Registry Link: open-vsx.org/extension/DebjyotiGhosh/dev-timekeeper

# VSCodium / Open VSX CLI
codium --install-extension DebjyotiGhosh.dev-timekeeper

# VS Code CLI
code --install-extension DebjyotiGhosh.dev-timekeeper

Option 2: Install from VSIX Release

1. Download the latest .vsix package from Open VSX Registry or GitHub Releases.
2. Open VS Code / VSCodium → Extensions tab (Ctrl+Shift+X / Cmd+Shift+X).
3. Click the ... menu in the top-right corner → Install from VSIX...
4. Choose the downloaded DebjyotiGhosh.dev-timekeeper-*.vsix file.

Option 3: Build from Source

# Clone the repository
git clone https://github.com/debjyoti71/time_extension.git
cd time_extension

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package VSIX extension package
npm run package:vsix

📚 Documentation Hub

For full technical documentation, architecture specs, and feature guides, explore the project documentation:

• ✨ Features Specification — Detailed feature showcase, Webview dashboard breakdown, and settings reference.
• 📖 Product Specification — Feature requirements, user stories, and data schemas.
• 📐 Design Document — System architecture, event lifecycle, and UI component designs.
• 🛠️ Developer Guide — Local development workflow, build scripts, and testing setups.

🐞 Issues & Community Support

Contributions, bug reports, and feature suggestions are welcome!

• 🐛 Report a Bug — Encountered an issue? Open a bug report with reproduction steps.
• 💡 Request a Feature — Have an idea for a new dashboard chart or tracking feature? Submit a feature request.
• 💬 View All Issues — Browse ongoing discussions and reported issues.

📄 License & Author

Distributed under the MIT License. See LICENSE for full details.

Developed by Debjyoti Ghosh — https://debjyoti-ghosh.in/