RepoBeats

Track the music behind your code.

RepoBeats is a VS Code extension that connects to Spotify and records what you listen to while coding — per workspace. After a session, you can explore your top tracks, artists, coding hours, and listening patterns through a built-in dashboard.

Every codebase has a soundtrack. RepoBeats captures it.

Why RepoBeats?

Most developers listen to music while coding. That music is context — it reflects focus, mood, and energy at a specific point in a project's history. RepoBeats treats that context as data worth keeping.

• You can look back at a feature branch and see exactly what was playing during those late-night sessions.
• You can compare the vibe of different projects: one is all high-energy metal, another is ambient instrumentals.
• You can export a full music analysis of everything you listened to while building something.

It's a small thing, but it adds a layer of personal history to your work that didn't exist before.

Features

Core Tracking

• Per-workspace music history — each VS Code workspace has its own listening log
• Session detection — sessions start when you open a workspace and stop after configurable inactivity (default: 5 min idle)
• Status bar — currently playing track shown at the bottom of VS Code at all times

Analytics & Dashboard

• Top tracks and artists — ranked by listened time and play count
• Repeat play detection — if you listen to a 3-min song for 9 minutes, it counts as 3 plays
• Most productive hours — bar chart of track counts by hour of day
• Music heatmap — GitHub-style grid showing listening activity from first session to today
• Session timeline — scrub through a session and see what was playing at each moment
• Fun facts — auto-generated stats like night owl detection, total listening time, most repeated track

Export & Share

• Export Analysis — generates a .md file with overview, listening habits, top tracks, top artists, and highlights
• README section generator — inserts a "Coded to" section with your top tracks directly into your project's README
• Share card — exports a styled dark-theme HTML card (560px) with stats, insights grid, and clickable Spotify track links (optional workspace name blur, copy as image)

Privacy

• All data is stored locally only — nothing leaves your machine
• No accounts, no cloud sync, no telemetry
• Data lives at VS Code's globalStorageUri (managed by VS Code, not in your project)

Install

From VS Code Marketplace:

1. Open VS Code → Extensions (Ctrl+Shift+X)
2. Search RepoBeats
3. Click Install

Or install directly: marketplace.visualstudio.com/items?itemName=erenisci.repobeats

Getting Started

Prerequisites

• VS Code 1.85 or later
• A Spotify account (free or premium — both work)
• Node.js 18+ (for building from source)

Run from Source (Development)

git clone https://github.com/erenisci/repobeats.git
cd repobeats
cp .env.example .env
# .env already has a working Client ID — no changes needed for basic use
npm install
npm run generate-config

Open the project in VS Code and press F5. A new Extension Development Host window opens with RepoBeats active.

Connect to Spotify

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run RepoBeats: Connect Spotify
3. Your browser opens the Spotify authorization page
4. Approve the permissions
5. The browser shows "Connected!" — you can close the tab
6. RepoBeats starts tracking automatically

Commands

Settings

How It Works

Authentication

RepoBeats uses Spotify's PKCE OAuth flow — no client secret is involved. When you run "Connect Spotify", a temporary local server listens on 127.0.0.1:3000 to receive the authorization callback. Tokens are stored in VS Code's encrypted SecretStorage and refreshed automatically.

Session Lifecycle

Workspace opens
  └─ Spotify connected? → start session (UUID)
       └─ poll Spotify every 5s (configurable)
            └─ new track detected? → save to local JSON
            └─ same track playing? → update listened duration
  └─ idle timeout → end session
  └─ next keystroke → resume (new session)
  └─ same song across sessions? → recorded in both, but not double-counted in play stats

Storage

Data is stored as JSON files at VS Code's globalStorageUri — one file per workspace. The location is OS-managed and not inside your project.

{
  "workspaceId": "my-project",
  "createdAt": "2026-03-11T19:41:45.000Z",
  "sessions": [
    {
      "id": "a1b2c3d4-...",
      "workspaceId": "my-project",
      "startedAt": "2026-03-13T21:00:00.000Z",
      "endedAt": "2026-03-13T23:00:00.000Z"
    }
  ],
  "tracks": [
    {
      "id": "spotify-track-id",
      "name": "Resonance",
      "artist": "HOME",
      "album": "Resting State",
      "uri": "spotify:track:...",
      "playedAt": "2026-03-13T21:05:12.000Z",
      "sessionId": "a1b2c3d4-...",
      "listenedMs": 195000,
      "durationMs": 208000
    }
  ],
  "audioFeatures": []
}

Architecture

Key Modules

For Developers

Setup

git clone https://github.com/erenisci/repobeats.git
cd repobeats
cp .env.example .env
# Edit .env — set SPOTIFY_CLIENT_ID to your own Spotify app's Client ID
npm install
npm run generate-config   # generates src/config.generated.ts from .env

Create your own Spotify app at developer.spotify.com/dashboard:

• Redirect URI: http://127.0.0.1:3000/callback
• Copy your Client ID into .env

Build Commands

npm run generate-config   # must run after any .env change
npm run compile           # one-time TypeScript build → out/
npm run watch             # watch mode (used by F5)
npm run lint              # ESLint
npx tsc --noEmit          # type-check without emitting

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

Contributing

See CONTRIBUTING.md for the full guide — setup, PR process, commit style, and roadmap.

License

MIT — see LICENSE for details.

Copyright 2026 Eren İşci