📋 Table of Contents

• 1. What is the opencode-obsidian Plugin?
• 2. Environment Preparation
• 3. Installing the BRAT Plugin
• 4. Installing opencode-obsidian via BRAT
• 5. Installing OpenCode CLI
• 6. Plugin Settings Explained
• 7. First Use
• 8. Context Injection (Experimental Feature)
• 9. Custom Command Mode
• 10. FAQ and Troubleshooting

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:

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

Interface Settings

Context Injection (Experimental)

Custom Commands

7. First Use

Opening the OpenCode Panel

Three ways to open OpenCode:

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

First Launch Flow

After opening the panel, the plugin automatically:

1. Detects the OpenCode executable path
2. Starts the OpenCode service (opencode serve)
3. 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:

1

/help

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

1

/models

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

Shortcut Reference

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

1. Select some text, open the OpenCode panel, say “polish this paragraph” — AI already knows which text you mean
2. 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

1. In plugin settings, turn on “Use custom command”
2. 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:

1. Find the full path of opencode.cmd in terminal:

1

where opencode.cmd

2. 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

┌──────────────────────────────────────────┐
│         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