opencode-codetime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Pinchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# opencode-codetime
+
+[CodeTime](https://codetime.dev) plugin for [OpenCode](https://github.com/anomalyco/opencode) -- track your AI coding activity and time spent.
+
+## Features
+
+- **Automatic time tracking** -- sends coding events to CodeTime when OpenCode reads, edits, or writes files
+- **Language detection** -- detects 90+ programming languages from file extensions
+- **Git integration** -- captures current branch and remote origin
+- **Rate-limited** -- one heartbeat per 2 minutes to avoid API spam
+- **Session lifecycle** -- flushes pending events on session end so no data is lost
+- **Zero config** -- just set your token and go
+
+## Prerequisites
+
+A [CodeTime](https://codetime.dev) account. Sign up for free at [codetime.dev](https://codetime.dev).
+
+Get your upload token from [CodeTime Settings](https://codetime.dev/dashboard/settings).
+
+## Installation
+
+### Via opencode config (recommended)
+
+Add to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-codetime"]
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/roman-pinchuk/opencode-codetime
+cd opencode-codetime
+npm install && npm run build
+```
+
+Then copy the built files to your OpenCode plugins directory:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp dist/*.js ~/.config/opencode/plugins/
+```
+
+## Configuration
+
+Set your CodeTime upload token as an environment variable:
+
+```bash
+export CODETIME_TOKEN="your-upload-token-here"
+```
+
+Add it to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist across sessions.
+
+The plugin validates the token on startup and logs a warning if it is missing or invalid.
+
+## How It Works
+
+The plugin hooks into OpenCode's event system to detect file activity.
+
+```
+OpenCode events                    Plugin                         CodeTime API
++-----------------------+     +------------------+     +------------------------+
+| message.part.updated  | --> | Extract files    | --> | POST /v3/users/event-log|
+| (edit, write, read,   |     | Detect language  |     |                        |
+|  patch, multiedit)    |     | Rate limit (2m)  |     | { eventTime, language, |
++-----------------------+     +------------------+     |   project, relativeFile,|
+| session.idle          | --> | Force flush      |     |   editor: "opencode",  |
+| session.deleted       |     | pending events   |     |   platform, git info } |
++-----------------------+     +------------------+     +------------------------+
+```
+
+### What gets tracked
+
+Each heartbeat sent to CodeTime includes:
+
+| Field | Value |
+|-------|-------|
+| `eventTime` | Unix timestamp of the event |
+| `language` | Detected from file extension (e.g. `TypeScript`, `Python`) |
+| `project` | Current directory name |
+| `relativeFile` | File path relative to the project root |
+| `editor` | `opencode` |
+| `platform` | OS platform (`darwin`, `linux`, `windows`) |
+| `gitOrigin` | Remote origin URL (if available) |
+| `gitBranch` | Current branch name (if available) |
+
+### Hooks used
+
+| Hook | Purpose |
+|------|---------|
+| `event` | Listens for `message.part.updated` (tool completions) and `session.idle`/`session.deleted` (flush) |
+| `chat.message` | Processes pending heartbeats on chat activity |
+
+### Tool tracking
+
+| Tool | Data Extracted |
+|------|---------------|
+| `read` | File path from title |
+| `edit` | File path from filediff metadata |
+| `write` | File path from metadata |
+| `patch` | File paths from output |
+| `multiedit` | File paths from each edit result |
+
+## Project Structure
+
+```
+src/
+  index.ts        Main plugin entry point with event hooks
+  codetime.ts     CodeTime API client (token validation, heartbeats)
+  state.ts        Rate limiter (max 1 heartbeat per 2 minutes)
+  language.ts     File extension to language name mapping
+  git.ts          Git branch and remote origin extraction
+  logger.ts       Structured logging via OpenCode SDK
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## Troubleshooting
+
+### Plugin not loading
+
+1. Verify `opencode.json` syntax
+2. Check that `CODETIME_TOKEN` is set in your environment
+3. Check OpenCode logs for `opencode-codetime` messages
+
+### Heartbeats not appearing in CodeTime
+
+1. Verify your token at [codetime.dev/dashboard/settings](https://codetime.dev/dashboard/settings)
+2. Make sure you are editing files (not just chatting) -- heartbeats fire on tool completions
+3. Wait up to 2 minutes for rate-limited heartbeats to flush
+4. Check that the CodeTime API is reachable: `curl -s https://api.codetime.dev/v3`
+
+### Token validation fails
+
+1. Regenerate your token at [codetime.dev/dashboard/settings](https://codetime.dev/dashboard/settings)
+2. Make sure the token has no leading/trailing whitespace
+
+## License
+
+[MIT](LICENSE)

package/dist/codetime.d.ts

@@ -0,0 +1,30 @@
+export interface EventLogRequest {
+    eventTime: number;
+    language: string;
+    project: string;
+    relativeFile: string;
+    editor: string;
+    platform: string;
+    absoluteFile?: string | null;
+    gitOrigin?: string | null;
+    gitBranch?: string | null;
+}
+export interface UserSelf {
+    id: number;
+    username: string;
+    uploadToken: string;
+    plan: string;
+}
+/**
+ * Validate the CodeTime token by fetching the current user.
+ * Returns user info on success, or null on failure.
+ */
+export declare function validateToken(token: string): Promise<UserSelf | null>;
+/**
+ * Send a coding event (heartbeat) to the CodeTime API.
+ */
+export declare function sendHeartbeat(token: string, event: EventLogRequest): Promise<boolean>;
+/**
+ * Fetch today's coding minutes from CodeTime API.
+ */
+export declare function getTodayMinutes(token: string): Promise<number | null>;

package/dist/codetime.js

@@ -0,0 +1,85 @@
+import * as logger from "./logger.js";
+const API_BASE = "https://api.codetime.dev";
+/**
+ * Validate the CodeTime token by fetching the current user.
+ * Returns user info on success, or null on failure.
+ */
+export async function validateToken(token) {
+    try {
+        const response = await fetch(`${API_BASE}/v3/users/self`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            await logger.error("Token validation failed", {
+                status: response.status,
+                statusText: response.statusText,
+            });
+            return null;
+        }
+        const data = (await response.json());
+        return data;
+    }
+    catch (err) {
+        await logger.error("Token validation request failed", {
+            error: String(err),
+        });
+        return null;
+    }
+}
+/**
+ * Send a coding event (heartbeat) to the CodeTime API.
+ */
+export async function sendHeartbeat(token, event) {
+    try {
+        const response = await fetch(`${API_BASE}/v3/users/event-log`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(event),
+        });
+        if (!response.ok) {
+            await logger.warn("Failed to send heartbeat", {
+                status: response.status,
+                statusText: response.statusText,
+                event,
+            });
+            return false;
+        }
+        await logger.debug("Heartbeat sent", { event });
+        return true;
+    }
+    catch (err) {
+        await logger.error("Heartbeat request failed", {
+            error: String(err),
+            event,
+        });
+        return false;
+    }
+}
+/**
+ * Fetch today's coding minutes from CodeTime API.
+ */
+export async function getTodayMinutes(token) {
+    try {
+        const response = await fetch(`${API_BASE}/v3/users/self/minutes?minutes=1440`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return data.minutes;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,15 @@
+interface ShellFn {
+    (strings: TemplateStringsArray, ...values: unknown[]): Promise<{
+        stdout: Buffer;
+        exitCode: number;
+    }>;
+}
+/**
+ * Extract git remote origin URL from the worktree.
+ */
+export declare function getGitOrigin($: ShellFn, worktree: string): Promise<string | null>;
+/**
+ * Extract the current git branch from the worktree.
+ */
+export declare function getGitBranch($: ShellFn, worktree: string): Promise<string | null>;
+export {};

package/dist/git.js

@@ -0,0 +1,32 @@
+import * as debug from "./logger.js";
+/**
+ * Extract git remote origin URL from the worktree.
+ */
+export async function getGitOrigin($, worktree) {
+    try {
+        const result = await $ `git -C ${worktree} config --get remote.origin.url 2>/dev/null`;
+        if (result.exitCode === 0) {
+            return result.stdout.toString().trim() || null;
+        }
+    }
+    catch {
+        await debug.debug("Failed to get git origin", { worktree });
+    }
+    return null;
+}
+/**
+ * Extract the current git branch from the worktree.
+ */
+export async function getGitBranch($, worktree) {
+    try {
+        const result = await $ `git -C ${worktree} rev-parse --abbrev-ref HEAD 2>/dev/null`;
+        if (result.exitCode === 0) {
+            const branch = result.stdout.toString().trim();
+            return branch && branch !== "HEAD" ? branch : null;
+        }
+    }
+    catch {
+        await debug.debug("Failed to get git branch", { worktree });
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const plugin: Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,243 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { sendHeartbeat, validateToken, } from "./codetime.js";
+import { getGitBranch, getGitOrigin } from "./git.js";
+import { detectLanguage } from "./language.js";
+import { initLogger, info, warn, error, debug } from "./logger.js";
+import { initState, shouldSendHeartbeat, updateLastHeartbeat, } from "./state.js";
+// ---- State ----
+const processedCallIds = new Set();
+const pendingFiles = new Map();
+let _token = null;
+let _projectName = "unknown";
+let _projectDir = "";
+let _worktree = "";
+let _gitOrigin = null;
+let _gitBranch = null;
+let _platform = os.platform();
+// ---- File extraction from tool events ----
+function extractFilesFromTool(tool, metadata, output, title) {
+    const files = [];
+    if (!metadata && tool !== "read")
+        return files;
+    switch (tool) {
+        case "edit": {
+            const filediff = metadata?.filediff;
+            if (filediff?.file) {
+                files.push(filediff.file);
+            }
+            else {
+                const filePath = metadata?.filePath;
+                if (filePath)
+                    files.push(filePath);
+            }
+            break;
+        }
+        case "write": {
+            const filepath = metadata?.filepath;
+            if (filepath)
+                files.push(filepath);
+            break;
+        }
+        case "read": {
+            if (title)
+                files.push(title);
+            break;
+        }
+        case "patch": {
+            const lines = output.split("\n");
+            for (const line of lines) {
+                if (line.startsWith("  ") && !line.startsWith("   ")) {
+                    const file = line.trim();
+                    if (file && !file.includes(" "))
+                        files.push(file);
+                }
+            }
+            break;
+        }
+        case "multiedit": {
+            const results = metadata?.results;
+            if (results) {
+                for (const result of results) {
+                    if (result.filediff?.file) {
+                        files.push(result.filediff.file);
+                    }
+                }
+            }
+            break;
+        }
+        case "glob":
+        case "grep":
+        case "bash":
+            // These don't produce meaningful file paths for tracking
+            break;
+    }
+    return files;
+}
+function computeRelativeFile(absoluteFile, projectDir) {
+    if (absoluteFile.startsWith(projectDir)) {
+        return absoluteFile.slice(projectDir.length).replace(/^\//, "");
+    }
+    return path.basename(absoluteFile);
+}
+// ---- Heartbeat processing ----
+async function processHeartbeats(force = false) {
+    if (!_token)
+        return;
+    if (!shouldSendHeartbeat(force) && !force)
+        return;
+    if (pendingFiles.size === 0)
+        return;
+    const promises = [];
+    for (const [filePath, fileInfo] of pendingFiles.entries()) {
+        const relativeFile = computeRelativeFile(filePath, _projectDir);
+        const event = {
+            eventTime: Math.floor(Date.now() / 1000),
+            language: fileInfo.language,
+            project: _projectName,
+            relativeFile,
+            editor: "opencode",
+            platform: _platform,
+            absoluteFile: fileInfo.absoluteFile ?? filePath,
+            gitOrigin: _gitOrigin,
+            gitBranch: _gitBranch,
+        };
+        const p = sendHeartbeat(_token, event);
+        if (force) {
+            promises.push(p);
+        }
+    }
+    pendingFiles.clear();
+    updateLastHeartbeat();
+    if (force && promises.length > 0) {
+        await Promise.all(promises);
+    }
+}
+function trackFile(filePath) {
+    const language = detectLanguage(filePath);
+    pendingFiles.set(filePath, {
+        language,
+        absoluteFile: filePath,
+    });
+}
+// ---- Event guard ----
+function isMessagePartUpdatedEvent(event) {
+    return event.type === "message.part.updated";
+}
+// ---- Deduplication cleanup ----
+function pruneProcessedIds() {
+    if (processedCallIds.size > 1000) {
+        const entries = Array.from(processedCallIds);
+        const toRemove = entries.slice(0, entries.length - 500);
+        for (const id of toRemove) {
+            processedCallIds.delete(id);
+        }
+    }
+}
+// ---- Plugin entry point ----
+export const plugin = async (ctx) => {
+    try {
+        const { client, directory, worktree, $ } = ctx;
+        // Initialize logger (may fail if client shape differs)
+        try {
+            initLogger(client);
+        }
+        catch {
+            // Logger init failed, continue without structured logging
+        }
+        // Read token from environment
+        _token = process.env.CODETIME_TOKEN ?? null;
+        if (!_token) {
+            await warn("CODETIME_TOKEN not set. CodeTime tracking disabled. " +
+                "Get your token from https://codetime.dev/dashboard/settings").catch(() => { });
+            return {};
+        }
+        // Validate token
+        const user = await validateToken(_token);
+        if (!user) {
+            await error("Invalid CODETIME_TOKEN. Please check your token at https://codetime.dev/dashboard/settings").catch(() => { });
+            _token = null;
+            return {};
+        }
+        await info(`CodeTime plugin initialized for user: ${user.username}`, {
+            plan: user.plan,
+        }).catch(() => { });
+        // Initialize state
+        initState();
+        _projectDir = directory;
+        _worktree = worktree;
+        _projectName = path.basename(directory);
+        _platform = os.platform();
+        // Fetch git info
+        if (worktree) {
+            const shellFn = $;
+            _gitOrigin = await getGitOrigin(shellFn, worktree);
+            _gitBranch = await getGitBranch(shellFn, worktree);
+            await debug("Git info", { origin: _gitOrigin, branch: _gitBranch }).catch(() => { });
+        }
+        return {
+            event: async ({ event }) => {
+                try {
+                    if (!_token)
+                        return;
+                    // Handle tool completions
+                    if (isMessagePartUpdatedEvent(event)) {
+                        const { part } = event.properties;
+                        if (!("tool" in part) || part.type !== "tool")
+                            return;
+                        const toolPart = part;
+                        if (toolPart.state.status !== "completed")
+                            return;
+                        // Deduplicate
+                        if (processedCallIds.has(toolPart.callID))
+                            return;
+                        processedCallIds.add(toolPart.callID);
+                        pruneProcessedIds();
+                        const { tool, state } = toolPart;
+                        const metadata = state.metadata;
+                        const output = state.output ?? "";
+                        const title = state.title;
+                        const files = extractFilesFromTool(tool, metadata, output, title);
+                        if (files.length > 0) {
+                            for (const file of files) {
+                                trackFile(file);
+                            }
+                            // Try to process heartbeats (rate limiter will throttle if needed)
+                            await processHeartbeats();
+                        }
+                    }
+                    // Handle session lifecycle - force flush
+                    if (event.type === "session.idle" ||
+                        event.type === "session.deleted") {
+                        await debug("Session ending, flushing heartbeats", {
+                            type: event.type,
+                            pendingFiles: pendingFiles.size,
+                        }).catch(() => { });
+                        await processHeartbeats(true);
+                    }
+                }
+                catch (err) {
+                    await error("Event handler error", { error: String(err) }).catch(() => { });
+                }
+            },
+            "chat.message": async () => {
+                try {
+                    // On any chat activity, try to process pending heartbeats
+                    if (_token && pendingFiles.size > 0) {
+                        await processHeartbeats();
+                    }
+                }
+                catch (err) {
+                    await error("Chat message handler error", { error: String(err) }).catch(() => { });
+                }
+            },
+        };
+    }
+    catch (err) {
+        // If anything goes wrong during plugin initialization,
+        // return empty hooks so OpenCode can continue without this plugin
+        console.error("[opencode-codetime] Plugin failed to initialize:", err);
+        return {};
+    }
+};
+export default plugin;

package/dist/language.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detect the programming language from a file path using its extension.
+ * Returns "Unknown" if the extension is not recognized.
+ */
+export declare function detectLanguage(filePath: string): string;

package/dist/language.js

@@ -0,0 +1,121 @@
+import * as path from "node:path";
+const EXTENSION_MAP = {
+    // JavaScript / TypeScript
+    ".js": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".jsx": "JavaScript JSX",
+    ".ts": "TypeScript",
+    ".mts": "TypeScript",
+    ".cts": "TypeScript",
+    ".tsx": "TypeScript JSX",
+    // Web
+    ".html": "HTML",
+    ".htm": "HTML",
+    ".css": "CSS",
+    ".scss": "SCSS",
+    ".sass": "Sass",
+    ".less": "Less",
+    ".vue": "Vue",
+    ".svelte": "Svelte",
+    ".astro": "Astro",
+    // Python
+    ".py": "Python",
+    ".pyw": "Python",
+    ".pyi": "Python",
+    // Go
+    ".go": "Go",
+    // Rust
+    ".rs": "Rust",
+    // Java / Kotlin
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".kts": "Kotlin",
+    // C / C++
+    ".c": "C",
+    ".h": "C",
+    ".cpp": "C++",
+    ".cc": "C++",
+    ".cxx": "C++",
+    ".hpp": "C++",
+    // C#
+    ".cs": "C#",
+    // Swift
+    ".swift": "Swift",
+    // Ruby
+    ".rb": "Ruby",
+    // PHP
+    ".php": "PHP",
+    // Lua
+    ".lua": "Lua",
+    // Shell
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    ".fish": "Shell",
+    // Config / Data
+    ".json": "JSON",
+    ".jsonc": "JSONC",
+    ".yaml": "YAML",
+    ".yml": "YAML",
+    ".toml": "TOML",
+    ".xml": "XML",
+    ".csv": "CSV",
+    // Markup / Docs
+    ".md": "Markdown",
+    ".mdx": "MDX",
+    ".rst": "reStructuredText",
+    ".tex": "LaTeX",
+    // Docker / DevOps
+    ".dockerfile": "Dockerfile",
+    ".tf": "Terraform",
+    ".hcl": "HCL",
+    // SQL
+    ".sql": "SQL",
+    // R
+    ".r": "R",
+    ".R": "R",
+    // Elixir / Erlang
+    ".ex": "Elixir",
+    ".exs": "Elixir",
+    ".erl": "Erlang",
+    // Dart
+    ".dart": "Dart",
+    // Zig
+    ".zig": "Zig",
+    // Nim
+    ".nim": "Nim",
+    // Scala
+    ".scala": "Scala",
+    // Haskell
+    ".hs": "Haskell",
+    // OCaml
+    ".ml": "OCaml",
+    ".mli": "OCaml",
+    // Clojure
+    ".clj": "Clojure",
+    ".cljs": "ClojureScript",
+    // GraphQL
+    ".graphql": "GraphQL",
+    ".gql": "GraphQL",
+    // Proto
+    ".proto": "Protocol Buffers",
+};
+/**
+ * Detect the programming language from a file path using its extension.
+ * Returns "Unknown" if the extension is not recognized.
+ */
+export function detectLanguage(filePath) {
+    if (!filePath)
+        return "Unknown";
+    // Handle special filenames
+    const basename = path.basename(filePath).toLowerCase();
+    if (basename === "dockerfile")
+        return "Dockerfile";
+    if (basename === "makefile" || basename === "gnumakefile")
+        return "Makefile";
+    if (basename === "cmakelists.txt")
+        return "CMake";
+    const ext = path.extname(filePath).toLowerCase();
+    return EXTENSION_MAP[ext] ?? "Unknown";
+}

package/dist/logger.d.ts

@@ -0,0 +1,20 @@
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogClient {
+    app: {
+        log: (opts: {
+            body: {
+                service: string;
+                level: LogLevel;
+                message: string;
+                extra?: Record<string, unknown>;
+            };
+        }) => Promise<unknown>;
+    };
+}
+export declare function initLogger(client: LogClient): void;
+export declare function log(level: LogLevel, message: string, extra?: Record<string, unknown>): Promise<void>;
+export declare function debug(message: string, extra?: Record<string, unknown>): Promise<void>;
+export declare function info(message: string, extra?: Record<string, unknown>): Promise<void>;
+export declare function warn(message: string, extra?: Record<string, unknown>): Promise<void>;
+export declare function error(message: string, extra?: Record<string, unknown>): Promise<void>;
+export {};

package/dist/logger.js

@@ -0,0 +1,29 @@
+let _client = null;
+const SERVICE = "opencode-codetime";
+export function initLogger(client) {
+    _client = client;
+}
+export async function log(level, message, extra) {
+    if (!_client)
+        return;
+    try {
+        await _client.app.log({
+            body: { service: SERVICE, level, message, extra },
+        });
+    }
+    catch {
+        // Silently ignore logging failures
+    }
+}
+export async function debug(message, extra) {
+    return log("debug", message, extra);
+}
+export async function info(message, extra) {
+    return log("info", message, extra);
+}
+export async function warn(message, extra) {
+    return log("warn", message, extra);
+}
+export async function error(message, extra) {
+    return log("error", message, extra);
+}

package/dist/state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Rate limiter for CodeTime heartbeats.
+ * Prevents sending more than one heartbeat per HEARTBEAT_INTERVAL_MS per project.
+ */
+/**
+ * Initialize state (called on plugin startup).
+ */
+export declare function initState(): void;
+/**
+ * Check if enough time has passed to send a new heartbeat.
+ * @param force If true, always returns true.
+ */
+export declare function shouldSendHeartbeat(force?: boolean): boolean;
+/**
+ * Record that a heartbeat was just sent.
+ */
+export declare function updateLastHeartbeat(): void;

package/dist/state.js

@@ -0,0 +1,28 @@
+/**
+ * Rate limiter for CodeTime heartbeats.
+ * Prevents sending more than one heartbeat per HEARTBEAT_INTERVAL_MS per project.
+ */
+const HEARTBEAT_INTERVAL_MS = 2 * 60 * 1000; // 2 minutes
+let lastHeartbeatTime = 0;
+/**
+ * Initialize state (called on plugin startup).
+ */
+export function initState() {
+    lastHeartbeatTime = 0;
+}
+/**
+ * Check if enough time has passed to send a new heartbeat.
+ * @param force If true, always returns true.
+ */
+export function shouldSendHeartbeat(force = false) {
+    if (force)
+        return true;
+    const now = Date.now();
+    return now - lastHeartbeatTime >= HEARTBEAT_INTERVAL_MS;
+}
+/**
+ * Record that a heartbeat was just sent.
+ */
+export function updateLastHeartbeat() {
+    lastHeartbeatTime = Date.now();
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "opencode-codetime",
+  "version": "0.1.0",
+  "description": "CodeTime plugin for OpenCode - Track AI coding activity and time spent with codetime.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "codetime",
+    "coding-time",
+    "time-tracking",
+    "opencode-plugin"
+  ],
+  "author": "Roman Pinchuk",
+  "license": "MIT",
+  "homepage": "https://github.com/roman-pinchuk/opencode-codetime#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roman-pinchuk/opencode-codetime.git"
+  },
+  "bugs": {
+    "url": "https://github.com/roman-pinchuk/opencode-codetime/issues"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.0.0",
+    "@types/node": "^25.3.3",
+    "typescript": "^5.0.0"
+  }
+}