# opencode-obsidian: running the OpenCode web view inside an Obsidian sidebar

> A third party Obsidian plugin that embeds the OpenCode agent web view rather than reimplementing a chat panel, with a custom command escape hatch and one unfinished feature.

**mtymek/opencode-obsidian** — Embed OpenCode AI assistant directly in Obsidian's sidebar.

- Repository: https://github.com/mtymek/opencode-obsidian
- Stars: 1,150 · Forks: 82
- Language: TypeScript
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/mtymek-opencode-obsidian

## What the plugin embeds, and what it deliberately does not build

Most Obsidian plugins that talk to a coding assistant implement their own chat interface. This one takes the opposite route: it starts OpenCode as a child process and embeds the web view that process already serves. The README is direct about why, saying the author wanted to find out how much was possible without implementing and then maintaining a custom chat UI. What you get is the agent's real interface, session list and all, inside the Obsidian window.

That decision shapes the whole plugin. There is no message schema to negotiate, no streaming protocol to keep in sync, and nothing to rebuild when OpenCode changes its interface. The cost is that you inherit OpenCode's interface decisions, including the ones you might not want in a narrow editor pane. The README also states plainly that the author is not affiliated with OpenCode or Obsidian, so treat it as third party software attached to two projects it does not control.

The stated use cases are summarizing long notes, drafting and refining writing, querying a knowledge base, and generating outlines. Note what is absent: there is no Obsidian-specific command palette, no vault indexer and no note-linking logic. The plugin gets you an agent in a sidebar. Everything you do with your notes is something you prompt for.

## BRAT for beta users, a clone path for developers

The plugin is distributed through BRAT, Obsidian's Beta Reviewer's Auto-update Tool, which is the normal channel for a plugin that has not been submitted to the community list. Install BRAT from Community Plugins, add `mtymek/opencode-obsidian` as a beta plugin, and BRAT pulls the newest release and checks for updates afterwards. You then enable the plugin in Obsidian settings.

The developer path clones the repository straight into your vault, which is the only way to run unreleased code:

```bash
git clone https://github.com/mtymek/opencode-obsidian.git .obsidian/plugins/obsidian-opencode
```

Then install dependencies and build:

```bash
bun install && bun run build
```

The plugin directory name in that clone path, `obsidian-opencode`, does not match the repository name, which trips up anyone scripting this. The package itself is named `obsidian-opencode` at version 0.2.1, and `manifest.json` at the repository root carries the version that Obsidian reads. The `version` npm script syncs the two, which is why the script list in `package.json` contains `bun run scripts/sync-manifest-version.ts` next to the patch, minor and major bump scripts.

There are three hard requirements: desktop only, because the plugin shells out to Node.js child processes; the OpenCode CLI installed; and Bun installed. The mobile app cannot run a child process, so this is a desktop-vault feature and nothing else.

## Custom command mode exists because the default serve line is not enough

Out of the box the plugin starts OpenCode itself, and the server comes up when you open the panel. Turn on the custom command setting and the plugin runs whatever string you give it instead. The README names three situations: adding extra CLI flags, routing OpenCode through a wrapper script, or running it inside a container or virtual environment.

The catch is specific enough that you will hit it. Hostname and port in your custom command have to match the port and hostname fields in the settings pane, and the command must include `--cors app://obsidian.md`, because that origin is what Obsidian loads the web view from. The README's own example is the shape most people need:

```bash
opencode serve --port 14096 --hostname 127.0.0.1 --cors app://obsidian.md
```

If either half of that contract is broken the failure is quiet. A mismatch on the origin means the embedded view refuses to load; a mismatch on the port means you are talking to nothing. Because the plugin does not validate the string, treat the settings fields as part of the command rather than as separate preferences.

Everything else in the settings pane is described as self explanatory: port, hostname, auto start, view location and context injection. That is thin documentation for five preferences, and the view location option in particular changes where in the Obsidian window the panel appears.

## Context injection is the feature to treat as unfinished

The plugin can push two things into the running OpenCode instance: the list of notes you have open, and the text you currently have selected. The README labels this work in progress and names a specific limitation: it does not work when you create a new session from the OpenCode interface itself.

That limitation is more interesting than it first appears. It means context flows into sessions the plugin started, and not into sessions you started inside the embedded view. If your habit is to open a fresh session per question, you are in the half that gets no injected context. Worth knowing before you build a workflow around it.

