OpenCode + Obsidian: Build Your AI-Powered Knowledge Management Workflow

Thu, 30 Apr 2026 02:00:15 +0800

📋 Table of Contents

1. What is the opencode-obsidian Plugin?

opencode-obsidian is a third-party community plugin that embeds the OpenCode AI assistant directly into the Obsidian window. Unlike traditional terminal integration solutions, this plugin uses OpenCode’s Web view for direct embedding — what you see is the complete OpenCode interface, with no need to switch back and forth between terminal and Obsidian.

Core Features:

🖥️ OpenCode interface directly embedded in Obsidian sidebar or main editor
🔄 Automatic server management — starts when panel opens, stops when closed
📄 Experimental context injection — automatically passes current notes and selected text to AI
⌨️ Shortcut Ctrl/Cmd + Shift + O for quick panel toggle

Use Cases:

Summarizing and distilling long-form content
Drafting, editing, and polishing writing
Querying and exploring your knowledge base

Generating outlines and structured notes

⚠️ The plugin author is not affiliated with OpenCode or Obsidian — this is an independent third-party project. Current version is 0.2.1 (Beta stage), desktop only.

2. Environment Preparation

Before starting, ensure you have the following ready:

Item	Requirement	Notes
Obsidian	≥ 1.4.0	Download
Node.js	≥ 18+	Download, for OpenCode installation

Once ready, follow the steps below.

3. Installing the BRAT Plugin

BRAT (Beta Reviewer’s Auto-update Tool) is an Obsidian community plugin specifically for installing Beta plugins not yet listed in the community plugin marketplace. opencode-obsidian isn’t officially listed yet, so installation via BRAT is required.

Step 1: Open Community Plugin Marketplace

In Obsidian, click: Settings → Third-party plugins → Turn off “Safe mode” → Community plugin marketplace

Step 2: Search and Install BRAT

Search for BRAT (full name: Obsidian42 - BRAT) in the community marketplace, click “Install” → “Enable”.

💡 BRAT stands for Beta Reviewer’s Auto-update Tool, developed by TfTHacker. It automatically checks for Beta plugin updates and notifies you to upgrade.

4. Installing opencode-obsidian via BRAT

Once BRAT is installed, use it to install the opencode-obsidian plugin.

Step 1: Open BRAT Settings

Settings → Third-party plugins → Find installed BRAT, click the gear icon on the right to enter settings.

Step 2: Add Beta Plugin

In the BRAT settings page, click the “Add Beta plugin” button.

Step 3: Enter Repository Address

In the popup input box, enter:

`1`	`mtymek/opencode-obsidian`

Click “Add Plugin”.

BRAT will automatically pull the latest release version from GitHub and install it.

Step 4: Enable the Plugin

After installation, go to Settings → Third-party plugins → Find OpenCode-Obsidian in the “Installed plugins” list and toggle it on.

✅ Once enabled, a terminal-style icon appears in Obsidian’s left sidebar — this is the OpenCode entry point.

Auto-Update

BRAT periodically checks GitHub for new versions. When an update is available, it shows a notification in Obsidian — just click to confirm and auto-upgrade.

5. Installing OpenCode CLI

The plugin itself is just a “shell” — it starts opencode serve in the background and embeds OpenCode’s web interface into Obsidian. So you only need to install the OpenCode CLI via npm.

Open your system terminal (PowerShell for Windows, Terminal for macOS/Linux):

`1`	`npm i -g opencode-ai`

Verify installation:

1
2

opencode --version
# Expected output like: 1.14.39

⚠️ Windows users: If the plugin shows “Executable not found at ‘opencode’”, jump to Section 10 for the solution.

6. Plugin Settings Explained

After enabling the plugin, go to Settings → Third-party plugins → OpenCode-Obsidian gear icon to see these configuration options:

Basic Settings

Setting	Default	Description
OpenCode executable path	`opencode`	Enter full path if not found in system PATH
Port	`14096`	Port number the OpenCode service listens on
Hostname	`127.0.0.1`	Address the service binds to
Project directory	(Auto from Vault path)	Working directory for OpenCode
Startup timeout	`45000` (45s)	Max milliseconds to wait for service startup

Interface Settings

Setting	Default	Description
Default view position	`sidebar`	`sidebar` = sidebar, `main` = main editor area
Auto-start	`Off`	Auto-start OpenCode service when Obsidian opens

Context Injection (Experimental)

Setting	Default	Description
Inject workspace context	`Off`	Auto-pass current note info to OpenCode
Max notes	`20`	Maximum notes included in context
Max selection length	`2000`	Character limit for text passed to AI

Custom Commands

Setting	Default	Description
Use custom command	`Off`	Enable to customize OpenCode launch command
Custom command	(empty)	Custom launch command (see Section 9)

7. First Use

Opening the OpenCode Panel

Three ways to open OpenCode:

Click sidebar icon: Click the terminal icon in the left sidebar
Shortcut: Ctrl + Shift + O (macOS: Cmd + Shift + O)
Command palette: Ctrl/Cmd + P → type Toggle OpenCode panel

First Launch Flow

After opening the panel, the plugin automatically:

Detects the OpenCode executable path
Starts the OpenCode service (opencode serve)
Loads the OpenCode interface in an embedded web view

Once started, you’ll see the complete OpenCode dialog interface — type prompts directly.

