Local-first docs

Code Pulse documentation.

Install the VS Code extension, desktop app, CLI, local daemon, and MCP server, then read the same local developer activity signal from each surface.

Overview

Code Pulse is local-first developer time tracking and AI-activity observability. It has three surfaces: VS Code extension, desktop app (Tauri+Svelte), and CLI + local daemon + MCP server.

Quick start

1

VS Code-only

Install the extension, reload VS Code, and open Code Pulse: Show Dashboard.

2

Desktop

Start the daemon, then open the Tauri desktop app for Timeline, Tokens, Recovery, and AI Sources.

3

CLI + daemon

Run codepulse doctor and codepulse status to validate the local service.

4

AI agents

Connect the MCP server so local activity, token, and session stats are queryable by compatible agents.

Install — VS Code extension

Install from the Marketplace: umutkorkmaz.code-pulse-tracker

Or install the local .vsix:

code --install-extension code-pulse-tracker-1.2.2.vsix

Or package from source: 

git clone https://github.com/UmutKorkmaz/code-pulse.git
cd code-pulse
npm install
npm run package
code --install-extension code-pulse-tracker-1.2.2.vsix

Reload the window, then open Code Pulse from the Command Palette with Code Pulse: Show Dashboard.

Install — Desktop app

Build the desktop app from source:

git clone https://github.com/UmutKorkmaz/code-pulse
cd code-pulse/platform && npm install && npm run build
cd apps/desktop && npm run tauri:build

The native installer is in src-tauri/target/release/bundle/. For development, run npm run tauri:dev.

After a release is published, install from GitHub Releases with:

gh release download v1.2.2 \
  --repo UmutKorkmaz/code-pulse \
  --pattern "*.dmg" \
  --dir dist/releases
open dist/releases/*.dmg

The desktop app needs the daemon running. Dev mode needs VITE_DAEMON_TOKEN=$(cat ~/.codepulse/token) npm run dev.

Install — CLI & daemon

The daemon binds 127.0.0.1:7842 for HTTP and :7843 for WebSocket. Start it with: 

node platform/apps/daemon/dist/main.js

CLI commands:

codepulse doctor
codepulse status
codepulse registry
codepulse daemon

Sample codepulse doctor output:

$ codepulse doctor
✓ data-directory        ~/.codepulse
✓ auth-token            present, mode 0600
✓ database              SQLite ready
✓ daemon-reachable      http://127.0.0.1:7842
✓ registry              6 scanners

All checks passed

AI tool detection

Code Pulse detects 6 tools via process, log, terminal, and extension signals:

  • Claude Code
  • OpenAI Codex
  • Cursor
  • Cline
  • Droid (Factory)
  • Kilo

Run time is how long the tool ran. Active work time is the activity Code Pulse can account for. All sources merge into one row per tool.

The dashboards

The VS Code dashboard includes the AI Tools card. The desktop app includes the Home You vs AI panel and Timeline rows like ran 3h · worked 37m.

Privacy & data

Code Pulse is 100% local: SQLite database under ~/.codepulse, loopback-only daemon, 0600 auth token, ed25519-signed scanner registry, and no cloud, account, or telemetry.

MCP server

Query your stats from any MCP-capable AI agent. The MCP server uses stdio JSON-RPC.

Publish GitHub Pages

The Pages workflow deploys the site/ directory. It runs on pushes to main, or you can trigger it manually: 

gh workflow run pages.yml --repo UmutKorkmaz/code-pulse --ref main
RUN_ID=$(gh run list --repo UmutKorkmaz/code-pulse --workflow pages.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch --repo UmutKorkmaz/code-pulse "$RUN_ID"
gh api repos/UmutKorkmaz/code-pulse/pages --jq '.html_url'

Troubleshooting

  • Daemon not reachable: start the daemon or run codepulse doctor.
  • Desktop 401 in dev: set VITE_DAEMON_TOKEN=$(cat ~/.codepulse/token).
  • Stale unsigned manifests: clear ~/.codepulse/cache/registry/ so the daemon reseeds signed ones.
  • Gray or empty Activity Bar tile: install v1.2.2 or newer, then run Developer: Reload Window. If VS Code still shows the stale cached icon, quit and reopen VS Code.