# Obsidian OpenCode A plugin that embeds the OpenCode CLI directly into Obsidian. Browse conversation history and resume work without leaving your vault. ## Demo Work with vault notes and OpenCode side by side: ![A waterfall-model note open beside an OpenCode conversation in Obsidian](docs/assets/obsidian-opencode-side-by-side.png) Use OpenCode 2's multi-session interface in a full Obsidian editor tab: ![OpenCode 2 showing vertical session tabs inside Obsidian](docs/assets/obsidian-opencode-v2-sessions.png) ## Features - **Native OpenCode Execution:** Runs the OpenCode CLI directly inside Obsidian using an integrated terminal, ensuring smooth performance for long sessions. - **Vault-Centric Workflow:** Automatically spawns the agent in your vault's root, ensuring it has immediate access to your notes and project files. - **Drag and Drop Context:** Drop notes or folders from Obsidian's file explorer into the terminal. Notes become file line references. Folders paste their vault-relative path as plain text with a trailing slash, such as `extracurricular/ACG/anime/`, including names with spaces or Unicode and mixed selections. Nothing is submitted automatically. - **Session Manager:** - **History Browser:** View a list of all your past OpenCode sessions with timestamps. - **Conversation Preview:** Inspect message history, token usage and model details. - **One-Click Restore:** Instantly resume a previous session in the embedded terminal. - **Export to Markdown:** Save entire conversation threads as formatted notes in your vault for documentation or review. ## Platform Support - **Linux**: stable on my daily driver, not tested on all distros. - **WSL2/X410**: Supported with the Linux Obsidian app and formal OpenCode V2. Text copy/paste, OSC 52, Windows clipboard image paste, and copying rendered terminal images use a Unicode-safe Windows PowerShell bridge. WSLg is outside this support contract. - **Windows**: Beta support on Windows 10 version 1809 and later through ConPTY. Node.js must be available on `PATH` for the isolated PTY helper. - **macOS**: Experimental. ## Known Issues - **Empty external-editor prompts are not applied:** In both OpenCode 1 and OpenCode V2, opening the prompt in an external editor, deleting all content, and saving leaves the previous prompt in place. This also reproduces when OpenCode runs outside Obsidian, so it must be fixed upstream. - **OpenCode V2 can time out while pasting large images:** This reproduces in both the embedded terminal and standalone OpenCode V2, so it is not caused by the plugin. A V2 preview build configured clipboard reads with a 1-second timeout and an 8 MiB read limit; a 54.5 MB, 2720 x 18447 PNG reports `Clipboard read timed out`. Its separate local-file attachment limit is 20 MiB, so attaching that same file by path is also unsupported. OpenCode 1.4.6 on Linux reads image data through `wl-paste` without those explicit clipboard limits, so the large image may work there, but that comparison has not yet been verified manually. - **large session preview:** While the buffer size for exporting sessions has been increased (up to 100MB), exceptionally large or deeply complex OpenCode sessions with massive token counts may still occasionally fail to preview or load properly. - **not tested on all Linux distros:** While the plugin should work on major distros, it's only tested on manjaro, ubuntu, and fedora. - **Experimental Windows pty:** It's usable but far from linux and macos experience. - **shortcuts conflicts:**: Default opencode shortcuts like `Ctrl+P` could conflict with obsidian shortcuts. A solution for now is to always use leader key for opencode shortcuts. ## Integrations ### LaTeX render OpenCode CLI doesn't support LaTeX render natively. I made this opencode plugin for myself: [opencode-latex](https://github.com/kriss-spy/opencode-latex) Screenshot_20260919_172121 ### Obsidian Personally, i use kepano's [obsidian skills](https://github.com/kepano/obsidian-skills) and some of my [obsidian skills](https://github.com/kriss-spy/obsidian-skills). Any other general community project (MCP, skill, framework...) that connects coding agents with obsidian should work out of the box, as long as it doesn't specify the main interface. ### Templates I've always wanted a natural way to let opencode discover and use folder templates. [Templater](https://github.com/silentvoid13/Templater) doesn't do that out of the box. So i made [frontmatter-templater](https://github.com/kriss-spy/frontmatter-templater) to let you define folder template in folder note. In that way opencode should naturally discover and use the template when exploring a folder. ## Installation ### From Obsidian Community Plugins (Recommended) 1. Open Obsidian and go to **Settings** → **Community plugins** 2. Click **Browse** and search for **OpenCode** 3. Click **Install**, then **Enable** ### Manual Installation 1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/kriss-spy/obsidian-opencode/releases/latest) 2. Create a folder named `opencode` in your vault's `.obsidian/plugins/` directory 3. Copy the downloaded files into that folder 4. Reload Obsidian and enable the **OpenCode** plugin in Community Plugins settings ## Usage - **Terminal:** Use the command palette (`Ctrl/Cmd + P`) and select **"OpenCode: Open Terminal"** to launch the CLI. - **Line references:** With a Markdown note active and the embedded terminal running, select **"OpenCode: Add active line or selection to terminal"**. It adds the cursor's line, or the lines in the primary selection, to the current terminal draft without submitting it. A selection ending at the start of a line excludes that line. The private editor bridge creates a file attachment when connected; otherwise, confirm the `@path#5-9` suggestion in OpenCode. Paths containing spaces use a quoted text reference if the bridge is unavailable. Open or restart the terminal first if it is closed or its process has exited. Assign a hotkey in Obsidian settings if desired. - **Sessions View:** Use the command palette to select **"OpenCode: Open conversations"** to browse, restore, or export past conversations, or start a new session from the panel header. - **Ctrl+Z:** The default OpenCode suspend shortcut is blocked in the embedded terminal because there is no shell to resume it. A notice explains how to close or restart the terminal. If your OpenCode keymap disables `terminal_suspend` and uses Ctrl+Z for undo, that binding remains available. - **Close terminal:** Run **"OpenCode: Close terminal"** or press `Ctrl+Shift+W`. The shortcut can be changed in Obsidian's Hotkeys settings. - **Terminal links:** Click a web URL or Markdown note path in terminal output to open it. When OpenCode owns mouse input, hold `Ctrl/Cmd` while clicking. Note links support `:line:column` locations and Obsidian's modifier behavior for new tabs and splits. See [terminal links](docs/terminal-links.md) for supported path forms. - **Settings:** Leave the OpenCode path empty to auto-detect a compatible OpenCode installation, or configure `opencode`, `opencode2`, a `~/…` path, or a full executable path. Bare executable names are resolved from `PATH`, common user-local directories, and NVM installations: nvm-sh version directories on Unix, or the active `NVM_SYMLINK` and installed versions under `NVM_HOME` on Windows. Shell aliases are not executable paths and cannot be launched directly. Default CLI arguments, per-vault environment variables, and terminal styling preferences are available in the Obsidian settings under the "OpenCode" tab. - **WSL2 clipboard:** With Linux Obsidian displayed through X410, selecting text uses OpenCode's default copy-on-select behavior, and the plugin forwards its OSC 52 copy to Windows. For manual copy, set `terminal.copy` to `"manual"` in OpenCode V2's TUI config (`cli.json` in 2.0.1 or `tui.json` in newer builds); the legacy `OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=1` environment flag is also recognized for older OpenCode releases. In manual mode, `Ctrl+C` copies an active terminal selection through the Windows bridge; without a selection it remains an OpenCode interrupt. `Ctrl+V` prefers a Windows clipboard image and otherwise pastes Unicode text. Right-click a rendered terminal image to copy it to the Windows clipboard. PowerShell interop errors appear as Obsidian notices. ## Development Development requires Node.js 22.12 or newer. To develop the plugin, you can run the development script which automatically rebuilds the plugin when files change: ```bash npm run dev ``` Unit tests run with `npm test`. To create a fresh isolated vault and test the built plugin inside a sandboxed Obsidian instance, run: ```bash npm run test:obsidian ``` Use `npm run test:obsidian:smoke` for the smaller baseline suite. Windows contributors can also run `npm run test:obsidian:windows-ui` to exercise the installed OpenCode CLI and native terminal interactions. See [Testing in Obsidian](docs/testing-obsidian.md) for setup, coverage, evidence, and limitations. ## Acknowledgements - **Terminal integration approach** inspired by [polyipseity/obsidian-terminal](https://github.com/polyipseity/obsidian-terminal) — the Python PTY proxy with `pty.fork()` and 4-pipe stdio for resize control (FD 3). ## License MIT License