Verify Everything Works

In the OpenCode interface, type:

/help

If you see the command list, everything is working. You can also type:

/models

to view available AI models. OpenCode has built-in free models (GLM-4.7, MiniMax-2.1) — no configuration needed.

Shortcut Reference

Shortcut	Function
`Ctrl/Cmd + Shift + O`	Toggle OpenCode panel

8. Context Injection (Experimental Feature)

This is one of the opencode-obsidian plugin’s most unique features — it can automatically pass Obsidian’s working context to OpenCode.

How to Enable

In plugin settings, toggle on “Inject workspace context”.

What Gets Injected

When enabled, the plugin automatically passes this information to the running OpenCode instance:

📂 Currently open notes list: Which files you’re editing
📝 Selected text: Text you’ve highlighted in notes

Use Cases

Select some text, open the OpenCode panel, say “polish this paragraph” — AI already knows which text you mean
Open multiple notes, ask AI “compare the differences between these two notes” — AI already knows which files are open

Limitations

⚠️ This is an experimental feature with some current limitations:

Context doesn’t auto-inject when creating a new Session in the OpenCode interface

Context updates have some latency

9. Custom Command Mode

By default, the plugin calls opencode serve to start the service. If you need more control, enable custom command mode.

When Do You Need Custom Commands?

Adding extra CLI arguments
Using custom startup scripts
Running OpenCode through containers or virtual environments
OpenCode installed in non-standard paths

Configuration Steps

In plugin settings, turn on “Use custom command”
Enter the complete command in the “Custom command” input field

Command Template

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

⚠️ Important Notes

Port and hostname must match the values in settings
Must include --cors app://obsidian.md — otherwise Obsidian cannot embed the OpenCode web interface

10. FAQ and Troubleshooting

❌ OpenCode Executable Not Found

Symptom: Panel shows “Executable not found at ‘opencode’”, but opencode works fine in terminal.

Cause: Electron (Obsidian’s underlying framework) doesn’t fully inherit system PATH environment variables on Windows.

Solution:

Find the full path of opencode.cmd in terminal:

`1`	`where opencode.cmd`

Paste the full path into the plugin setting “OpenCode executable path”, e.g.:

`1`	`C:\Users\YourUsername\AppData\Roaming\npm\opencode.cmd`

❌ Service Startup Timeout

Possible causes: Network issues, slow model loading, port in use.

Solution:

Check if port 14096 is occupied by another program
Try changing the port number (e.g., to 15096)

Increase the startup timeout

❌ Panel Shows Blank

Possible cause: CORS configuration incorrect.

Solution:

If using a custom command, ensure it includes --cors app://obsidian.md.

❌ Panel Cannot Embed

Possible cause: OpenCode version too old.

Solution:

`1`	`npm i -g opencode-ai@latest`

❌ Chinese Filename Garbled (Windows)

Solution: Run in PowerShell:

`1`	`chcp 65001`

Then restart Obsidian.

❌ Plugin Needs Reconfiguration After Update

BRAT preserves your settings data when updating. If settings are lost, just re-enter the settings page to reconfigure.

Summary

The entire installation flow in one diagram:

┌──────────────────────────────────────────┐
│         Install BRAT Plugin              │
│   Settings → Community marketplace       │
│   → Search BRAT → Install               │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│    Install opencode-obsidian via BRAT    │
│   BRAT Settings → Add Beta plugin        │
│   Enter: mtymek/opencode-obsidian        │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│         Install OpenCode CLI             │
│   npm i -g opencode-ai                  │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│       Enable plugin, start using         │
│   Ctrl+Shift+O to open panel             │
│   Use OpenCode directly in Obsidian      │
└──────────────────────────────────────────┘

One-line summary: Install BRAT → Search mtymek/opencode-obsidian → Install OpenCode CLI → Ctrl+Shift+O and you’re set. It’s that simple.

📚 Sources:

opencode-obsidian GitHub Repository

BRAT Plugin GitHub Repository

OpenCode Official Documentation

Knowledge Management on Yanmu

OpenCode + Obsidian: Build Your AI-Powered Knowledge Management Workflow

📋 Table of Contents

1. What is the opencode-obsidian Plugin?

2. Environment Preparation

3. Installing the BRAT Plugin

Step 1: Open Community Plugin Marketplace

Step 2: Search and Install BRAT

4. Installing opencode-obsidian via BRAT

Step 1: Open BRAT Settings

Step 2: Add Beta Plugin

Step 3: Enter Repository Address

Step 4: Enable the Plugin

Auto-Update

5. Installing OpenCode CLI

6. Plugin Settings Explained

Basic Settings

Interface Settings

Context Injection (Experimental)

Custom Commands

7. First Use

Opening the OpenCode Panel

First Launch Flow

Verify Everything Works

Shortcut Reference

8. Context Injection (Experimental Feature)

How to Enable

What Gets Injected

Use Cases

Limitations

9. Custom Command Mode

When Do You Need Custom Commands?

Configuration Steps

Command Template

⚠️ Important Notes

10. FAQ and Troubleshooting

❌ OpenCode Executable Not Found

❌ Service Startup Timeout

❌ Panel Shows Blank

❌ Panel Cannot Embed

❌ Chinese Filename Garbled (Windows)

❌ Plugin Needs Reconfiguration After Update

Summary