opencode-auto-review-completed-todos 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# opencode-auto-review-completed-todos
+
+Auto-detect when all session todos are completed and send a review message. Fires once per session.
+
+## What it does
+
+Listens for OpenCode's internal `todo.updated` events — whenever the todowrite tool creates, updates, or completes todos. When all todos have status `completed` or `cancelled`, it sends a review message to the chat. If new pending todos appear before the debounce fires, the review is cancelled.
+
+This works with **any** todo source: the AI creating/checking todos via the todowrite tool, the user checking boxes in the UI, or the internal todo-reminder plugin.
+
+**Design philosophy:** Pairs with `opencode-todo-reminder` as its complement. Todo-reminder nudges when tasks remain incomplete; this plugin triggers a review when all tasks are done.
+
+## Install
+
+```bash
+cp opencode-auto-review-completed-todos.ts ~/.config/opencode/plugins/
+# or the compiled version:
+cp opencode-auto-review-completed-todos.js ~/.config/opencode/plugins/
+```
+
+Register in `opencode.json`:
+
+```json
+"plugin": [
+  "opencode-auto-review-completed-todos"
+]
+```
+
+Restart OpenCode.
+
+## Configuration
+
+```json
+{
+  "plugin": [
+    ["opencode-auto-review-completed-todos", {
+      "debounceMs": 500
+    }]
+  ]
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debounceMs` | `number` | `500` | Wait after the last completed todo before sending message |
+
+## How it works
+
+### Architecture
+
+Per-session state is minimal:
+
+```
+SessionState
+├── reviewFired: boolean         ← prevent double-fire
+└── debounceTimer: Timer | null  ← debounce before sending
+```
+
+### Event handling
+
+| Event | Action |
+|-------|--------|
+| `todo.updated` | Check all todos. If all completed/cancelled → schedule message. If any pending → cancel scheduled message. |
+| `session.deleted` / `session.error` / `session.compacted` | Clean up session state |
+
+### Review trigger flow
+
+1. User/AI completes todos via OpenCode's todowrite tool
+2. `todo.updated` event fires with updated todo list
+3. Plugin checks `todos.every(t => t.status === "completed" || t.status === "cancelled")`
+4. If all done → 500ms debounce timer starts
+5. Timer fires → sends message to chat: "All tasks in this session have been completed. Please perform a final review..."
+6. AI responds with a session review summary
+
+### How the message appears
+
+Uses `client.session.prompt()` with `synthetic: false` — the same approach as `opencode-todo-reminder`. The message appears as a **normal chat message** that the AI responds to naturally.
+
+## Yin and yang
+
+| Plugin | When it triggers | What it does |
+|--------|-----------------|--------------|
+| `opencode-todo-reminder` | Todos remain incomplete | Nudges to complete tasks |
+| `opencode-auto-review-completed-todos` | All todos complete | Triggers review |
+
+## Status
+
+**BETA — confirmed working (5 May 2026).**
+
+Plugin:
+- Detects `todo.updated` events from OpenCode's internal todowrite tool
+- Sends visible chat message when all todos are completed
+- AI responds with a session review summary
+- Debounces to avoid premature triggering
+- Fires only once per session
+
+## Files
+
+| Path | Description |
+|------|-------------|
+| `~/.config/opencode/plugins/opencode-auto-review-completed-todos.js` | Main plugin (loaded by OpenCode) |
+| `~/.config/opencode/plugins/opencode-auto-review-completed-todos.ts` | TypeScript source |
+| `~/Dev/opencode-auto-review-completed-todos/` | Git-tracked source |
+
+## Troubleshooting
+
+**Plugin not loading:**
+- Verify `opencode.json` has `"opencode-auto-review-completed-todos"` in the `plugin` array
+- Ensure file is at `~/.config/opencode/plugins/opencode-auto-review-completed-todos.js`
+
+**Message not appearing:**
+- Todos must be created via OpenCode's todowrite tool (not raw text like `- [ ]`)
+- All todos must have status `"completed"` or `"cancelled"`
+- Plugin fires only once per session (new session needed after firing)
+
+## Requirements
+
+- OpenCode with plugin support
+- No additional npm dependencies

package/opencode-auto-review-completed-todos.js

