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:

Use OpenCode 2's multi-session interface in a full Obsidian editor tab:

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

Obsidian

Personally, i use kepano's obsidian skills and some of my 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 doesn't do that out of the box. So i made 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
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 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:

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:

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 for setup, coverage, evidence, and limitations.

Acknowledgements

• Terminal integration approach inspired by polyipseity/obsidian-terminal — the Python PTY proxy with pty.fork() and 4-pipe stdio for resize control (FD 3).

License

MIT License