Ghostty Terminal for Obsidian

An embedded terminal plugin for Obsidian that uses ghostty-web - Ghostty's native terminal engine compiled to WASM - providing a high-quality terminal experience directly in your Obsidian sidebar.

🤔 Why

Have you ever wanted a terminal right inside Obsidian without switching windows? This plugin embeds a fully functional terminal in your Obsidian workspace, powered by Ghostty's native parser and rendering engine.

Why Ghostty?

• Native Quality: Uses Ghostty's actual terminal parser (compiled to WASM)
• Better Unicode: Superior handling of Devanagari, Arabic, CJK, and complex scripts
• Lightweight: Only 400KB WASM bundle with zero runtime dependencies
• Modern: Built-in FitAddon and two-pass Canvas rendering

🎨 Features

• Ghostty Terminal Engine: Uses ghostty-web (Ghostty compiled to WASM)
• Full Shell Support: Works with bash, zsh, fish, PowerShell, and custom shells
• Obsidian Theme Integration: Automatic color syncing with your Obsidian theme
• URL Support: Clickable URLs with Cmd/Ctrl+Click to open in browser
• Shell Persistence: Session survives when terminal is toggled off/on
• Auto-Close: Terminal closes automatically when shell exits
• Responsive: Auto-resizes with window and sidebar changes
• Customizable: Font family, font size, cursor style, and appearance
• Startup Commands: Execute commands automatically on terminal open
• Shell Arguments: Pass custom arguments to your shell
• Keyboard Support: Full terminal keyboard navigation
• Desktop-Only: Requires native node-pty bindings (macOS, Linux, Windows)
• Clean Resource Management: Proper PTY cleanup on close

💡 What You Can Do

• Work from your vault - Terminal starts in vault root by default, perfect for vault operations
• Run git commands for vault version control without leaving Obsidian
• Execute build scripts and watch output in real-time
• Browse vault files with terminal tools (ls, cd, find, grep, etc.)
• Create/edit notes using command-line tools (vim, nano, etc.)
• Run quick scripts and commands with startup commands
• Keep a persistent shell session - toggle terminal off/on without losing your session
• Click URLs in terminal output to open them in your browser
• Run interactive programs like vim, htop, or top
• Terminal auto-closes when you type exit - clean and simple

🚀 Usage

Opening the Terminal

Three ways to open the terminal:

1. Ribbon Icon: Click the terminal icon in the left sidebar
2. Command Palette: Search for "Open terminal"
3. Keyboard: Assign a hotkey to "Open terminal" command

The terminal opens in the right sidebar by default.

Keyboard Shortcuts & Interactions

• All standard terminal keybindings work: Ctrl+C, Ctrl+D, Ctrl+Z, etc.
• Cmd/Ctrl+Click URLs: Open links in your default browser
• Resize: Drag the sidebar to adjust terminal size
• Toggle terminal: Close/open without losing your shell session

Settings

Configure the terminal in Settings → Ghostty Terminal:

Shell Configuration

• Shell Path: Custom shell executable (empty = system default)
• Shell Arguments: Additional arguments to pass to the shell
• Startup Command: Command to execute when terminal opens
• Working Directory: Choose starting directory (vault root, home, or custom path)

Appearance

• Font Family: Terminal font (default: monospace)
• Font Size: 8-24px (default: 14px)
• Sync with Obsidian Theme: Automatically match terminal colors to your Obsidian theme

Cursor

• Cursor Style: Choose from block, underline, or bar
• Cursor Blink: Enable or disable cursor blinking

Actions

• Reset to Defaults: Restore all settings to their default values

📋 Requirements

• Platform: Desktop only (macOS, Linux, Windows)
• Obsidian: Version 1.4.0 or higher
• Node: node-pty requires native compilation

Platform Compatibility

Platform	Status	Notes
macOS	✅ Tested	Fully working
Linux	⚠️ Untested	Should work (node-pty supports Linux)
Windows	⚠️ Untested	Should work (node-pty supports Windows)

😎 How to Install

[!WARNING] This plugin is in alpha stage. It may not work properly and compatibility with future versions is not guaranteed.

Please report bugs or suggestions on GitHub Issues.

Install Manually

1. Navigate to the Releases page
2. Download main.js, manifest.json, styles.css, and ghostty-vt.wasm from the latest release
3. Open your vault's .obsidian/plugins directory
4. Create a new directory: obsidian-ghostty-terminal
5. Move the downloaded files into the new directory

Directory structure:

.obsidian/plugins/obsidian-ghostty-terminal/
├── main.js
├── manifest.json
├── styles.css
└── ghostty-vt.wasm

6. Enable "Ghostty Terminal" in Settings → Community Plugins

⏳ Roadmap

Multiple Terminal Support

• Track multiple terminal instances
• Tab interface for switching between terminals
• Unique shells per terminal instance
• Split pane support

Session Persistence

• Save terminal buffer on close
• Restore terminal state on reopen
• Preserve command history across sessions
• Workspace-specific terminal states

Enhanced Features

• Custom keybindings configuration
• Right-click context menu (copy/paste/clear)
• Search in terminal buffer
• Terminal recordings/playback
• Custom color schemes beyond Obsidian theme
• Terminal profiles with different shell/settings
• Drag-and-drop file paths into terminal

Platform Features (when ghostty-web adds support)

• Mouse support
• RTL language support

💻 Development

Setup

1. Create a development vault
2. Install hot-reload plugin (optional)
3. Clone into .obsidian/plugins/obsidian-ghostty-terminal
4. Install dependencies:

pnpm install

5. Build:

pnpm run build

6. Reload Obsidian (Command Palette → "Reload app without saving")

Build Commands

• pnpm run build - Build for production
• pnpm run typecheck - Run TypeScript type checking
• pnpm run lint - Lint code
• pnpm run lint:fix - Fix linting issues

Testing

See TESTING.md for comprehensive testing checklist covering terminal UI, shell integration, theme integration, and cross-platform compatibility.

Architecture

Terminal View (terminal-view.ts)
  ├─ ghostty-web (WASM terminal engine)
  │   ├─ Terminal class (rendering)
  │   └─ FitAddon (responsive sizing)
  └─ PTY Manager (pty-manager.ts)
      └─ node-pty (shell process)

🙏 Credits

• Ghostty: ghostty.org | GitHub - Mitchell Hashimoto's amazing terminal emulator
• ghostty-web: coder/ghostty-web - Coder's WASM port
• node-pty: microsoft/node-pty - PTY bindings

📄 License

MIT License - See LICENSE file

---

Built with ❤️ using Ghostty's native terminal engine