/opencode-runner

name: opencode-runner
description: "Run coding tasks via opencode using free cloud models. Use when asked to offload work to opencode.ai or run a free model. Don't use for local models (Ollama, LM Studio), Claude/OpenAI calls, or when Claude should do the work itself."
license: MIT
effort: medium
metadata:
  version: 1.6.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

OpenCode Runner

Delegate coding tasks to opencode using free models — zero cost, fully automated.

OpenCode (opencode.ai) is a terminal AI coding assistant that supports multiple providers and models. This skill automates the process of selecting the best available free model, launching the task, and reporting progress back to you.

Prerequisites

• **opencode installed**: `which opencode` must succeed; install via `npm i -g opencode-ai@latest` or `brew install opencode` if missing
• **Internet access**: required for cloud model selection and task execution via OpenCode Zen
• **Project context**: the current working directory should be the project root for file-context tasks

Critical Rules

1. **Never do the task yourself.** This skill exists solely to delegate work to opencode. If opencode is not installed, fails to run, or no free cloud model is available — report the problem to the user and **stop**. Do not fall back to editing files directly, writing code yourself, or using any other tool to accomplish the user's coding task. The whole point is that opencode does the work.

2. **Only select cloud models.** Never select local models (e.g., `ollama/*`, `lmstudio/*`, or any model running on localhost). Only select models from the `opencode/*` provider namespace, which are cloud-hosted on OpenCode Zen. Local models have unpredictable availability, performance, and may not support the tool-use capabilities opencode needs.

3. **Always clean up after yourself.** opencode spawns background processes (LSP servers, MCP servers, node workers) that persist after the task finishes. Every execution path — success, failure, error, timeout — must end with the cleanup steps in Phase 6. Orphaned opencode processes silently eat CPU and memory, and users won't notice until their machine slows to a crawl.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If `origin` is missing or conflicts occur, stop and ask the user before continuing.

Phase 1: Verify Installation

Check that opencode is installed and at the latest version.

Step 1: Check if installed

which opencode && opencode --version

If `opencode` is not found, tell the user:

> opencode is not installed. Install it with one of these commands: > > ```bash > curl -fsSL https://opencode.ai/install | bash > ``` > or > ```bash > npm i -g opencode-ai@latest > ``` > or (macOS) > ```bash > brew install opencode > ```

Then **stop completely** with `BLOCKED — opencode is not installed` (*Final Report*) — do not proceed to any other phase, do not attempt the task yourself, do not edit any files. Wait for the user to install opencode and re-invoke this skill.

Step 2: Check for updates

1. Run `opencode upgrade`. It upgrades to the latest version, or confirms the installed one is current. 2. If `opencode upgrade` exits non-zero, tell the user its error and suggest running `opencode upgrade` manually. Then continue to item 3. 3. Run `opencode --version` again. 4. If `opencode --version` exits non-zero, stop with `BLOCKED — opencode does not start after the upgrade`. Do not continue to Phase 2.

Phase 2: Discover Free Models & Let User Pick

Query the available models, present the free ones to the user, and let them choose. If the user doesn't choose, fall back to the priority order.

opencode models 2>/dev/null

Free model priority list (default order if user defers)

| Priority | Model ID | Notes | |----------|----------|-------| | 1 | `opencode/deepseek-v4-flash-free` | Strong recent free coding model — preferred default | | 2 | `opencode/minimax-m2.5-free` | MiniMax free tier — good general-purpose | | 3 | `opencode/nemotron-3-super-free` | NVIDIA Nemotron free tier | | 4 | `opencode/big-pickle` | Free fallback | | 5 | `opencode/gpt-5-nano` | Small fallback; free only when `opencode models` prices it at $0 |

Model IDs evolve. A model is **free-tier eligible** when its ID is in the `opencode/*` namespace and one of these holds: the ID ends in `-free`, the ID is `opencode/big-pickle`, or the `opencode models` output prices it at $0. Match by suffix, not by exact ID. Without a $0 price in the output, leave `opencode/gpt-5-nano` out.

Selection logic

1. Run `opencode models` and collect all entries. 2. **Filter out all non-`opencode/*` models** — ignore anything from `ollama/*`, `lmstudio/*`, `nvidia/*`, or any other namespace. Only cloud-hosted `opencode/*` models qualify. 3. Among the remaining list, keep only the free-tier eligible models. 4. **Present the free models to the user as numbered options**, in priority order, with priority 1 marked as the default. Use the `<options>` format if possible. Example:

> I found these free cloud models available via opencode. Pick one, or accept the default. > > 1. `opencode/deepseek-v4-flash-free` *(default — priority 1)* > 2. `opencode/minimax-m2.5-free` > 3. `opencode/nemotron-3-super-free` > 4. `opencode/big-pickle`

5. If the user names a model, use that one. If the user says "default", "you pick", "any", or doesn't specify, use priority 1 (the highest-priority available free model). 6. If no free-tier eligible model remains, **stop** with