@@ -0,0 +1,106 @@
+// @bun
+// opencode-auto-review-completed-todos.ts
+var DEFAULT_OPTIONS = {
+  debounceMs: 500
+};
+function mergeOptions(raw) {
+  if (!raw || typeof raw !== "object")
+    return { ...DEFAULT_OPTIONS };
+  return {
+    debounceMs: typeof raw.debounceMs === "number" && raw.debounceMs > 0 ? raw.debounceMs : DEFAULT_OPTIONS.debounceMs
+  };
+}
+export default async function AutoReviewCompletedTodosPlugin(input, rawOptions) {
+  const config = mergeOptions(rawOptions);
+  const sessions = /* @__PURE__ */ new Map();
+  function getSession(sessionId) {
+    return sessions.get(sessionId) || null;
+  }
+  function ensureSession(sessionId) {
+    let state = sessions.get(sessionId);
+    if (!state) {
+      state = { reviewFired: false, debounceTimer: null };
+      sessions.set(sessionId, state);
+    }
+    return state;
+  }
+  function cleanupSession(sessionId) {
+    const state = sessions.get(sessionId);
+    if (state?.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+    }
+    sessions.delete(sessionId);
+  }
+  function allTodosCompleted(todos) {
+    return Array.isArray(todos) && todos.length > 0 && todos.every((t) => t.status === "completed" || t.status === "cancelled");
+  }
+  async function triggerReview(sessionId) {
+    const state = sessions.get(sessionId);
+    if (!state || state.reviewFired)
+      return;
+    state.reviewFired = true;
+    if (state.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+      state.debounceTimer = null;
+    }
+    try {
+      await input.client.session.prompt({
+        path: { id: sessionId },
+        query: { directory: input.directory },
+        body: {
+          parts: [
+            {
+              type: "text",
+              text: "All tasks in this session have been completed. Please perform a final review: summarize what was accomplished, note any technical decisions or trade-offs made, flag anything that should be documented, and list any follow-up tasks or improvements for next time.",
+              synthetic: false
+            }
+          ]
+        }
+      });
+    } catch (e) {
+      process.stderr.write("[auto-review] REVIEW TRIGGERED (prompt failed)\n");
+    }
+  }
+  function scheduleReview(sessionId) {
+    const state = sessions.get(sessionId);
+    if (!state)
+      return;
+    if (state.debounceTimer)
+      clearTimeout(state.debounceTimer);
+    state.debounceTimer = setTimeout(() => {
+      state.debounceTimer = null;
+      triggerReview(sessionId);
+    }, config.debounceMs);
+  }
+  function cancelScheduledReview(sessionId) {
+    const state = sessions.get(sessionId);
+    if (state?.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+      state.debounceTimer = null;
+    }
+  }
+  return {
+    event: async ({ event }) => {
+      const e = event;
+      const sessionId = e?.properties?.sessionID ?? e?.properties?.info?.id ?? e?.properties?.path?.id;
+      if (!sessionId)
+        return;
+      if (e.type === "session.deleted" || e.type === "session.error" || e.type === "session.compacted") {
+        cleanupSession(sessionId);
+        return;
+      }
+      if (e.type === "todo.updated") {
+        const todos = e?.properties?.todos;
+        if (!Array.isArray(todos))
+          return;
+        const state = ensureSession(sessionId);
+        if (allTodosCompleted(todos)) {
+          scheduleReview(sessionId);
+        } else {
+          cancelScheduledReview(sessionId);
+        }
+        return;
+      }
+    }
+  };
+}

package/opencode-auto-review-completed-todos.ts

