mirror of
https://github.com/sdkasper/lean-obsidian-terminal.git
synced 2026-07-22 14:30:31 +00:00
No description
7db8ab0cc4
* fix: address CSS lint and source code warnings for plugin submission - binary-manager.ts: remove redundant non-null assertion on version (already narrowed) - styles.css: expand 3-digit hex to 6-digit (#000 -> #000000, #FFF -> #ffffff) - styles.css: split text-decoration shorthand into text-decoration-line + text-decoration-style for better browser compatibility - styles.css: remove !important by increasing selector specificity (.xterm .xterm-dim) and relying on already-higher specificity for .view-content overrides - bump to 0.16.3 Co-Authored-By: Claude <noreply@anthropic.com> * docs: explain extra release files in release.yml and README node-pty zips and checksums.json are fetched on-demand by BinaryManager when the user clicks "Download binaries" in plugin settings. Obsidian itself only installs main.js, manifest.json, and styles.css. Co-Authored-By: Claude <noreply@anthropic.com> * fix: replace text-decoration sub-properties with shorthand (0.16.4) Obsidian CSS scanner flags text-decoration-line and text-decoration-style as partially supported browser features. Replace all four xterm-underline variants (2-5) with plain text-decoration: underline to pass the check. Style variants degrade to normal underline visually. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|---|---|---|
| .github | ||
| .planning/phases/02-code-review-lineHeight | ||
| __mocks__ | ||
| docs | ||
| patches | ||
| scripts | ||
| src | ||
| .gitignore | ||
| .npmrc | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| esbuild.config.mjs | ||
| install.mjs | ||
| LICENSE | ||
| manifest.json | ||
| NOTICE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| styles.css | ||
| tsconfig.json | ||
| versions.json | ||
| vitest.config.ts | ||
Lean Terminal
An embedded terminal panel for Obsidian, powered by xterm.js and node-pty. Run shell commands directly inside your vault workspace - no external windows needed.
Desktop only. Requires Obsidian 1.5.0+.
Features
Terminal Core
- Full PTY terminal (not a simple command runner) with interactive shell support
- Auto-detects your shell: PowerShell 7 / Windows PowerShell / cmd.exe on Windows,
$SHELLon macOS/Linux - Startup command: configure a command that runs automatically in every new tab once the shell is ready (e.g.
claude,npm run dev) - Clipboard support: Ctrl+V / Cmd+V paste, Ctrl+C / Cmd+C copy (with selection)
- Clickable URLs in terminal output
- Auto-resize as the panel resizes
- Shift+Enter inserts a newline without submitting (muscle memory for Claude Code users)
Tab Management
- Multiple tabs with rename, color-coding, and pinning support
- Drag tabs to reorder them in the tab bar
- Keyboard shortcuts: Next/Previous (with wrap-around), Jump to Tab 1-8, Jump to last - bindable under Settings > Hotkeys
- Tab bar positioning: Top (default), Left, or Right side for wide-monitor layouts
Vault Integration
- Opens in vault root by default; command palette to open in the current file's folder; right-click any file or folder to open a terminal there
- Drag files from the Obsidian file explorer or Windows Explorer into the terminal to insert the absolute path (spaces auto-quoted)
- Wiki-link autocomplete: type
[[in the terminal to pick any vault note and insert as a wiki-link, vault-relative path, or absolute path
Search & Selection
- In-terminal search bar (Ctrl+Alt+F): match counter, case-sensitive toggle, and highlight decorations
- Copy on select: automatically copies selected text to the clipboard as you highlight
Appearance & Configuration
- 12 built-in color themes (Obsidian Dark, Obsidian Light, Monokai, Solarized Dark, and more); extend or override via themes.json
- Custom background color override with color picker (match your vault theme)
- Customizable ribbon and panel tab icon (any Lucide icon name)
- Configurable: shell path, font size, font family, cursor blink, scrollback, panel location
Sessions & Persistence
- Session persistence: tab names, colors, working directories, and scrollback are restored when Obsidian reopens
- Rescue recently closed tabs from the command palette (ring buffer of the last 10 sessions)
- Notification sounds when background tab commands finish (4 sound types, adjustable volume)
- Optional Claude Code integration: auto-maintained session registry with clickable Resume links and URI handler
Installation
Via BRAT (recommended)
- Install the BRAT plugin if you don't have it
- Open Settings > BRAT > Add Beta Plugin
- Enter:
sdkasper/lean-obsidian-terminal - Enable the plugin in Settings > Community Plugins
- Go to Settings > Terminal > Download binaries and click Download - this fetches the native terminal binary for your platform (the platform-specific
node-ptyzip from the GitHub release; Obsidian itself only usesmain.js,manifest.json, andstyles.css) - Open the terminal via the ribbon icon or command palette
Manual Installation
- Clone this repository
- Run
npm install && npm run build - Run
node install.mjs "/path/to/your/vault" - Restart Obsidian and enable the plugin in Settings > Community Plugins
How It Works
The plugin uses xterm.js for terminal rendering and node-pty for native pseudo-terminal support. node-pty spawns a real shell process (PowerShell, bash, etc.) and connects its stdin/stdout to xterm.js via Obsidian's Electron runtime. This gives you a fully interactive terminal - not just command execution.
On Windows, the plugin uses the ConPTY backend (correct UTF-8 and emoji support). A patched windowsConoutConnection.js replaces node-pty's Worker thread with inline socket piping so ConPTY works inside Obsidian's Electron renderer, which does not support Worker thread construction.
Related documents
See Usage for the full command reference.
See Settings for all configuration options.
See Session Persistence for how tab state is saved and restored.
See Claude Code Integration for setup and usage.
See URI Handler for the obsidian://lean-terminal protocol reference.
See Security for the security review summary.
Changelog
See CHANGELOG.md for release history and feature documentation by version.
Feedback
Use this repo to report bugs, request features, or ask questions.
If you want to support my work, you can use this link to buy me a drink - thank you, I appreciate you.
Development
npm install
npm run dev # Watch mode (auto-rebuild on save)
npm run build # Production build
node install.mjs # Install to default vault (D:\LOS Test)
Contributors
This plugin is built and maintained by a dedicated community. Special thanks to:
- @FarhadGSRX - Session persistence, session rescue buffer, Claude Code integration with registry generation and resume links, color scheme catalog with themes.json support
- @ckelsoe - Per-tab color tint customization with editable palette, wiki-link autocomplete with path-insertion modes
- @c00llin - Terminal location options (Tab Right, Split Tab Right)
- @kkugot - Emoji rendering fixes, system theme detection with terminal color reporting protocol
- @CHodder5 - Zsh startup file forwarding (.zshenv and .zprofile) via ZDOTDIR override