The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # OpenCode |
| 2 | |
| 3 | Install and authenticate OpenCode on the machine running your environment, then |
| 4 | enable it in **Settings > Providers**. See [provider setup](./install.md#providers). |
| 5 | T3 Code requires OpenCode 1.14.19 or newer, including when you connect an existing |
| 6 | OpenCode server. |
| 7 | |
| 8 | ## OpenCode 2 |
| 9 | |
| 10 | T3 Code supports OpenCode 2.0.18 and newer. It detects the version on its own, so |
| 11 | the same provider settings work for OpenCode 1.x and 2.x. OpenCode 1.x shows |
| 12 | **Limited support** in its provider settings. |
| 13 | |
| 14 | OpenCode 2 is a separate package, `@opencode/cli`. To move from 1.x, install it |
| 15 | yourself, for example `npm install -g @opencode/cli`. Then refresh provider status. |
| 16 | T3 Code's update button updates whichever package you have installed. It never |
| 17 | switches a 1.x install to 2.x. |
| 18 | |
| 19 | OpenCode 2 converts the shared OpenCode database to its own format the first time it |
| 20 | runs. Don't run OpenCode 1.x and 2.x side by side on the same machine. Threads you |
| 21 | started on 1.x continue on 2.x. |
| 22 | |
| 23 | ## Compaction |
| 24 | |
| 25 | OpenCode compacts long conversations itself, and T3 Code has no setting for it. On |
| 26 | OpenCode 2, change it under `compaction` in an OpenCode configuration file, such as |
| 27 | `opencode.json`: `auto` turns |
| 28 | automatic compaction on or off, `buffer` sets the token headroom, and `keep.tokens` |
| 29 | sets how much recent context stays. OpenCode 1.x configures compaction differently. |
| 30 | Send `/compact` to compact a thread yourself. |
| 31 | |
| 32 | ## Local or external server |
| 33 | |
| 34 | Leave **Server URL** empty to let T3 Code start OpenCode locally. A password in |
| 35 | provider settings applies to both that server and T3 Code's connection. With no |
| 36 | password setting, the local server uses `OPENCODE_SERVER_PASSWORD` from its |
| 37 | environment. |
| 38 | |
| 39 | To use an existing OpenCode server, set **Server URL** and its password in provider |
| 40 | settings. T3 Code uses only that configured password for an external server; it |
| 41 | does not forward a local `OPENCODE_SERVER_PASSWORD`. If connection or version checks |
| 42 | fail, check the URL, credentials, and OpenCode version, then refresh provider status. |
| 43 | |
| 44 | When **Server URL** points to a locally running server (such as `127.0.0.1`), |
| 45 | the update button upgrades its installed CLI. If that server is this machine's |
| 46 | OpenCode background service, T3 Code then restarts it on the new version. The URL |
| 47 | must use the service's own protocol, host, and port. For a service listening on |
| 48 | `0.0.0.0` use `127.0.0.1`, and for `[::]` use `[::1]`. |
| 49 | |
| 50 | Restarting interrupts running turns, and the service then runs with T3 Code's |
| 51 | environment. Set any variables it needs with `opencode service set env <name> <value>`. |
| 52 | |
| 53 | T3 Code does not restart any other server, including the background service |
| 54 | reached through `localhost`. That server can still report the previous version |
| 55 | until you restart it. For a loopback URL, T3 Code shows that restart requirement |
| 56 | instead of treating the CLI update as a failure. |
| 57 | |
| 58 | T3 Code waits for a local server it started to recover after a lost connection. |
| 59 | You can stop the turn while it reconnects. If the server exits or an external |
| 60 | connection cannot be restored, send another prompt to resume the same OpenCode |
| 61 | session. |
| 62 | |
| 63 | ## Approvals |
| 64 | |
| 65 | OpenCode follows the shared [permission modes](./permission-modes.md). **Auto** has |
| 66 | the same rules as **Supervised** because OpenCode has no AI approval reviewer. |
| 67 | Environment files such as `.env` and `.env.local` need approval in restricted |
| 68 | modes even though normal file reads do not; `.env.example` is allowed. |
| 69 | |
| 70 | **Allow for workspace** applies to matching requests in other OpenCode sessions |
| 71 | using the same workspace. It is broader than the current thread, especially on a |
| 72 | shared external server. Use **Allow once** for a single request. Denying an action |
| 73 | does not stop the whole turn. |
| 74 | |
| 75 | ## Refresh models, commands, and skills |
| 76 | |
| 77 | After changing an OpenCode login or configuration, use **Refresh provider status** |
| 78 | in **Settings > Providers** for that environment. On mobile, use **Refresh models** |
| 79 | in the thread settings. Reconnecting also refreshes the catalog; periodic provider |
| 80 | health checks do not. |
| 81 | |
| 82 | Credential changes are read on refresh. Native OpenCode configuration can remain |
| 83 | cached while the local helper is running. Let it sit for 30 seconds without model |
| 84 | refreshes or text-generation work, then refresh again to reload the files. Repeated |
| 85 | refreshes keep the helper alive. An external server may need its own reload or |
| 86 | restart before T3 Code can see configuration changes. |
| 87 | |
| 88 | Models defined in a project's own `opencode.json` appear only in that project's |
| 89 | model picker, after T3 Code reads the project's catalog the first time the picker |
| 90 | opens there. |
| 91 | |
| 92 | Existing threads keep their selected model and options even when it disappears |
| 93 | from the catalog. If OpenCode rejects that model, select an available one and retry. |