@devclocked/tracker-core

Shared SDK for DevClocked tracker applications (VS Code, Chrome, Desktop).

Features

• Unified API: Same interface across all tracker applications
• Offline Support: Local queue with exponential retry
• Auto Authentication: JWT token management with refresh
• Cross-Platform: Works in browser, Node.js, and VS Code
• Privacy First: User-controlled exclusion patterns
• Real-time Sync: Automatic session and tick synchronization

Installation

npm install @devclocked/tracker-core

Quick Start

import { TrackerClient, StorageAdapter } from '@devclocked/tracker-core';

// Create a storage adapter for your environment
const storage = new YourStorageAdapter();

// Initialize the tracker client
const tracker = new TrackerClient({
  supabaseUrl: 'https://your-project.supabase.co',
  supabaseAnonKey: 'your-anon-key',
  source: 'vscode', // or 'chrome', 'desktop'
  clientId: 'unique-client-id',
  deviceName: 'My Development Machine',
  debug: true
}, storage);

// Authenticate with Supabase access token
await tracker.authenticate('your-access-token');

// Start tracking a session
const session = await tracker.startSession('https://github.com/user/repo', 'main');

// Send activity ticks
await tracker.sendTick('/src/components/App.tsx', 'file', {
  repo_url: 'https://github.com/user/repo',
  branch: 'main',
  language: 'typescript',
  is_write: true
});

// End the session
await tracker.endSession(session.id);

API Reference

agentRun (module)

Pure, dependency-free engine that parses local AI agent session stores (Claude Code, Codex CLI, Grok Build, Antigravity) into a common AgentThread → AgentRun[] → AgentRunEvent[] timeline shape. Every interval is classified explicit or inferred with a confidence value, and a structural sanitizer keeps prompt/reply/tool-output bodies out of the output by type construction.

• parseAgentThread({ runtime, lines, ... }) - Parse one session into a thread
• summarizeThread(thread) - Per-run state-split, token and cost summary
• Adapters, capability matrix and invariant checkers are exported from src/agentRun/index.ts
• tools/validateLocal.mjs - Read-only operator CLI for validating a local store (not shipped in the npm package)

Node agent-run capture

Node clients can import local source discovery, read-only parsing, wire batch construction, hashing, and upload helpers from the Node-only subpath:

import {
  AgentRunHasher,
  AgentRunUploader,
  buildWireBatches,
  discoverSources,
  parseSource,
  sourcePathAllowed,
} from '@devclocked/tracker-core/agent-run/node';

The package root stays browser-safe and does not load the file system or path modules. Call sourcePathAllowed before parsing a user-selected file. The discovery and parsing helpers open transcript files read-only, and parsed wire output excludes prompt, response, tool-output, and absolute-path content.

TrackerClient

Main class for all tracker operations.

Methods

• authenticate(token: string) - Authenticate with Supabase
• startSession(repo?, branch?, projectName?) - Start a new session
• endSession(sessionId?) - End current or specified session
• getActiveSession() - Get current active session
• sendTick(entity, type, metadata?) - Send activity tick
• flushQueue() - Manually flush the tick queue
• linkCommit(sessionId, sha, repo, committedAt) - Link commit to session
• sendTelemetry(events) - Send telemetry events
• getTrackerState() - Get current tracker state
• getQueueStats() - Get queue statistics
• clearQueue() - Clear the tick queue
• destroy() - Cleanup resources

StorageAdapter

Abstract class for cross-platform storage. Implement this for your environment.

Methods

• get(key: string) - Get value by key
• set(key: string, value: string) - Set value by key
• remove(key: string) - Remove value by key
• clear() - Clear all values
• keys() - Get all keys
• getObject<T>(key: string) - Get JSON object
• setObject<T>(key: string, value: T) - Set JSON object

AuthManager

Handles authentication and token management.

Methods

• authenticate(token: string) - Authenticate with token
• isAuthenticated() - Check authentication status
• getAccessToken() - Get current access token
• refreshToken() - Refresh access token
• logout() - Logout and clear state

TickQueue

Manages local queue with retry logic.

Methods

• enqueueTicks(ticks: TickData[]) - Add ticks to queue
• enqueueTelemetry(events: TelemetryEvent[]) - Add telemetry to queue
• processQueue(processor) - Process queue items
• getQueueStats() - Get queue statistics
• clearQueue() - Clear all items

Storage Adapter Implementations

Browser (IndexedDB)

import { StorageAdapter } from '@devclocked/tracker-core';

class BrowserStorageAdapter extends StorageAdapter {
  private db: IDBDatabase;

  async get(key: string): Promise<string | null> {
    // Implement IndexedDB get
  }

  async set(key: string, value: string): Promise<void> {
    // Implement IndexedDB set
  }

  // ... implement other methods
}

Node.js (File System)

import { StorageAdapter } from '@devclocked/tracker-core';
import fs from 'fs/promises';
import path from 'path';

class NodeStorageAdapter extends StorageAdapter {
  private storageDir: string;

  async get(key: string): Promise<string | null> {
    try {
      const filePath = path.join(this.storageDir, key);
      return await fs.readFile(filePath, 'utf-8');
    } catch {
      return null;
    }
  }

  async set(key: string, value: string): Promise<void> {
    const filePath = path.join(this.storageDir, key);
    await fs.writeFile(filePath, value, 'utf-8');
  }

  // ... implement other methods
}

VS Code (GlobalState)

import { StorageAdapter } from '@devclocked/tracker-core';
import * as vscode from 'vscode';

class VSCodeStorageAdapter extends StorageAdapter {
  constructor(private context: vscode.ExtensionContext) {
    super();
  }

  async get(key: string): Promise<string | null> {
    return this.context.globalState.get(key) || null;
  }

  async set(key: string, value: string): Promise<void> {
    await this.context.globalState.update(key, value);
  }

  // ... implement other methods
}

Configuration

TrackerConfig

interface TrackerConfig {
  supabaseUrl: string;        // Your Supabase project URL
  supabaseAnonKey: string;    // Your Supabase anon key
  source: TrackerSource;     // 'vscode' | 'chrome' | 'desktop'
  clientId: string;           // Unique client identifier
  deviceName?: string;        // Optional device name
  debug?: boolean;           // Enable debug logging
}

Error Handling

The SDK includes comprehensive error handling:

• Authentication errors: Invalid tokens, expired sessions
• Network errors: Connection failures, timeouts
• Rate limiting: Automatic retry with exponential backoff
• Queue management: Persistent storage of failed requests

Privacy & Security

• Local storage: All data stored locally until successfully synced
• Encryption: Sensitive data encrypted at rest
• User control: Exclusion patterns for private work
• No content logging: Only metadata (paths, URLs, timestamps)

License

MIT