opencode-runner

What this skill does

# 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:

```bash
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:

```bash
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

```bash
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** — 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

```bash
opencode upgrade
```

This will upgrade to the latest version if one is available, or confirm already up to date. If the upgrade fails, inform the user of the error and suggest running the command manually. If the upgrade itself breaks opencode, stop and report — do not continue.

## 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.

```bash
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, low-cost fallback (verify pricing) |

Model IDs evolve. When parsing `opencode models` output, treat any `opencode/*` model whose ID ends in `-free` (or is explicitly priced $0) as free-tier eligible. Match by suffix, not by exact ID.

### 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, identify the free candidates (suffix `-free` or known-free IDs from the priority list).
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 cloud models exist at all, inform the user and **stop** — do not fall back to local models, paid models, or doing the task yourself.

**Privacy note** (always show this with the model list): Free models on OpenCode Zen may use collected data for model improvement.

## Phase 3: Confirm Before Executing

Before invoking opencode, show the user a one-screen summary and get explicit confirmation. This catches wrong-model or wrong-prompt mistakes before any tokens are burned.

Present this block:

> **Ready to delegate to opencode**
>
> - **Model:** `opencode/deepseek-v4-flash-free` (free tier)
> - **Working directory:** `/Users/.../current-project`
> - **Context files:** `path/to/foo.py`, `path/to/bar.py` *(or "none")*
> - **Prompt:** *(quote the prompt verbatim, multi-line OK)*
> - **Estimated duration:** unknown — opencode is non-deterministic; cleanup runs even on timeout
>
> Confirm to proceed, or tell me what to change (model, prompt, files).

Then offer the user two `<options>`: "Proceed" and "Change something". Wait for confirmation. Do **not** invoke `opencode run` until the user confirms.

If the user asks to change anything (different model, edit prompt, add/remove context files), loop back: update the field, re-show the summary, and ask again.

## Phase 4: Execute the Task

Run the coding task with the confirmed model. **Always run in the background with output redirected to a log file** — this is required for the low-token monitoring strategy in Phase 5.

```bash
LOG=/tmp/opencode-$$.log
opencode run -m "[confirmed-model-id]" "[confirmed prompt]" > "$LOG" 2>&1 &
OPENCODE_PID=$!
echo "opencode started: pid=$OPENCODE_PID log=$LOG"
```

### Handling multi-line or complex prompts

For tasks that reference files or need detailed context, use the `--file` flag:

```bash
opencode run -m "[confirmed-model-id]" --file path/to/relevant-file.py "[task description]" > "$LOG" 2>&1 &
OPENCODE_PID=$!
```

Foreground execution is **discouraged** — streaming the full opencode output back into your context wastes tokens. The Phase 5 monitor reads only the log tail.

## Phase 5: Monitor with Minimum Tokens

opencode output is verbose. Streaming the full log back into your context is expensive — a single long run can easily push past 10k tokens of stream chatter. Use the lightweight polling protocol below instead.

### Polling protocol

Run **one** tiny status command per check. It returns at most ~200 bytes — enough to know status, elapsed time, and the latest activity line — without ingesting the whole log.

```bash
LOG=/tmp/opencode-$$.log   # the same log file from Phase 4
status() {
  if kill -0 $OPENCODE_PID 2>/dev/null; then s=running; else s=done; fi
  bytes=$(wc -c < "$