# app-opencode

[opencode](https://opencode.ai/) packaged in a Docker container and wired to
[weave](https://weave.redpencil.io) as the model provider. It ships with an
LSP for TypeScript/JavaScript and Python baked in, so opencode gets real
type-aware navigation out of the box. The default model is `weave/glm-5.2`.

The docs below are split into three parts: a **Getting started** walkthrough to
run it the first time, **How-to guides** for specific tasks, and a **Reference**
for the moving parts.

## Getting started

A first run from a clean checkout.

1. **Get a weave API key.** You need an account on
   [weave.redpencil.io](https://weave.redpencil.io/ui/) and/or an API key (ask us!).

2. **Create your local override.** `docker-compose.override.yml` is gitignored
   and holds your key plus the repo you want opencode to work on. Create it with
   your key and mount:

   ```yaml
   services:
     opencode:
       environment:
         WEAVE_API_KEY: "your-key-here"
       volumes:
         - /path/to/your/repo:/workspace/repo
   ```

3. **Start the container.**

   ```
   drc up -d
   ```

4. **Open the TUI.**

   ```
   drc exec opencode opencode
   ```

You're now in opencode, talking to `weave/glm-5.2`. Type `/models` to switch
models, or just start prompting.

## How-to guides

### Switch the model in a session

In the TUI, type `/models` and pick from the registered weave models. This only
changes the current session; to change the default for every session, edit
`opencode.json` (see below).

### Change the default model

Edit `model` (and optionally `small_model`) in
[`config/opencode/opencode.json`](config/opencode/opencode.json), then apply the
change:

```
drc restart opencode
```

`opencode.json` is mounted into the container, so a restart is all that's
needed.

### Register a new weave model

Add the model under `provider.weave.models` in `opencode.json`:

```json
"provider": {
  "weave": {
    "models": {
      "my-new-model": { "tools": true }
    }
  }
}
```

Then `drc restart opencode`. It will show up in the `/models` picker.
See the [model list on weave](https://weave.redpencil.io/ui/models-and-endpoints/) for an overview of available models. Need another model, please let us know :)

### Copy text out of the TUI

Copying from the opencode TUI over Docker is fiddly: `Shift`+click to select the
text, then `Ctrl`+`Shift`+`C` to copy. A plain copy doesn't work.

### Connect opencode to a (backend) service

To let opencode call a service over HTTP, e.g. a stack you've brought up in dev
mode and want the agent to follow up against, have that stack join opencode's
network instead of publishing ports or going via the host.

opencode's stack creates a default network named `app-opencode_default`. Attach the
dev-mode service to it as an external network:

```yaml
# the dev-mode app stack
services:
  app:
    networks:
      - default
      - app-opencode_default

networks:
  app-opencode_default:
    external: true
```

opencode can then reach it at `http://app:<port>`, where `app` is the **service
name** from that stack's compose and `<port>` is the container's *internal* port.

> Note: Bring the opencode stack up first, so `app-opencode_default` exists before adding to your app.

## Reference

### `opencode.json` keys

- **`model` / `small_model`** — default model and the model used for lighter
  tasks. Both default to `weave/glm-5.2`.
- **`provider.weave`** — the weave provider, using the
  `@ai-sdk/openai-compatible` adapter against `https://weave.redpencil.io/v1`
  with the key from `WEAVE_API_KEY`.
- **`provider.weave.models`** — the models offered in `/models`.
- **`lsp`** — language servers baked into the image:
  `typescript-language-server` for TS/JS and `pyright` for Python.
- **`permission`** — set to `ask` for read, edit, bash, and external-directory
  actions, so opencode prompts before acting.

### Caveats

- Copy from the TUI over Docker needs the `Shift`+click / `Ctrl`+`Shift`+`C`
  dance described above.