bacluc-opencode-completion-check-command 0.0.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Bacluc
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,108 @@
+# opencode-completion-check-command
+
+An [opencode](https://opencode.ai) plugin that automatically verifies task completion by running a shell command after the agent finishes.
+
+## How It Works
+
+1. Use the `/completion-check-command` slash command in your opencode prompt followed by a markdown code block containing the shell command to run
+2. When the agent finishes (session goes idle), the plugin executes the stored command
+3. If the command exits with code 0, the task is considered complete
+4. If the command exits with a non-zero code, the agent is automatically prompted again with:
+
+   ```
+   you are not yet finished:
+
+   stdout:
+   <command stdout output>
+
+   stderr:
+   <command stderr output>
+   ```
+
+5. This retry loop continues up to a configurable maximum number of retries (default: 3). Once the limit is reached, the plugin stops re-prompting to prevent burning tokens indefinitely.
+
+## Usage
+
+In your opencode session, type:
+
+````
+/completion-check-command
+```bash
+./check-task.sh
+```
+````
+
+The plugin will extract the command from the code block and run it when the agent finishes.
+
+## Configuration
+
+### Plugin Options
+
+The plugin accepts an `maxRetries` option (default: `10`) that controls the maximum number of times the agent will be re-prompted when the check command fails:
+
+```json
+{
+  "plugin": [["bacluc-opencode-completion-check-command@<version>", { "maxRetries": 10 }]]
+}
+```
+
+Setting `maxRetries` to `0` disables re-prompting entirely — the command runs once and any failure is silently dropped.
+
+### Custom Command Template
+
+The `/completion-check-command` is automatically registered by the plugin's `config` hook. If you want to override the template, add it to your `opencode.json`:
+
+```json
+{
+  "command": {
+    "completion-check-command": {
+      "template": "Your custom template here: {{arguments}}",
+      "description": "Custom description"
+    }
+  }
+}
+```
+
+## Example
+
+Create a check script:
+
+```bash
+#!/bin/bash
+# check-task.sh - verify the task is complete
+if [ -f "output.txt" ]; then
+  echo "Task complete - output file exists"
+  exit 0
+else
+  echo "Task NOT complete - output file missing"
+  echo "Create the file: output.txt"
+  exit 1
+fi
+```
+
+Then use it in opencode:
+
+````
+Please create a file called output.txt with the contents "Hello World"
+
+/completion-check-command
+```bash
+./check-task.sh
+```
+````
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Format code
+npm run format
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "bacluc-opencode-completion-check-command",
+  "version": "0.0.1",
+  "description": "",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "completion-check-command"
+  ],
+  "homepage": "https://github.com/BacLuc/opencode-completion-check-command",
+  "bugs": {
+    "url": "https://github.com/BacLuc/opencode-completion-check-command/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BacLuc/opencode-completion-check-command.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Lucius Bachmann",
+  "type": "module",
+  "exports": {
+    "./server": "./src/server.ts"
+  },
+  "main": "src/server.ts",
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.15.12"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "prettier": "3.6.2",
+    "typescript": "5.9.3",
+    "vitest": "4.1.7"
+  }
+}

package/src/completion-check-command.ts

