randomix777/dsh-opencode-zen

[!CAUTION] Deprecation notice (2026-10-06). OpenCode's free tier is now restricted to requests originating from inside OpenCode itself — external callers (including this plugin, and any other DSH/Harness plugin using the same endpoints) are rejected with FreeTierError: "OpenCode's free tier can only be used from within OpenCode". As of today the plugin's free-model feature no longer works for new users. The zen/v1 endpoint remains available for paid models (using an OPENCODE_API_KEY), but that mode is identical to what DSH's llm-pi-ai configuration offers natively, so the plugin no longer adds value.

The repo is being archived in this state. The fork's quota-tracker, persistent-cache, and retry improvements (v0.2.x) are preserved in git history for anyone who wants to port them to a maintained project.

What's new in this fork (v0.2.1)

• Free quota rate-limit tracker — records 429s, estimates reset time, shows countdown
• Persistent quota state — survives DSH restarts via ~/.dsh/cache/opencode-zen-quota.json
• 8 verified free models (cross-checked against live Zen — no phantom entries)
• Persistent file cache — catalog survives DSH restarts
• Retry with exponential backoff — 2 retries, 500ms/1s delay
• Improved error messages — clearer guidance on quota limits
• Updated config schema — cachePath option for custom cache location

All models are verified to exist on both models.dev (cost=0) and Zen's /v1/models endpoint.

Install it and configure nothing. Zen's free models accept anonymous calls, so once the plugin boots, a group of working models simply appears in the model picker.

Model picker
├─ nemotron-3-ultra-free         1M context
├─ muse-spark-1.2-contributor-free 1M context
├─ nemotron-3.5-lightning-free   256K context, 256K output too
├─ ling-3.0-flash-fin-free       256K context
├─ laguna-s-2.1-free             256K context
├─ deepseek-v4-flash-free        200K context, 128K output
├─ big-pickle                    Zen's own anonymous evaluation model
└─ mimo-v2.5-free                200K context

All support tool calls and reasoning content, enough to run a full agent loop — not a chat-only cut-down.

The list is not hardcoded; it is fetched at runtime: models.dev decides which are free and how large, Zen's model endpoint decides which still exist, and the plugin takes the intersection. Free models are offered for a limited time, so any hardcoded list is guaranteed to go stale. The bundled snapshot is only a fallback for when both sources are unreachable.

Install

Not published to npm — install from GitHub:

dsh plugin --profile web add -w github:randomix777/dsh-opencode-zen

Then restart dsh once, and the opencode-zen group appears in the model picker.

Three notes:

• -w is not optional. The profile directory ships a pnpm-workspace.yaml, so pnpm treats it as a workspace root; without the flag you get ERR_PNPM_ADDING_TO_ROOT.
• No build-script authorisation needed. The repository ships its build output and has no prepare script, so pnpm runs no build for a git source. You do not need allowBuilds, nor a build toolchain on your machine.
• --profile is whichever you already use (web or headless). This is an LLM provider; it does not depend on the web GUI.

To confirm it really entered the Loader tree:

dsh --profile web --dump-config | grep -A 1 opencode-zen
# - id: opencode-zen
#   name: dsh-opencode-zen

To hack on it, install locally:

git clone https://github.com/randomix777/dsh-opencode-zen
cd dsh-opencode-zen && pnpm install && pnpm build
dsh plugin --profile web add <absolute path to that directory>

Do I need an API key

No. Anonymous calls draw on Zen's shared free quota. It is rate-limited by source — plenty for trying things out, though sustained volume will hit FreeUsageLimitError.

For a private quota, grab a key at opencode.ai/zen:

export OPENCODE_API_KEY=<your key>

The variable name matches opencode's own, so if you already use opencode, one key serves both. You can also store it in the credentials service from dsh's Models page; the plugin reads that first.

When the quota runs out, the plugin does not just say Rate limit exceeded — it tells you whether you are anonymous or keyed, and what to do next.

Configuration

All optional. An empty config gives the behaviour described above.

plugins:
  dsh-opencode-zen:
    apiKeyEnv: OPENCODE_API_KEY        # credential reference (an env var name)
    baseURL: https://opencode.ai/zen/v1
    catalogUrl: https://models.dev/api.json
    catalogTtlMs: 3600000              # catalog TTL, one hour by default
    catalogTimeoutMs: 8000             # catalog request timeout
    maxTokens: 32000                   # output cap; the model's own lower cap wins
    defaultContextWindow: 128000       # assumed when the catalog has no entry
    cachePath: ~/.dsh/cache/opencode-zen-catalog.json  # persistent cache (default)

Set cachePath: "" to disable file caching entirely.

Known limits

• The free quota is shared, and anonymous calls hit the limiter most easily. That is Zen's policy; all the plugin can do is state the reason clearly.
• Reasoning is not sent back. OpenAI-compatible chat/completions has no request field to carry the previous turn's thinking, so reasoning blocks are displayed, not replayed.
• Text only. All models take text alone; an image in a tool result is replaced with a one-line placeholder rather than dropped silently.
• Paid models are excluded. Zen also offers Claude, GPT and others, but this plugin exists so that things run with zero configuration — mixing paid models into the same list makes it unclear which choice costs money. To use them, add an llm-deepseek entry pointing at the same endpoint.

Development

pnpm install
pnpm check      # type check
pnpm test       # unit tests
pnpm build      # bundle to lib/

lib/ is committed on purpose. This package is not published to npm; everyone installs from a git source, and whether pnpm can build a git source depends on the other machine's toolchain and allowBuilds grants. Shipping the output removes that variable — commit the pnpm build output along with your code changes.

File	Responsibility
src/index.ts	Plugin entry: config validation, credential resolution, provider registration on ctx.llm
src/adapter.ts	LlmAdapter implementation: requests, error mapping, model metadata
src/stream.ts	State machine turning SSE deltas into the harness block sequence
src/discovery.ts	Two-source merge, caching (in-memory + file), fallback and retry for the free catalog
src/quota-tracker.ts	Rate-limit detection: tracks 429s, estimates reset time, persists state to disk
src/fs-cache.ts	File-based cache helpers (no-op on browsers)

Related

• OpenCode Zen — the model gateway itself; keys come from here
• DeepSeek Harness — the host
• dsh-plugin-subs — OAuth sign-in for subscription LLMs
• dsh-sprite-gen — AI sprite generation plugin
• Original: keman-ai/dsh-opencode-zen

License

MIT © 2026 Science Roam Limited (fork & optimization by randomix777)

---