Skip to content

docs: document OpenCode Desktop limitation #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yuseferi merged 2 commits into from
Sep 13, 2026
Merged

docs: document OpenCode Desktop limitation #29

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
031da93
docs: document OpenCode Desktop limitation
yuseferi Sep 13, 2026
722ea40
docs: clarify Desktop issue tracking
yuseferi Sep 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,7 @@ sequenceDiagram
Plugin->>Cache: persist for next startup
end
Note over Plugin,Cache: on session.created, revalidate cache in<br/>the background (throttled to 5 min)
OC->>OC: render model picker with all discovered models
OC->>OC: render model picker with all discovered models (CLI)
```

1. On OpenCode startup the `config` lifecycle hook fires.
Expand All @@ -348,6 +348,8 @@ sequenceDiagram
6. Discovered models are merged on top of any user-defined ones — never overwriting them — and persisted to the cache.
7. On every `session.created` event the cache is revalidated in the background (throttled to once per 5 minutes); refreshed entries surface on the next OpenCode start. The whole cold path is capped by a 20 s timeout so a slow proxy never blocks boot.

> **OpenCode Desktop:** Dynamic LiteLLM models currently appear in the CLI but may not appear in the Desktop model picker. This is an observed OpenCode Desktop config-hook limitation: plugin mutations are not reflected in the provider state used by the picker. The plugin cannot safely work around this without persisting resolved configuration and credentials. Track [issue #5](https://github.com/yuseferi/opencode-litellm/issues/5) for updates.

## 📋 Requirements

- [OpenCode](https://opencode.ai) ≥ 0.1.x with plugin support (`@opencode-ai/plugin ^1.14.0`)
Expand Down Expand Up @@ -380,6 +382,15 @@ delete the cache directory (`~/.cache/opencode-litellm/`, or
`$XDG_CACHE_HOME/opencode-litellm/`).
</details>

<details>
<summary><b>Why do discovered models appear in the CLI but not OpenCode Desktop?</b></summary>

OpenCode Desktop currently does not reflect mutations made by a plugin's
`config` hook in the provider state used by its model picker. The plugin works
as expected in the CLI, but there is no safe plugin-side workaround yet. This
is being tracked in [issue #5](https://github.com/yuseferi/opencode-litellm/issues/5).
</details>

<details>
<summary><b>Can I use this with a remote LiteLLM proxy?</b></summary>

Expand Down
Loading