OpenCode Task Completion Loop

OpenCode 2 only: Version 2.0.1 requires OpenCode 2.0.27 or newer (2.x). It does not run on OpenCode 1.x. The previous version remains available: npm install [email protected] (or opencode-task-completion-loop@opencode-v1). Install the V2 release with opencode plugin add opencode-task-completion-loop@^2.0.1 and restart OpenCode. For OpenCode 2, use "plugins": ["opencode-task-completion-loop@^2.0.1"] in opencode.json. The instructions below apply to this OpenCode 2 release. Old V1 releases remain available separately. V2 keeps the normal composer intact: the task bar is inserted above the session composer and in the home footer. Start, Update, Pause, Resume and Stop remain explicit user controls.

Maintainer: Joel Buchholz. MIT © 2026 Joel Buchholz.

A native inline /loop bar for OpenCode. It keeps the agent working on a saved task until the agent records verified completion or a real hard blocker.

Features

• Native /loop bar with an editable task field above the session composer; on the home screen it appears in the footer below the composer.
• Running: Update, Pause, Stop. Paused or blocked: Update, Resume, Stop.
• The text cursor and Pause label are white. All other colours follow the active OpenCode theme.
• Uses OpenCode's normal chat, tools, permissions and questions.
• Keeps state per session and rejects stale completion or blocker results.

System requirements

Runtime requirements

• OpenCode 2.0.27 or newer, below 3.0.0.
• Node.js ^22.22.2 || ^24.15.0 || >=26.0.0.
• A configured OpenCode model that supports tool calls.

Development/build requirements

These are required only when building or testing from source:

• Node.js and npm.
• Run npm ci before npm test.

Install in native Windows OpenCode

Open PowerShell:

opencode --version
opencode plugin add opencode-task-completion-loop@^2.0.1
opencode

To replace version 2.0.0 configured with ^2.0.0 (for any other version, copy the exact SOURCE entry from opencode plugin list into the removal command):

opencode plugin list
opencode plugin remove opencode-task-completion-loop@^2.0.0
opencode plugin add opencode-task-completion-loop@^2.0.1

OpenCode adds the package to the global plugins array in opencode.json and installs its npm dependencies. The package supplies both the server tool and the V2 TUI module automatically. No /tui suffix or tui.json entry is required. Remove any old 1.x entries from cli.json before restarting OpenCode.

Install in OpenCode running in WSL or Linux

Open the WSL or Linux terminal:

opencode --version
opencode plugin add opencode-task-completion-loop@^2.0.1
opencode

To replace a ^2.0.0 installation (use the exact SOURCE entry from opencode plugin list if your configured version differs):

opencode plugin list
opencode plugin remove opencode-task-completion-loop@^2.0.0
opencode plugin add opencode-task-completion-loop@^2.0.1

The same commands apply on macOS. Run them inside the environment where OpenCode is installed. Write the package spec with a plain @; no backslash is needed.

Uninstall

opencode plugin remove opencode-task-completion-loop@^2.0.1

This removes the entry installed by the instructions above. If you used a different specifier, run opencode plugin list and remove its exact SOURCE entry. Restart OpenCode. Credentials and saved user data are kept.

Exact behavior

| State | Controls | Bar | | --- | --- | --- | | First /loop or after Stop | Start, Stop | Visible | | Running | Update, Pause, Stop | Visible | | Paused or blocked | Update, Resume, Stop | Visible | | Stop | None | Hidden until /loop |

Start validates and saves the task, then begins the loop. Update saves text only and does not change its state. Pause stops automatic continuation and requests cancellation. Resume starts another attempt with the saved task. Stop deletes the saved task and hides the bar. Escape returns focus to normal chat without changing the loop.

A hard blocker stays paused until you choose Resume or Stop. Existing file changes and external actions cannot be undone by cancellation.

Slash commands

| Command | Use | | --- | --- | | /loop | Opens or focuses the task bar. |

Enter the task in the bar, not after /loop.

Tools

| Tool | Purpose | | --- | --- | | task_goal_decide | Records verified completion or a concrete hard blocker for the active loop. |

Decisions

The model must use the current run ID and revision from its task-loop instruction. Completion needs concrete evidence. A blocker needs the specific missing prerequisite. Plain assistant text, stale results and results from another session do not end a loop.

Recommended global context

The user controls task loops through the native /loop bar.
When a TASK LOOP instruction is present, continue useful work on its latest task.
A plan, progress report, question, or partial result does not complete the task.
Call task_goal_decide only after verified completion, or for a real hard blocker with what is missing.
Do not try to start, pause, resume, stop, or render loop controls yourself.

Configuration

OpenCode keeps only package references in the configuration:

{
  "plugins": ["opencode-task-completion-loop@^2.0.1"]
}

For a TUI-only installation, use the same package spec in the plugins array of cli.json. A normal installation in opencode.json loads both parts; do not duplicate it in cli.json.

Build and verification from source

npm ci
npm test

The test suite covers the task-loop state machine, server protocol, slash command, native TUI controls, package contents and the required completion/blocker decisions.

Publishing

Run npm test, then publish the verified package version with npm publish.

Verification scope: Native Windows and OpenCode 2.0.27 are tested. Linux/macOS/WSL support is implemented where applicable but has not been retested on those platforms for this release. Automated provider fixtures do not prove live model-account integration.

Maintainer

Joel Buchholz on LinkedIn

License

MIT