@@ -0,0 +1,199 @@
+import type { Hooks, Plugin, PluginInput } from '@opencode-ai/plugin'
+import type { Event } from '@opencode-ai/sdk'
+
+export const DEFAULT_MAX_RETRIES = 10
+
+export function parseCodeBlock(input: string): string | null {
+  const codeBlockRegex = /(?:```|~~~)([a-zA-Z0-9_-]*)\n([\s\S]*?)(?:```|~~~)/
+  const match = input.match(codeBlockRegex)
+  if (match && match[2]) {
+    return match[2].trim()
+  }
+  return null
+}
+
+interface SessionEntry {
+  command: string
+  retries: number
+}
+
+export class CompletionCheckStore {
+  private entries = new Map<string, SessionEntry>()
+  private maxRetries: number
+
+  constructor(maxRetries = DEFAULT_MAX_RETRIES) {
+    this.maxRetries = maxRetries
+  }
+
+  set(sessionID: string, command: string): void {
+    this.entries.set(sessionID, { command, retries: 0 })
+  }
+
+  get(sessionID: string): string | undefined {
+    return this.entries.get(sessionID)?.command
+  }
+
+  getEntry(sessionID: string): SessionEntry | undefined {
+    return this.entries.get(sessionID)
+  }
+
+  incrementRetries(sessionID: string): number {
+    const entry = this.entries.get(sessionID)
+    if (!entry) {
+      return -1
+    }
+    entry.retries++
+    return entry.retries
+  }
+
+  retriesExhausted(sessionID: string): boolean {
+    const entry = this.entries.get(sessionID)
+    if (!entry) {
+      return false
+    }
+    return entry.retries >= this.maxRetries
+  }
+
+  delete(sessionID: string): void {
+    this.entries.delete(sessionID)
+  }
+
+  has(sessionID: string): boolean {
+    return this.entries.has(sessionID)
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+
+  getMaxRetries(): number {
+    return this.maxRetries
+  }
+}
+
+export interface CommandResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+export async function executeCommand($: PluginInput['$'], command: string, cwd: string): Promise<CommandResult> {
+  try {
+    const result = await $`${command}`.nothrow().quiet().cwd(cwd)
+    return {
+      exitCode: result.exitCode,
+      stdout: result.text(),
+      stderr: result.stderr.toString(),
+    }
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export function buildFailureMessage(result: CommandResult): string {
+  let message = 'you are not yet finished:\n'
+  if (result.stdout) {
+    message += `\nstdout:\n${result.stdout}`
+  }
+  if (result.stderr) {
+    message += `\nstderr:\n${result.stderr}`
+  }
+  if (!result.stdout && !result.stderr) {
+    message += `\nCommand exited with code ${result.exitCode}`
+  }
+  return message
+}
+
+export const CompletionCheckCommandPlugin: Plugin = async (input, options) => {
+  const { client, $ } = input
+  const maxRetries = typeof options?.maxRetries === 'number' ? options.maxRetries : DEFAULT_MAX_RETRIES
+  const store = new CompletionCheckStore(maxRetries)
+
+  const processing = new Set<string>()
+
+  const hooks: Hooks = {
+    config: async (config) => {
+      if (!config.command) {
+        config.command = {}
+      }
+      if (!config.command['completion-check-command']) {
+        config.command['completion-check-command'] = {
+          template:
+            'The user wants to verify task completion after you finish. Run your task, and when you are done, a completion check will automatically run to verify your work.\n\nThe completion check command is:\n{{arguments}}',
+          description:
+            'Register a shell command that will be executed after the agent finishes to verify task completion. Include a markdown code block with the shell command to run.',
+        }
+      }
+    },
+
+    'command.execute.before': async (input, output) => {
+      if (input.command !== 'completion-check-command') {
+        return
+      }
+
+      const command = parseCodeBlock(input.arguments)
+      if (!command) {
+        return
+      }
+
+      store.set(input.sessionID, command)
+    },
+
+    event: async ({ event }) => {
+      if (event.type !== 'session.idle') {
+        return
+      }
+
+      const sessionID = (event as Extract<Event, { type: 'session.idle' }>).properties.sessionID
+      const command = store.get(sessionID)
+      if (!command) {
+        return
+      }
+
+      if (processing.has(sessionID)) {
+        return
+      }
+      processing.add(sessionID)
+
+      try {
+        const result = await executeCommand($, command, input.directory)
+
+        if (result.exitCode === 0) {
+          store.delete(sessionID)
+          return
+        }
+
+        if (store.retriesExhausted(sessionID)) {
+          store.delete(sessionID)
+          return
+        }
+
+        store.incrementRetries(sessionID)
+
+        const failureMessage = buildFailureMessage(result)
+
+        await client.session.promptAsync({
+          path: { id: sessionID },
+          body: {
+            parts: [
+              {
+                type: 'text',
+                text: failureMessage,
+              },
+            ],
+          },
+        })
+      } finally {
+        processing.delete(sessionID)
+      }
+    },
+  }
+
+  return hooks
+}
+
+export default CompletionCheckCommandPlugin

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  CompletionCheckCommandPlugin,
+  DEFAULT_MAX_RETRIES,
+  parseCodeBlock,
+  CompletionCheckStore,
+  executeCommand,
+  buildFailureMessage,
+} from './completion-check-command.js'
+export type { CommandResult } from './completion-check-command.js'

package/src/server.ts

@@ -0,0 +1,9 @@
+import type { PluginModule } from '@opencode-ai/plugin'
+import { CompletionCheckCommandPlugin } from './completion-check-command.js'
+
+const plugin: PluginModule = {
+  id: 'opencode-completion-check-command',
+  server: CompletionCheckCommandPlugin,
+}
+
+export default plugin