@@ -0,0 +1,151 @@
+// @bun
+// opencode-auto-review-completed-todos.ts
+import { type Plugin, type PluginOptions } from "@opencode-ai/plugin";
+import type { EventTodoUpdated, Todo } from "@opencode-ai/sdk";
+
+interface SessionState {
+  reviewFired: boolean;
+  debounceTimer: ReturnType<typeof setTimeout> | null;
+}
+
+interface Options {
+  debounceMs: number;
+}
+
+const DEFAULT_OPTIONS: Options = {
+  debounceMs: 500,
+};
+
+function mergeOptions(raw: unknown): Options {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_OPTIONS };
+  const o = raw as Record<string, unknown>;
+  return {
+    debounceMs:
+      typeof o.debounceMs === "number" && o.debounceMs > 0
+        ? o.debounceMs
+        : DEFAULT_OPTIONS.debounceMs,
+  };
+}
+
+function allTodosCompleted(todos: Todo[]): boolean {
+  return (
+    Array.isArray(todos) &&
+    todos.length > 0 &&
+    todos.every(
+      (t: Todo) => t.status === "completed" || t.status === "cancelled",
+    )
+  );
+}
+
+const AutoReviewCompletedTodosPlugin: Plugin = async (input, rawOptions) => {
+  const config = mergeOptions(rawOptions);
+  const sessions = new Map<string, SessionState>();
+
+  function getSession(sessionId: string): SessionState | null {
+    return sessions.get(sessionId) ?? null;
+  }
+
+  function ensureSession(sessionId: string): SessionState {
+    let state = sessions.get(sessionId);
+    if (!state) {
+      state = { reviewFired: false, debounceTimer: null };
+      sessions.set(sessionId, state);
+    }
+    return state;
+  }
+
+  function cleanupSession(sessionId: string): void {
+    const state = sessions.get(sessionId);
+    if (state?.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+    }
+    sessions.delete(sessionId);
+  }
+
+  async function triggerReview(sessionId: string): Promise<void> {
+    const state = sessions.get(sessionId);
+    if (!state || state.reviewFired) return;
+
+    state.reviewFired = true;
+    if (state.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+      state.debounceTimer = null;
+    }
+
+    try {
+      await input.client.session.prompt({
+        path: { id: sessionId },
+        query: { directory: input.directory },
+        body: {
+          parts: [
+            {
+              type: "text" as const,
+              text: "All tasks in this session have been completed. Please perform a final review: summarize what was accomplished, note any technical decisions or trade-offs made, flag anything that should be documented, and list any follow-up tasks or improvements for next time.",
+              synthetic: false,
+            },
+          ],
+        },
+      });
+    } catch {
+      process.stderr.write("[auto-review] REVIEW TRIGGERED (prompt failed)\n");
+    }
+  }
+
+  function scheduleReview(sessionId: string): void {
+    const state = sessions.get(sessionId);
+    if (!state) return;
+
+    if (state.debounceTimer) clearTimeout(state.debounceTimer);
+    state.debounceTimer = setTimeout(() => {
+      state.debounceTimer = null;
+      triggerReview(sessionId);
+    }, config.debounceMs);
+  }
+
+  function cancelScheduledReview(sessionId: string): void {
+    const state = sessions.get(sessionId);
+    if (state?.debounceTimer) {
+      clearTimeout(state.debounceTimer);
+      state.debounceTimer = null;
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      const e = event as Record<string, unknown>;
+      const props = e?.properties as Record<string, unknown> | undefined;
+      const sessionId: string | undefined =
+        (props?.sessionID as string) ??
+        ((props?.info as Record<string, unknown>)?.id as string) ??
+        ((props?.path as Record<string, unknown>)?.id as string);
+
+      if (!sessionId) return;
+
+      if (
+        e.type === "session.deleted" ||
+        e.type === "session.error" ||
+        e.type === "session.compacted"
+      ) {
+        cleanupSession(sessionId);
+        return;
+      }
+
+      if (e.type === "todo.updated") {
+        const todos = (e as unknown as EventTodoUpdated).properties.todos;
+        if (!Array.isArray(todos)) return;
+
+        const state = ensureSession(sessionId);
+
+        if (allTodosCompleted(todos)) {
+          scheduleReview(sessionId);
+        } else {
+          cancelScheduledReview(sessionId);
+        }
+        return;
+      }
+    },
+  };
+};
+
+export { AutoReviewCompletedTodosPlugin };
+export default AutoReviewCompletedTodosPlugin;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "opencode-auto-review-completed-todos",
+  "version": "1.0.0",
+  "description": "Auto-detect when all session todos are completed and trigger a review. Yin to opencode-todo-reminder's yang.",
+  "type": "module",
+  "main": "opencode-auto-review-completed-todos.js",
+  "types": "opencode-auto-review-completed-todos.ts",
+  "files": [
+    "opencode-auto-review-completed-todos.js",
+    "opencode-auto-review-completed-todos.ts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0",
+    "@opencode-ai/sdk": ">=1.0.0"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "todo",
+    "review",
+    "productivity"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DraconDev/opencode-auto-review-completed-todos"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}