feat: add per-project time filtering and project breakdown to codetime tool

Author: roman-pinchuk

README.md

@@ -14,9 +14,11 @@
 
 - **Automatic time tracking** -- sends coding events to CodeTime when OpenCode reads, edits, or writes files
 - **Check your coding time** -- ask the AI "what's my coding time?" and it fetches your stats via the `codetime` tool
+- **Per-project filtering** -- view coding time for the current project or any specific project
+- **Project breakdown** -- see a ranked table of all projects with time spent today
 - **Language detection** -- detects 90+ programming languages from file extensions
 - **Git integration** -- captures current branch and remote origin
-- **Project identification** -- shows as `[opencode] project-name` on your CodeTime dashboard
+- **Project identification** -- shows as `directory-name [opencode]` on your CodeTime dashboard
 - **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
@@ -91,7 +93,7 @@ Each heartbeat sent to CodeTime includes:
 |-------|-------|
 | `eventTime` | Unix timestamp of the event |
 | `language` | Detected from file extension (e.g. `TypeScript`, `Python`) |
-| `project` | `[opencode] directory-name` |
+| `project` | `directory-name [opencode]` |
 | `relativeFile` | File path relative to the project root |
 | `editor` | `opencode` |
 | `platform` | OS platform (`darwin`, `linux`, `windows`) |
@@ -106,6 +108,48 @@ Each heartbeat sent to CodeTime includes:
 | `chat.message` | Processes pending heartbeats on chat activity |
 | `tool` | Registers `codetime` tool to check today's coding time |
 
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/codetime` | Show today's total coding time |
+| `/codetime-breakdown` | Show today's coding time broken down by project |
+
+### `codetime` tool
+
+The `codetime` tool supports optional arguments for project filtering:
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `project` | string (optional) | Filter by project name. Use `"current"` to auto-detect the current project. Omit to show total time. |
+| `breakdown` | boolean (optional) | When `true`, show a ranked breakdown of all projects. |
+
+**Usage examples** (in natural language to the AI):
+
+- "What's my coding time?" -- shows total time across all projects
+- "How long have I been coding on this project?" -- shows time for the current project
+- "Show me a breakdown of my coding time by project" -- shows ranked project list
+- "How much time did I spend on my-app today?" -- shows time for a specific project
+
+**Example outputs:**
+
+```
+# Total time (default)
+Today's coding time: 2h 42m
+
+# Current project
+Today's coding time for opencode-codetime [opencode]: 1h 23m (Total across all projects: 2h 42m)
+
+# Project breakdown
+Today's coding time by project:
+
+  opencode-codetime [opencode]    1h 23m
+  my-other-project [vscode]         52m
+  side-project [opencode]           27m
+  ──────────────────────────────────────
+  Total                           2h 42m
+```
+
 ### Tool tracking
 
 | Tool | Data Extracted |
@@ -121,7 +165,7 @@ Each heartbeat sent to CodeTime includes:
 ```
 src/
   index.ts        Main plugin entry point with event hooks
-  codetime.ts     CodeTime API client (token validation, heartbeats)
+  codetime.ts     CodeTime API client (token validation, heartbeats, stats)
   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

src/codetime.ts

@@ -118,3 +118,114 @@ export async function getTodayMinutes(
     return null;
   }
 }
+
+// ---- Response types for stats/top endpoints ----
+
+export interface StatsTimeData {
+  duration: number;
+  time: string;
+}
+
+export interface StatsTimeResponse {
+  data: StatsTimeData[];
+}
+
+export interface TopEntry {
+  field: string;
+  minutes: number;
+}
+
+/**
+ * Fetch coding minutes for a specific project using the stats_time endpoint.
+ * Returns total minutes for the project within the last 24 hours,
+ * or a custom time range if start/end are provided.
+ */
+export async function getProjectMinutes(
+  token: string,
+  project: string,
+): Promise<number | null> {
+  try {
+    const params = new URLSearchParams({
+      project,
+      unit: "minutes",
+      limit: "1440",
+    });
+
+    const response = await fetch(
+      `${API_BASE}/v3/users/self/stats_time?${params.toString()}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+      },
+    );
+
+    if (!response.ok) {
+      await logger.warn("Failed to fetch project minutes", {
+        status: response.status,
+        statusText: response.statusText,
+        project,
+      });
+      return null;
+    }
+
+    const data = (await response.json()) as StatsTimeResponse;
+    // Sum all duration values from the response
+    const totalMinutes = data.data.reduce(
+      (sum, entry) => sum + entry.duration,
+      0,
+    );
+    return totalMinutes;
+  } catch (err) {
+    await logger.error("Project minutes request failed", {
+      error: String(err),
+      project,
+    });
+    return null;
+  }
+}
+
+/**
+ * Fetch top projects by coding time using the top endpoint.
+ * Returns a ranked list of projects with their minutes.
+ */
+export async function getTopProjects(
+  token: string,
+  minutes: number = 1440,
+): Promise<TopEntry[] | null> {
+  try {
+    const params = new URLSearchParams({
+      field: "workspace",
+      minutes: String(minutes),
+    });
+
+    const response = await fetch(
+      `${API_BASE}/v3/users/self/top?${params.toString()}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+      },
+    );
+
+    if (!response.ok) {
+      await logger.warn("Failed to fetch top projects", {
+        status: response.status,
+        statusText: response.statusText,
+      });
+      return null;
+    }
+
+    const data = (await response.json()) as TopEntry[];
+    return data;
+  } catch (err) {
+    await logger.error("Top projects request failed", {
+      error: String(err),
+    });
+    return null;
+  }
+}

