opencode-todo-enforcer

Standalone OpenCode plugin that enforces todo continuation when a session goes idle.

It is inspired by oh-my-opencode's todo continuation enforcer, but packaged independently so you can use it in any OpenCode setup.

What it does

• Listens for session.idle
• Checks for incomplete todos
• Applies safety guards (abort window, cooldown/backoff, skipped agents, stop state)
• Starts a countdown before injecting a continuation prompt
• Cancels continuation when user/tool/assistant activity resumes
• Supports per-session pause via /stop-continuation
• Includes debug tool todo_enforcer_debug_ping for runtime verification

Install

Add to OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-todo-enforcer"]
}

For local development without publishing, load from your working directory:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-todo-enforcer@file:/absolute/path/to/opencode-todo-enforcer"]
}

Optional configuration

You can export a configured plugin factory:

import { createTodoEnforcerPlugin } from "opencode-todo-enforcer";

export default createTodoEnforcerPlugin({
  countdownMs: 1500,
  continuationCooldownMs: 7000,
  skipAgents: ["compaction", "prometheus"],
  stopCommand: "/stop-continuation",
});

Defaults

• countdownMs: 2000
• continuationCooldownMs: 5000 (exponential backoff using consecutive failures)
• abortWindowMs: 3000
• maxConsecutiveFailures: 5
• skipAgents: prometheus, compaction

Test-only env override

• OPENCODE_TODO_ENFORCER_STOP_COMMAND lets you override the stop command string (useful for E2E harnesses).

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run test:integration
bun run test:e2e
bun run check
bun run build

See docs/parity-notes.md for parity and intentional differences from upstream behavior.

Testing strategy

• Unit tests in test/ validate guards, stop-state behavior, and orchestrator event handling.
• Integration test (bun run test:integration) runs end-to-end hook flows against a mocked OpenCode runtime:
  • idle continuation,
  • cooldown behavior,
  • stop/resume behavior,
  • compaction-only skip behavior,
  • completed todo skip behavior.
• Live CLI E2E (bun run test:e2e) runs real opencode run prompts and validates telemetry assertions.
• npm-mode E2E (bun run test:e2e:npm) validates package-installed mode in an isolated sandbox.
• Set OPENCODE_TODO_ENFORCER_E2E_STRICT=true to fail E2E when telemetry events are missing.

Telemetry for verification

This plugin emits optional JSONL telemetry events used by E2E checks:

• Default path: ~/.local/share/opencode/plugins/opencode-todo-enforcer/telemetry.jsonl
• Override path: OPENCODE_TODO_ENFORCER_TELEMETRY_PATH=/abs/path/file.jsonl
• Add run context tags: OPENCODE_TODO_ENFORCER_TELEMETRY_CONTEXT=case-id
• Disable telemetry: OPENCODE_TODO_ENFORCER_TELEMETRY=false

Runtime debug tool

Use the todo_enforcer_debug_ping tool to prove the plugin is loaded and executing.

• It writes a JSONL record to <session-directory>/.opencode-todo-enforcer-debug-pings.jsonl
• It returns { ok: true, marker, ping_path }

npm plugin sandbox

For manual OpenCode verification with the npm package (without local source shims):

bun run opencode:npm
bun run opencode:npm:config

Releasing

• Use bun run release:verify before version bumps.
• Use bun run release:patch|minor|major|beta:first|beta:next for tag/version creation.
• See RELEASING.md for full npm and GitHub release workflow details.