The interaction itself is otherwise minimal. Click the terminal icon in the ribbon, or press `Cmd/Ctrl+Shift+O` to toggle the panel. The server starts automatically on first open, so there is no separate start command to learn. The repository layout is small and readable: `src/` for the plugin logic, `tests/` for the test suite, `scripts/` for the version sync, `esbuild.config.mjs` for the bundler, and an `openspec/` directory that suggests the author specifies changes before writing them.

## Windows users hit a PATH problem the README does solve

The single most common Windows failure is an executable not found error for `opencode` even when OpenCode is installed. The cause is that Electron, which Obsidian is built on, does not fully inherit your PATH on Windows, so a command that works in your terminal does not resolve inside the plugin.

The fix is documented and takes two steps. Find the real path of the command shim:

```
where opencode.cmd
```

Then paste the absolute path into the plugin settings, in the form the README gives:

```
C:\Users\{username}\AppData\Roaming\npm\opencode.cmd
```

Note that this is a `.cmd` shim under the npm roaming directory, not the OpenCode executable itself. If your npm prefix lives somewhere else, the path will differ, and the README does not say how to discover the right one beyond that one lookup command.

Worth noting for a plugin this small: it is MIT licensed, and the last push was 2026-05-03 while the most recent tagged release, v0.2.1, dates from 2026-02-23. So the code on main has moved past the last packaged version. If you install through BRAT you are installing February code, and the fix set on main may not be in your Obsidian yet.

## Where this stops being a plugin and starts being OpenCode

The README is short because almost everything it does is OpenCode's job. There is no architecture section, no configuration reference beyond the settings pane, and no changelog. What the plugin adds is the child process launch, the embedded web view, the context injection hook and the settings UI.

That makes the adoption question different from most Obsidian plugins. You are not choosing a feature set, you are choosing whether you want OpenCode's own interface inside your editor. If you have already evaluated OpenCode and liked it, this is a thin convenience layer over it with a real cost saved: you keep one session history instead of two. If you have not, evaluate OpenCode on its own terms first, because this plugin cannot make an OpenCode configuration you dislike any better.

There is also a documentation path the README does not mention but the repository implies. The step `Add AGENTS.md to your workspace root to guide the AI assistant` tells you that OpenCode reads an agent instructions file from the workspace, and the plugin ships an `AGENTS.md` of its own at the repository root. Reading that file alongside the README is the fastest way to understand what the author expected OpenCode to be told before it touches your vault.

## Conclusion

Adopt this if you already run OpenCode from a terminal and want its session list, file diffs and mode switching inside Obsidian without writing a plugin yourself. Skip it if you need mobile sync, if you want the plugin to manage the OpenCode install for you, or if the experimental context injection is the whole point of your setup. The last push was 2026-05-03 and the newest release is v0.2.1 from 2026-02-23, so expect the plugin version and the code in main to be out of step. Verify first that `opencode serve` starts on its own, because everything else in this plugin hangs off that child process.

## FAQ

### Can Obsidian be used with OpenCode?

Yes, through this plugin, and only on desktop Obsidian. The plugin starts the OpenCode CLI as a Node.js child process and embeds the web view that process serves, so you need OpenCode and Bun installed locally. Obsidian on mobile cannot run child processes, so the plugin does not apply there.

### How do I install opencode-obsidian in Obsidian?

The README recommends BRAT. Install BRAT from Obsidian Community Plugins, choose Add Beta plugin, enter `mtymek/opencode-obsidian`, and let BRAT pull the latest release. Developers can instead clone the repository into `.obsidian/plugins/obsidian-opencode` under the vault root and run `bun install && bun run build`.

### Does opencode-obsidian work on mobile?

No. The plugin lists desktop only as a requirement because it relies on Node.js child processes, which the mobile app does not provide. That also rules out mobile vault sync, since the plugin never loads on the phone.

### Why does opencode-obsidian fail to find the opencode command on Windows?

Obsidian is built on Electron, which does not fully inherit your PATH on Windows, so the installed command does not resolve inside the plugin. Run `where opencode.cmd` to find the shim path and paste that absolute path into the plugin settings.

## Sources

- [Issues](https://github.com/mtymek/opencode-obsidian/issues)
- [License: MIT](https://github.com/mtymek/opencode-obsidian/blob/main/LICENSE)
- [mtymek/opencode-obsidian on GitHub](https://github.com/mtymek/opencode-obsidian)
- [README](https://github.com/mtymek/opencode-obsidian/blob/main/README.md)
- [Releases](https://github.com/mtymek/opencode-obsidian/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mtymek-opencode-obsidian