src/index.ts

@@ -6,6 +6,8 @@ import {
   sendHeartbeat,
   validateToken,
   getTodayMinutes,
+  getProjectMinutes,
+  getTopProjects,
   type EventLogRequest,
 } from "./codetime.js";
 import { getGitBranch, getGitOrigin } from "./git.js";
@@ -344,21 +346,97 @@ export const plugin: Plugin = async (ctx) => {
             "Immediately call `codetime` with no arguments and return its output verbatim.\n" +
             "Do not call other tools.",
         };
+        cfg.command["codetime-breakdown"] = {
+          description: "Show today's coding time breakdown by project",
+          template:
+            "Retrieve CodeTime coding time stats broken down by project.\n\n" +
+            'Immediately call `codetime` with `breakdown: true` and return its output verbatim.\n' +
+            "Do not call other tools.",
+        };
       },
 
       tool: {
         codetime: tool({
           description:
             "Show today's coding time tracked by CodeTime. " +
             "Use this when the user asks about their coding time, " +
-            "how long they've been coding, or wants to see their CodeTime stats.",
-          args: {},
-          async execute() {
+            "how long they've been coding, or wants to see their CodeTime stats. " +
+            "Supports filtering by project name and showing a breakdown of time across all projects.",
+          args: {
+            project: tool.schema.string().optional().describe(
+              "Filter by project name. Use 'current' to auto-detect the current project. " +
+              "Omit to show total time across all projects.",
+            ),
+            breakdown: tool.schema.boolean().optional().describe(
+              "When true, show a breakdown of coding time across all projects today.",
+            ),
+          },
+          async execute(args) {
             if (!_token) {
               return "CodeTime is not configured. Set CODETIME_TOKEN environment variable to enable tracking. Get your token from https://codetime.dev/dashboard/settings";
             }
 
             try {
+              // Breakdown mode: show all projects ranked by time
+              if (args.breakdown) {
+                const projects = await getTopProjects(_token);
+                if (projects === null || projects.length === 0) {
+                  return "No project data available for today.";
+                }
+
+                // Calculate total
+                const totalMinutes = projects.reduce(
+                  (sum, p) => sum + p.minutes,
+                  0,
+                );
+
+                // Find the longest project name for alignment
+                const maxNameLen = Math.max(
+                  ...projects.map((p) => p.field.length),
+                  "Total".length,
+                );
+
+                const lines = ["Today's coding time by project:", ""];
+                for (const p of projects) {
+                  const name = p.field.padEnd(maxNameLen + 2);
+                  lines.push(`  ${name}${formatMinutes(p.minutes)}`);
+                }
+                lines.push(`  ${"─".repeat(maxNameLen + 2 + 8)}`);
+                lines.push(
+                  `  ${"Total".padEnd(maxNameLen + 2)}${formatMinutes(totalMinutes)}`,
+                );
+
+                return lines.join("\n");
+              }
+
+              // Project-specific mode
+              const projectName =
+                args.project === "current" ? _projectName : args.project;
+
+              if (projectName) {
+                // Fetch both project-specific and total in parallel
+                const [projectMins, totalMins] = await Promise.all([
+                  getProjectMinutes(_token, projectName),
+                  getTodayMinutes(_token),
+                ]);
+
+                if (projectMins === null) {
+                  return `Failed to fetch coding time for project "${projectName}" from CodeTime API.`;
+                }
+
+                const projectFormatted = formatMinutes(projectMins);
+                const displayName = args.project === "current"
+                  ? _projectName
+                  : projectName;
+
+                if (totalMins !== null) {
+                  const totalFormatted = formatMinutes(totalMins);
+                  return `Today's coding time for ${displayName}: ${projectFormatted} (Total across all projects: ${totalFormatted})`;
+                }
+                return `Today's coding time for ${displayName}: ${projectFormatted}`;
+              }
+
+              // Default: total coding time (original behavior)
               const minutes = await getTodayMinutes(_token);
               if (minutes === null) {
                 return "Failed to fetch coding time from CodeTime API.";