The best way to control Claude Code, Codex and more from any computer or phone

main
md 93 lines 4.62 KB
Rendered Raw
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.