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