Onyx Terminal Shell

An embedded terminal plugin for Obsidian — powered by Ghostty's VT parser and Canvas renderer via ghostty-web.

Open a fully functional terminal right inside your vault. Onyx Terminal Shell reads your native Ghostty configuration for theming, fonts, and shell settings — so your terminal in Obsidian looks and feels just like your standalone terminal.

Features

• Terminal in any pane — open terminals as tabs, in the sidebar, or in split views
• Ghostty config integration — automatically reads your ~/.config/ghostty/config for theme, font, cursor, and shell settings
• Dark/light theme support — respects Ghostty's dark:X,light:Y theme syntax and switches with Obsidian's appearance
• Multi-instance — run multiple terminal sessions simultaneously
• Open in file directory — launch a terminal pre-cd'd to the active file's folder
• Sidebar terminal — pin a terminal in the right sidebar for quick access

Requirements

• Obsidian Desktop 1.5.0 or later (not available on mobile)
• macOS or Linux (Windows support is experimental)
• Node.js toolchain for the initial native module build

Installation

Community Plugins (coming soon)

1. Open Settings → Community Plugins → Browse
2. Search for Onyx Terminal Shell
3. Click Install, then Enable

BRAT

1. Install the BRAT plugin
2. Add davidmat/onyx-shell as a beta plugin

Manual

1. Clone this repo into your vault's plugin directory:

   cd /path/to/vault/.obsidian/plugins
   git clone https://github.com/davidmat/onyx-shell.git
   

2. Follow the post-install steps below

Post-install (required)

The plugin uses node-pty for native PTY support, which must be compiled against Obsidian's Electron version:

cd /path/to/vault/.obsidian/plugins/onyx-shell
npm install
npm run rebuild:electron
npm run build

Then restart Obsidian and enable the plugin.

Configuration

All settings are optional — the plugin works out of the box with sensible defaults.

Setting	Description	Default
Ghostty config path	Path to your Ghostty config file	Auto-detected
Shell	Shell program to launch	Ghostty config → system default
Font family	Terminal font	Ghostty config → monospace
Font size	Font size in pixels	Ghostty config → 14
Cursor style	Block, underline, or bar	Ghostty config → block
Cursor blink	Enable cursor blinking	true
Scrollback lines	Lines of scrollback history	10000
Default working directory	Vault root, home, or active file's dir	Vault root

Configuration cascade

Settings resolve in this order: Plugin settings → Ghostty config → Built-in defaults

This means you can leave most plugin settings empty and they'll inherit from your Ghostty configuration.

Ghostty theming

The plugin reads color and font settings from your Ghostty config file. Supported keys:

Colors: foreground, background, cursor-color, cursor-text, selection-background, selection-foreground, palette (0–15)

Theme files: The theme key resolves named themes from Ghostty's theme directories:

• ~/.config/ghostty/themes/
• ~/Library/Application Support/com.mitchellh.ghostty/themes/ (macOS)
• Bundled themes in Ghostty.app

Dark/light mode: Use Ghostty's theme = dark:Catppuccin Frappe,light:Catppuccin Latte syntax — the plugin picks the right variant based on Obsidian's current appearance.

Commands

Command	Description
Open terminal	Open a new terminal tab
Open terminal in current file's directory	Terminal cd'd to the active file's folder
Open terminal in right sidebar	Pin a terminal in the right sidebar

Troubleshooting

"Failed to load node-pty"

The native node-pty module needs to be compiled for Obsidian's Electron version:

cd /path/to/vault/.obsidian/plugins/onyx-shell
npm run rebuild:electron

If you update Obsidian, you may need to re-run this command.

Electron version mismatch

The rebuild:electron script targets Electron 37.10.2. If Obsidian updates its Electron version, update the version in package.json:

"rebuild:electron": "npx @electron/rebuild -v <NEW_VERSION> -m ."

Development

git clone https://github.com/davidmat/onyx-shell.git
cd onyx-shell
npm install
npm run rebuild:electron
npm run dev

Then symlink the repo into your vault's plugin directory:

ln -s /path/to/onyx-shell /path/to/vault/.obsidian/plugins/onyx-shell

License

MIT