# CodeHeat

A Visual Studio Code extension that tracks how much time you actually spend in
each project and each file, and paints that time back onto the file explorer as
a heatmap.

Everything stays on your machine. There is no account, no server, no sync and
no telemetry — the extension writes a single JSON file into VS Code's own
extension storage directory and nothing leaves it.

## What it does

- **Per-project and per-file time tracking.** A 30-second heartbeat credits time
  to the file you are currently working in, but only while you are actually
  active. Typing, moving the cursor and switching editors all count as activity.
- **Idle detection.** After a configurable period with no editor activity
  (3 minutes by default) the heartbeat stops crediting time, so a session left
  open overnight does not turn into eight tracked hours.
- **Explorer heatmap.** Every file that has tracked time gets a badge from 1 to
  5 in the explorer, coloured blue → green → yellow → orange → red. The scale is
  relative to the hottest file in that project, so it shows where the work went
  rather than an absolute number. Hovering a file shows the exact time.
- **Status bar clock.** The left of the status bar shows the total time tracked
  in the current project. Click it to open a summary.
- **Summary view.** A panel listing the 25 hottest files in the project as a bar
  chart, plus the project total.
- **Export and clear.** Export the whole dataset as JSON, or wipe the data for
  the current project only.

Time is attributed to a file only when that file belongs to an open workspace
folder. Files opened outside a workspace folder are not tracked.

## Requirements

- Visual Studio Code 1.85.0 or newer.

That is the whole list. The extension is plain JavaScript against the VS Code
API with no runtime dependencies and no build step.

## Installing

The extension is not on the Marketplace. Two ways to install it:

**Copy it into the extensions folder**

```bash
git clone https://github.com/dualfroz/codeheat.git ~/.vscode/extensions/codeheat
```

Then restart VS Code.

**Or package it into a .vsix**

```bash
npx @vscode/vsce package
code --install-extension codeheat-0.1.0.vsix
```

## Commands

Open the command palette and search for "CodeHeat":

| Command | What it does |
| --- | --- |
| CodeHeat: Show Time Summary | Opens the per-file bar chart for the current project |
| CodeHeat: Toggle Tracking | Pauses or resumes tracking; the status bar shows the state |
| CodeHeat: Export Data as JSON | Writes the full dataset to a file you choose |
| CodeHeat: Clear Data for This Project | Deletes tracked data for the current project only |

## Settings

| Setting | Default | Meaning |
| --- | --- | --- |
| `codeheat.idleThresholdMinutes` | `3` | Minutes of no editor activity before tracking pauses |
| `codeheat.heatmapEnabled` | `true` | Show the heat badges in the file explorer |

## Where the data lives

A single file, `codeheat-data.json`, inside VS Code's global storage directory
for this extension. On Linux that is usually:

```
~/.config/Code/User/globalStorage/foksiu-local.codeheat/codeheat-data.json
```

The structure is straightforward — projects keyed by their absolute workspace
path, each with a total and a map of workspace-relative file paths to seconds:

```json
{
  "projects": {
    "/home/you/work/api": {
      "label": "api",
      "totalSeconds": 7230,
      "files": { "src/server.js": 4100, "README.md": 300 }
    }
  }
}
```

Because projects are keyed by absolute path, moving a project directory starts
a new entry rather than continuing the old one.

## Tested on

Linux Mint 22.2 with the Cinnamon desktop, VS Code 1.85+. Nothing in the
extension is platform-specific, so it should work anywhere VS Code runs, but
that is the only environment it has actually been used in.

## Licence

No licence has been chosen yet.