oc-free-provider

oc-free-provider

An unofficial Hermes model-provider for OpenCode Zen free models. Hermes keeps
control of the agent loop and executes tools locally; the provider only handles
model discovery and inference transport.

It does not run opencode serve, ACP, or a tool-execution proxy.

Compatibility and terms notice

This project is independent, unofficial, and not affiliated with or endorsed by
OpenCode. It is intended for a user's own internal use on systems they control.
It does not grant access to OpenCode Zen or any model, and it is not legal
advice.

OpenCode's Zen documentation describes Zen as
usable with other coding agents. That general interoperability statement is not
an authorization for every client, authentication method, workload, or use
case. This plugin's current public compatibility transport is not documented by
OpenCode as a supported Hermes integration and may be changed or disabled at
any time.

Before using the plugin, review and independently comply with the current:

• OpenCode Terms of Service
• OpenCode Zen documentation
• terms, privacy notices, and acceptable-use rules for the selected model

In particular, use the service only when you have the right to access it. Do
not use this project to provide inference for third parties, resell or proxy the
service, scrape or bulk-extract outputs, evade quotas or rate limits, rotate
accounts or identities for additional free usage, conceal prohibited activity,
or bypass an access restriction. A disclaimer cannot make a prohibited use
compliant. If OpenCode requires an account, API key, paid access, or a supported
client for your intended use, do not use this compatibility transport instead.

Free-model labels describe pricing, not permission or privacy. Some free,
trial, and contributor models may use prompts or completions for model
improvement or may prohibit confidential data. Check the current Zen model
notice before every use and never send secrets or regulated data unless the
applicable terms expressly allow it.

Bidirectional tool translation

Hermes remains the agent runtime: it applies its normal policy and approval
rules, executes tools locally, and returns each result to the model. The plugin
is a bidirectional adapter between OpenCode's tool vocabulary and Hermes':

1. Hermes → OpenCode: available native Hermes schemas are exposed under
   their OpenCode-compatible names. Their native duplicates are omitted, while
   unrelated Hermes tools remain available under their native names.
2. OpenCode → Hermes: model tool calls are translated back to native Hermes
   names and argument shapes before local dispatch.
3. Hermes → OpenCode continuation: recorded native calls are translated
   back to OpenCode names and arguments when conversation history is replayed,
   keeping the model on one consistent vocabulary. Tool results retain their
   call IDs and payloads. Explicit tool choices are translated the same way.

The bidirectional pairs are:

• bash ↔ terminal
• edit ↔ patch
• glob / grep ↔ search_files
• read ↔ read_file
• skill ↔ skill_view
• task ↔ delegate_task
• todowrite ↔ todo_list
• webfetch ↔ web_extract
• websearch ↔ web_search
• write ↔ write_file

An alias is advertised only when its target tool was supplied by Hermes. If the
model calls an unavailable compatibility alias, the request fails
closed—nothing is executed and no success is fabricated. Streamed tool
arguments are buffered until their JSON is complete before translation.

The adapters preserve executable intent, not every OpenCode runtime option.
bash.timeout is converted from milliseconds to seconds; todo order is
preserved but OpenCode's priority label is discarded; OpenCode read directory
listing and image-attachment behavior is not emulated; webfetch
formatting/timeout hints and advanced websearch crawl hints have no Hermes
equivalent; and OpenCode task metadata is passed to the Hermes subagent as
context while Hermes controls scheduling.

Install

hermes plugins install oc-free-provider --enable

The plugin does not install or run the OpenCode CLI, Node.js, npm, or npx.
Model discovery and inference use Python's standard-library HTTPS client, so the
same code path works on Linux, macOS, and Windows.

Select the provider and one of its discovered models:

hermes model
# Provider: opencode-free

Model discovery

The plugin intersects OpenCode Zen's live /v1/models response with the
OpenCode catalog metadata published by models.dev. It
exposes only live, tool-capable models whose published input/output/cache costs
are all zero. The resulting intersection—not the full upstream responses—is
cached for the gateway process and persisted under the active Hermes profile.
Each new gateway process queries both endpoints once; if refresh fails or finds
no qualifying model, the plugin uses the last successful intersection, then
the verified entries bundled with it when no cache exists. It selects
/chat/completions or /responses according to the known model transport.

Model availability, pricing, retention, and data-use rules belong to OpenCode
and the underlying provider and can change independently of this repository.

Verify

python -m unittest discover -s tests -v
hermes plugins validate . --json

hermes plugins doctor . also verifies runtime discovery, import, and provider
registration.

License

MIT.

README from the reviewed commit ae705c6; it updates when the author re-pins.