feat: WakaTime integration for IDE activity tracking

[kianhub]

Summary

• Adds WakaTime integration to track Maestro coding sessions as IDE activity in WakaTime dashboards
• Users only need to toggle WakaTime on and enter their API key in Settings — CLI installation, version updates, and heartbeat management are fully automatic
• Follows the official WakaTime plugin creation guide

What's included

Settings UI

• WakaTime toggle and API key input added to the Usage & Stats section in General settings
• Password-masked API key field with validation on blur (green checkmark / red X)
• CLI availability check with auto-install status feedback
• Falls back to reading API key from ~/.wakatime.cfg if not set in Maestro

Main Process

• WakaTimeManager class (src/main/wakatime-manager.ts) handles:
  • Auto-install: Downloads platform-specific CLI binary from GitHub releases to ~/.wakatime/
  • Auto-update: Daily version check against GitHub API, re-downloads if outdated
  • Heartbeats: Sent on AI output (data events) and AI reasoning (thinking-chunk events) for interactive sessions, plus query-complete for batch/auto-run; debounced to 2 min per session
  • Entity type: Uses --entity-type app with --entity Maestro (app name, not file path) per WakaTime spec
  • Language detection: Detects project language from manifest files in the session's cwd (tsconfig.json → TypeScript, Cargo.toml → Rust, go.mod → Go, pyproject.toml → Python, etc.) — cached per session
  • Branch detection: Detects current git branch via git rev-parse --abbrev-ref HEAD and passes via --alternate-branch — cached per session
  • Plugin identification: --plugin maestro/{version} maestro-wakatime/{version} per official spec
  • Category: Uses ai coding category (dedicated WakaTime category for AI-assisted work)
• Process listener (wakatime-listener.ts) wires heartbeats to:
  • data events — fires on every AI stdout chunk (covers interactive sessions); skips terminal sessions
  • thinking-chunk events — fires during AI extended thinking/reasoning, ensuring long reasoning periods are tracked
  • query-complete events — fires for batch/auto-run processes
  • exit events — cleans up per-session debounce, branch, and language caches
• IPC handlers for CLI check and API key validation, using WakaTimeManager for auto-install
• Auto-install triggered on startup (if enabled) and when user toggles WakaTime on

Tests

• 48 WakaTime-specific tests across:
  • wakatime-manager.test.ts — heartbeats, debouncing, CLI detection, auto-install, version checking, config fallback
  • wakatime.test.ts (IPC handlers) — handler registration, CLI check, API key validation
  • wakatime-listener.test.ts — data events, thinking-chunk events, terminal session filtering, query-complete, exit cleanup
  • SettingsModal.test.tsx — CLI status UI states
  • useSettings.test.ts — settings persistence

New files

File	Purpose
src/main/wakatime-manager.ts	CLI management, heartbeats, language/branch detection, auto-install/update
src/main/ipc/handlers/wakatime.ts	IPC handlers for renderer
src/main/preload/wakatime.ts	Preload bridge (window.maestro.wakatime)
src/main/process-listeners/wakatime-listener.ts	AI activity → heartbeat wiring

Key design decisions

• --entity-type app with --entity Maestro: WakaTime expects an application name (not a file path) for the app entity type. The project directory is passed via --project instead.
• data + thinking-chunk events: The query-complete event only fires for batch-mode processes with querySource set, which the renderer doesn't provide for interactive sessions. Listening on data and thinking-chunk ensures heartbeats fire for all AI activity including extended reasoning.
• Project language detection: Checks for well-known manifest files (tsconfig.json, Cargo.toml, go.mod, etc.) rather than scanning all file extensions — fast, deterministic, and covers the common case.
• 2-minute debounce: Matches WakaTime's own deduplication window. WakaTime uses a 15-minute timeout to join heartbeats into durations, so continuous activity within 2-minute intervals produces accurate time tracking.

Test plan

• Enable WakaTime in Settings → General → Usage & Stats
• Verify CLI auto-installs (check ~/.wakatime/ for binary)
• Enter API key → blur field → verify validation indicator appears
• Run a query in an interactive AI session → verify heartbeat appears in WakaTime dashboard
• Verify WakaTime dashboard shows correct project language (not "Other")
• Verify WakaTime dashboard shows correct git branch
• Run an auto-run task → verify heartbeat appears in WakaTime dashboard
• Verify npm run lint and npm run test pass

[pedramamini]

Review: WakaTime Integration

Solid contribution — well-structured, follows existing patterns, good test coverage (48 tests). Clean separation across manager, listener, IPC handlers, preload, and settings. A few items to address below.

Key positives:

• Concurrent install guard, per-session debounce/caching, fire-and-forget heartbeats
• Clean file separation following established project patterns
• Correct --entity-type app with --entity Maestro per WakaTime spec
• path.basename(projectDir) for project name matches VS Code behavior

Items to address:

1. 🐛 Double handler registration — registerWakatimeHandlers is called both in index.ts:setupIpcHandlers() and added to registerAllHandlers() in handlers/index.ts
2. ⚡ Performance on disabled path — data event listener fires on every stdout chunk, doing work even when WakaTime is disabled (the default)
3. 🔧 projectPath vs cwd inconsistency in listener
4. 🧹 Cosmetic — stray double blank line in SettingsModal

See inline comments for details.

[pedramamini]

🐛 Double handler registration — registerWakatimeHandlers is called here inside registerAllHandlers() AND separately in index.ts:setupIpcHandlers(). The app uses setupIpcHandlers() directly (not registerAllHandlers()), so this line is dead code today. But if registerAllHandlers is ever called, it would double-register the IPC handlers and crash.

The wakatimeManager field was also added to the HandlerDependencies interface (line 156), but nothing currently passes it — type-level landmine.

Suggested fix: Remove the registerAllHandlers addition and the HandlerDependencies change entirely, since index.ts calls registerWakatimeHandlers directly.

[pedramamini]

⚡ Performance on the disabled path — The data event fires on every single stdout chunk from AI agents. This function runs processManager.get(), path.basename(), and then sendHeartbeat() (which hits settingsStore.get('wakatimeEnabled')) on every chunk — even when WakaTime is disabled (the default).

Since most users won't have WakaTime enabled, consider adding an early bail-out in the data listener that checks the enabled flag before doing any work. You could cache the enabled state and listen on store.onDidChange('wakatimeEnabled') to update it.

// In setupWakaTimeListener:
let enabled = settingsStore.get('wakatimeEnabled', false);
settingsStore.onDidChange('wakatimeEnabled', (v) => { enabled = !!v; });

processManager.on('data', (sessionId: string) => {
  if (!enabled) return; // fast path — no store reads, no lookups
  heartbeatForSession(processManager, wakaTimeManager, sessionId);
});

[pedramamini]

🔧 projectPath vs cwd inconsistency — This passes managedProcess.cwd as the third arg to sendHeartbeat, which is used for language detection and branch detection. But projectPath (when available) would be more accurate since cwd might be a subdirectory. You already use projectPath || cwd for the project name — the cwd param should match:

const projectDir = managedProcess.projectPath || managedProcess.cwd;
const projectName = projectDir ? path.basename(projectDir) : sessionId;
void wakaTimeManager.sendHeartbeat(sessionId, projectName, projectDir);

[pedramamini]

🧹 Stray double blank line here.

[pedramamini]

Minor: fs.readdirSync(cwd) on the main process for the *.csproj glob pattern. Cached per session so it only hits once, but it's a synchronous I/O call on the event loop. Fine for now since the cache mitigates it — just flagging.