mirror of
https://github.com/sdkasper/lean-obsidian-terminal.git
synced 2026-07-22 14:30:31 +00:00
No description
a3cd16ea45
- Expand Windows PowerShell detection to include MS Store install path (%LOCALAPPDATA%\Microsoft\WindowsApps\pwsh.exe) in addition to standard installer path (%ProgramFiles%\PowerShell\7\pwsh.exe) - Add -ExecutionPolicy Bypass to PowerShell shell integration script invocation to bypass default Restricted policy without affecting system-wide settings - Add per-OS shell path settings (Windows/macOS/Linux) to allow cross-platform users to configure shell paths separately without reconfiguring when switching devices. Legacy shellPath field kept as fallback for existing users. - Add resolveShellPath() helper to pick platform-specific shell path at spawn time with graceful fallback to legacy shellPath value for backwards compatibility Fixes #74 Fixes cross-platform shell configuration issues reported in community feedback Co-Authored-By: Claude |
||
|---|---|---|
| .github | ||
| .planning/phases/02-code-review-lineHeight | ||
| __mocks__ | ||
| arm64-prebuilds/win32-arm64 | ||
| 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 Obsidian Community Plugins (recommended)
- Open Settings > Community Plugins
- Search for "Lean Terminal"
- Click Install
- 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
Or install directly: community.obsidian.md/plugins/lean-terminal
Troubleshooting Binary Download (ARM64 Windows)
If you see "Failed to download binaries" on an ARM64 Windows device (Surface Pro X, Windows Dev Kit, etc.):
- Close all terminal tabs in Obsidian (the binary may be locked in use)
- Disable the plugin in Settings, then re-enable it
- Restart Obsidian completely (not just reload)
- Manually delete the plugin's
node_modulesfolder: browse to.obsidian/plugins/lean-terminal/node_modules/in your vault and delete it - Try downloading binaries again
If the issue persists, check that:
- You have write permissions to the plugin directory
- Your
.obsidianfolder is not synced to a cloud service (OneDrive, iCloud, Dropbox) that may lock files during sync - Your antivirus software is not blocking file extraction
Via BRAT (beta releases)
- 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
- Download binaries and enable as above
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