---
title: "How to use AgentDrive in OpenCode"
description: "How the AgentDrive plugin syncs OpenCode sessions, how to resume a Claude Code or Codex session with /agentdrive-resume, and what to do when a provider stops."
canonical: "https://agentdrive.sh/blog/use-agentdrive-with-opencode"
last-updated: "2026-11-18"
---
# How to use AgentDrive in OpenCode

> For the complete documentation index, see [llms.txt](https://agentdrive.sh/llms.txt). Every docs page is also served as markdown at its URL plus `.md`, and the full docs are in one file at [llms-full.txt](https://agentdrive.sh/llms-full.txt).

> How the AgentDrive plugin syncs OpenCode sessions, how to resume a Claude Code or Codex session with /agentdrive-resume, and what to do when a provider stops.

By Rakesh Roushan, November 18, 2026. Source: https://agentdrive.sh/blog/use-agentdrive-with-opencode

OpenCode has no hooks file, so AgentDrive reaches it through a plugin. After `npm install -g @adrive/cli` and `adrive init`, a generated `plugins/agentdrive.ts` syncs each session, the MCP server sits in `opencode.json`, and `/agentdrive-resume` loads a handoff brief from your Claude Code, Codex, Cursor or Antigravity session in the same project.

The plugin also changes what you get compared with the other four agents: one less event, no startup hint, and a different answer to "what do I do when it runs out". I'll take those in turn. The versions in play are CLI 1.4.0 and MCP server 1.3.0. Keep the [OpenCode integration page](https://agentdrive.sh/integrations/opencode) open if you want a quick reference beside it.

## How does the AgentDrive plugin hook into OpenCode? [#how-does-the-agentdrive-plugin-hook-into-opencode]

OpenCode loads TypeScript plugins from its config folder and runs them in its own runtime. Init writes one there, at `$XDG_CONFIG_HOME/opencode/plugins/agentdrive.ts` (`~/.config/opencode/plugins/agentdrive.ts` by default). It's generated code, and the first line says re-running init overwrites it.

The plugin subscribes to two events:

- **`session.created`**, for a new top-level session. Sessions with a parent are ignored, so a subagent's session doesn't turn into a separate handoff.
- **`session.idle`**, when the session finishes its work and waits for you.

On either, it spawns `adrive hook opencode` detached (or `npx -y @adrive/cli hook opencode` when `adrive` isn't on the PATH), writes the session id and directory to its stdin and moves on. It never waits for the process and never shows its errors. A slow or missing CLI can't hold OpenCode up.

There's no end-of-session event in this list, which is the reason for one rule that only OpenCode gets: `session.idle` always syncs. In the other agents, a turn-end event is limited to one sync every two minutes. Here, the first idle often arrives seconds after the session starts, and with that limit a short one-shot session could be uploaded empty.

## Where does sync read OpenCode sessions from? [#where-does-sync-read-opencode-sessions-from]

Not from files. OpenCode keeps sessions in its own store under `$XDG_DATA_HOME/opencode` (`~/.local/share/opencode` by default), so sync asks OpenCode for them with `opencode session list --format json` and `opencode export <id>`. Both run with `--pure`, which starts OpenCode without plugins, so AgentDrive's plugin doesn't fire while it's being read.

Two practical consequences. The `opencode` binary has to be on the PATH of whatever runs the sync, or OpenCode sessions don't appear and `sync.log` records the failure. And because the store is always there, local mode needs no plugin at all: `adrive resume` in another agent finds OpenCode sessions from before you installed AgentDrive. See [local mode](https://agentdrive.sh/blog/local-mode-no-account).

## How do I resume a Claude Code or Codex session in OpenCode? [#how-do-i-resume-a-claude-code-or-codex-session-in-opencode]

There's a command for it. In the same project:

```
/agentdrive-resume
```

`drive_resume` prefers the latest session in this project from an agent other than OpenCode. OpenCode receives the source session's goal, the files it touched and its last turns, and the command tells it to look at the current files before relying on the brief.

To pick a different session:

```
/agentdrive-sessions codex
/agentdrive-resume <session-id>
```

Both commands pass whatever follows them through `$ARGUMENTS`: an agent name filters, anything else is read as a project. Like the Codex and Cursor versions, they're prefixed `agentdrive-` to stay clear of OpenCode's built-in commands.

OpenCode sets `OPENCODE=1` on commands its shell tool runs. AgentDrive reads that, so when OpenCode runs `adrive resume` in local mode, OpenCode's own sessions are left out.

By source agent: [Claude Code to OpenCode](https://agentdrive.sh/resume/claude-code-to-opencode), [Codex to OpenCode](https://agentdrive.sh/resume/codex-to-opencode), [Cursor to OpenCode](https://agentdrive.sh/resume/cursor-to-opencode), [Antigravity to OpenCode](https://agentdrive.sh/resume/antigravity-to-opencode). [OpenCode, Codex and Claude Code on one task](https://agentdrive.sh/blog/opencode-codex-claude-code) is how I rotate the three.

### Why doesn't OpenCode list my other sessions when it starts? [#why-doesnt-opencode-list-my-other-sessions-when-it-starts]

The session-start hook in Claude Code, Codex, Cursor and Antigravity can hand the agent a short list of your recent sessions from other agents. OpenCode's plugin API has no way to inject that context, so OpenCode never gets it. Make `/agentdrive-sessions` your first command instead.

## My provider ran out. Switch model or switch agent? [#my-provider-ran-out-switch-model-or-switch-agent]

This is where OpenCode really parts ways with the rest. OpenCode doesn't run out; the provider behind it does. Its [providers docs](https://opencode.ai/docs/providers/) describe the setup: run `/connect`, choose a provider, enter its credentials, then pick a model with `/models`. The limits are that provider's. For example, the same page says that with a ChatGPT plan sign-in, "Usage counts against your plan", and that OpenCode Go, an optional subscription, documents its usage limits in the Go guide.

That gives you an option a single-vendor agent doesn't:

- **Switch model, stay in OpenCode.** If a second provider is connected, choose one of its models with `/models` and keep working. No handoff at all.
- **Wait or pay** on the provider that stopped, under its own terms.
- **Switch agent.** The idle event that fired when OpenCode stopped normally synced the session already, debounce or not. If you want to be certain, `adrive sync --force` in the project re-checks every agent without the two-minute wait. Then: [OpenCode to Claude Code](https://agentdrive.sh/resume/opencode-to-claude-code), [to Codex](https://agentdrive.sh/resume/opencode-to-codex), [to Cursor](https://agentdrive.sh/resume/opencode-to-cursor), [to Antigravity](https://agentdrive.sh/resume/opencode-to-antigravity).

If you land in an agent with its own plan, these help: [Claude Code](https://agentdrive.sh/blog/claude-code-usage-limit), [Codex](https://agentdrive.sh/blog/codex-usage-limit), [Cursor](https://agentdrive.sh/blog/cursor-usage-limit).

## Which files does init touch? [#which-files-does-init-touch]

All in `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`:

| File | Change |
|---|---|
| `opencode.json` | `mcp.agentdrive`: `type: "local"`, command `npx -y @adrive/mcp-server`, `environment` with `AGENTDRIVE_AGENT_PLATFORM=opencode`, `enabled: true`. Your original is kept as `opencode.json.bak` the first time. |
| `plugins/agentdrive.ts` | The plugin above. |
| `commands/agentdrive-resume.md`, `commands/agentdrive-sessions.md` | The two commands. |
| `skills/agentdrive/SKILL.md` | The AgentDrive skill. |
| `AGENTS.md` | With auto-context on (the default), a marked block telling OpenCode when to use the AgentDrive tools. |

If there's no `opencode.json` but there is an `opencode.jsonc`, init checks whether the `.jsonc` is plain JSON, which a fresh OpenCode writes. Plain JSON gets merged. A file with comments is left alone, with a warning to add the `agentdrive` entry yourself, because merging would drop the comments.

One more: OpenCode loads skills from `~/.claude/skills` as well, where CLI 1.0.0 put an AgentDrive skill. When init installs the Claude Code plugin, it deletes that old copy (only if it's a real folder whose frontmatter says `name: agentdrive`), so you don't see the skill twice.

## FAQ [#faq]

### Does the plugin slow OpenCode down? [#does-the-plugin-slow-opencode-down]

No. It spawns a detached process per event and returns without waiting.

### Does it matter which model a session used? [#does-it-matter-which-model-a-session-used]

Not to AgentDrive. The brief is built from the transcript, so a session run on one provider resumes the same way anywhere.

### OpenCode sessions aren't showing up. Why? [#opencode-sessions-arent-showing-up-why]

Check that `opencode` runs from a plain terminal, since sync shells out to it, then read `~/.config/agentdrive/sync.log`.

### Should I restart OpenCode after init? [#should-i-restart-opencode-after-init]

Yes, so it loads the new plugin and MCP server.

## Load the plugin [#load-the-plugin]

Run `adrive init`, restart OpenCode so it loads the plugin and MCP server, then type `/agentdrive-resume` in a project another agent worked in. With `--local`, init keeps everything on this machine. If nothing shows up, `~/.config/agentdrive/sync.log` is the first place to look.