OpenCode 2.0 Launches: Refactored as Background Service with Unified Multi-Client Sessions and New API

OpenCode 2.0 is a major over haul. It draws on mil lions of daily users' expe ri ence to deliver a system that can flex to every thing an agent needs to be. There are quite a lot of new fea tures, per for mance improve ments, and bug fixes but here are some of the more impact ful user-facing changes.

The Service

From the begin ning OpenCode adopted a client/server model. However, this was not some thing it took advan tage of and was mostly used users.

In 2.0 this server now auto mat i cally runs as a single back ground process on your machine. When you open up a TUI, the web inter face or the desktop app they're all talking to the same central process.

opencodepid 48213StoppedStartingRunningSessionsFix flaky testAdd dark modeReview changes

If you're using the pro gram matic client @opencode/client to make your own scripts, they will autodis cover the local service and just work. This is par tic u larly useful for sched uled tasks. You can also call it via CLI opencode api com mands.

You can expose it to other hosts and run /pair or opencode pair to connect it to other appli ca tions. We have native apps in the works that take advan tage of this flow.

The API

The old API grew hap haz ardly as we and the world col lec tively learned what agents are and should be. It was bad.

We started from scratch and exam ined all the weird use cases across the mil lions of users who use OpenCode every day. It now sup ports nearly any thing you need to be able to do.

OpenCode is also aware of its own API and will call it to do useful things like moving the current session into a git work tree when start ing new work.

SessionNew sessionOpenCode~/appFix flaky upload testinterruptedMigrate config loadertab closedNew sessionthis session~/worktrees/rate-limit

We've also shipped a new client package @opencode/client that con tains clients for vanilla JavaScript as well as Effect.

review.ts

import { OpenCode } from "@opencode/client"
import { Service } from "@opencode/client/service"

const endpoint = await Service.ensure()
const client = OpenCode.make({
  baseUrl: endpoint.url,
  headers: Service.headers(endpoint),
})

const session = await client.session.create({
  location: { directory: process.cwd() },
})

await client.session.prompt({
  sessionID: session.id,
  text: "Review the current changes",
})

Code Mode

The models love to write code and OpenCode 2.0 takes advan tage of that more than any other coding agent. We've built a minimal JavaScript inter preter in the @opencode/codemode package.

SessionCode ModeMCP serversgithublinearsentry

This package ingests MCP servers or OpenAPI end points, con vert ing them into func tions that the agent can call in a script. It can run these scripts natively without the com plex ity of Node.js VMs or embed ding com pli cated solu tions like QuickJS.

This lets your agent write scripts that can do things like call a tool, map over the results and call another tool. Single round trip instead of calling them one at a time.

All MCP servers in 2.0 are opted into code mode This means you can add a thou sand of them with minimal context bloat and your agent will dis cover and compose them to get things done.

Background Tasks

The latest batch of models are incred i bly good at orches tra tion and it is impor tant for har nesses to let them express the full extent of that capa bil ity.

SessionBackgroundctrlb

First, we've added back ground sub agents. This allows the primary agent to kick off some work to another one while it con tin ues.

This happens auto mat i cally but you can also trigger it man u ally

even with a dif fer ent model. It lets you do things like “spawn a back ground fable sub agent to review this code” while you keep prompt ing.

Second, we've added back ground shell com mands. The shell tool can be invoked asyn chronously so long-running work does not have to block the primary agent. It'll be noti fied when things are com plete.

If any fore ground shell command or sub agent takes longer than you expect, you can hit a hotkey to move them to the back ground so you can keep prompt ing.

Plugins

Although OpenCode 1.0 had a plugin system, it never got the atten tion it needed. To correct that, we forced our selves to imple ment nearly every OpenCode 2.0 feature as an inter nal plugin and there are now 80+ of them. This guar an tees that the Plugin API stays well main tained.

We've also pro moted TUI plugins from exper i men tal to stable. Since it is all powered by OpenTUI, you can build nearly any thing. Here is an example of some thing useless.

We also spent quite a lot of time ensuring everything in OpenCode 2.0 can be hot-reloaded. So it can write a plugin for itself mid-session and use it right away - we covered the design of this in a previous blogpost.

You can ask OpenCode to build whatever plugin you want and it knows how to. But if you do want to read the docs, they are available here.

The SDK

OpenCode can also now be used as a library with the @opencode/sdk package. This is the exact same code that powers our CLI.

This means you can strip it down and make your own flavor of OpenCode that runs on a server or in spe cial ized envi ron ments like Durable Objects. And then you can connect to it from any OpenCode client since it speaks the stan dard OpenCode server pro to col.

It also has an optional Effect-based API.

This one is still in development as things are shifting but you can already use it.

Upgrading

To upgrade the CLI, make sure you're on the latest 1.x release, then run opencode upgrade --major.

To upgrade your desktop app, download the latest here.

There are some break ing changes.

1.0 plugins will not work in 2.0

Server API is completely different

tui.json config is moved to json

There are a lot of other changes but they are backwards compatible. It is worth pointing OpenCode at this doc so it can migrate things for you.