# OpenCode

> How midcode runs OpenCode in the chat and in a terminal, with the providers and models you set up in it, and what to check when it won't start.

- Page: https://midcode.app/docs/agents/opencode
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

OpenCode runs in midcode's Agent panel in both views, with whichever providers and models you configured in it. midcode needs no key of its own for the model: it starts OpenCode in your project's folder and shows what it does.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `opencode acp` | `opencode`, typed into a login shell |
| Needs on your Mac | OpenCode, with a provider set up | OpenCode, with a provider set up |
| Account | The providers and keys in your OpenCode | The providers and keys in your OpenCode |
| OpenCode's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with OpenCode or git |

## Set it up

1. Install OpenCode, if you don't have it:

   ```bash
   npm install -g opencode-ai
   ```

2. Run `opencode` once in a terminal and connect the provider you want to use.
3. In midcode, open the Agent panel and choose OpenCode in the "Agent" menu.

If the panel says "OpenCode isn't installed", it shows the same command with a button to copy it. Press "Check again" once it's installed.

## The chat

OpenCode speaks the Agent Client Protocol by itself, so there is no adapter in between and nothing extra is downloaded: midcode runs the `opencode` on your login shell's `PATH` with `acp`, in your project's folder. The version is the one you installed. If it takes more than a few seconds to answer, the panel says "Getting OpenCode ready" while it waits.

- **Your models.** The pickers under the prompt are whatever OpenCode reports for the session (its mode, model and effort options, when it has them), so the models are the ones of the providers you connected. midcode adds none, and remembers the model you chose for OpenCode separately from the other agents.
- **Its commands.** Typing `/` at the start of the prompt lists the commands OpenCode reports.
- **Its permissions.** When OpenCode asks before it does something, the card in the thread has OpenCode's own choices. Which actions it asks about is set in OpenCode.

Each edit OpenCode makes is one `⌘Z` step and a line in [Publish](https://midcode.app/docs/publish/publish.md), named after it ("OpenCode: …").

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `opencode`. It's OpenCode's own interface, as in your terminal. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view OpenCode writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat's agent doesn't get provider keys from your shell's variables. When midcode starts an agent it leaves out the variables that start with `ANTHROPIC_`, `OPENAI_`, `GEMINI_` and `CODEX_`, so an `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` exported in your shell profile doesn't reach OpenCode there. Connect the provider inside OpenCode so it keeps the credential itself, or use the Terminal view, which is your shell.
- midcode doesn't configure OpenCode: providers, models, agents and permissions are set in OpenCode.

## Troubleshooting

**"Sign in to OpenCode first: run opencode once in a terminal."** OpenCode started but has no provider it can use. Connect one, then press "Try again".

**"OpenCode couldn't start".** The panel shows the reason it was given, often the last line OpenCode printed. An OpenCode too old to have the `acp` command is one cause: update it with the install command above.

**"OpenCode isn't installed", and it is.** Check that `opencode` runs in a new terminal window. midcode looks on your login shell's `PATH`; if installing it added a folder to your `PATH`, quit midcode and open it again.

To have OpenCode write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).