113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# 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.
|