Terminal Agent Tabs for Obsidian

An Obsidian plugin that lets you run multiple agent CLI sessions (Claude Code, Codex, Gemini CLI, etc.) as tabs within Obsidian.

Platform support: only macOS is actively tested and supported. The plugin relies on a POSIX PTY (os.openpty / fcntl) provided by the bundled pty-helper.py, so Windows is not supported and will not work. Linux may work in principle since the PTY APIs exist, but it has not been verified — use at your own risk and please report results.

Features

• Multiple Sessions: Run multiple CLI sessions in parallel as Obsidian tabs
• Configurable CLI Profiles: Add profiles for any agent CLI (Claude Code, Codex, Gemini, Grok, etc.)
• Session Sidebar: Overview of all sessions with status, notifications, and quick navigation
• Per-Tab Font Size: Adjust font size independently for each tab (Ctrl/Cmd +/-)
• Send Selection: Send selected text from your notes to the active session
• Dynamic Titles: Tab titles auto-update based on terminal output (OSC sequences)
• Session Resume: Resume previous sessions from termination screen or tab menu
• Split Views: Split session tabs horizontally or vertically
• Hook Notifications: Watch a JSONL event file and show notices for hook events (permissions, errors, task completion)
• Notification Sound: Optional audible alerts for hook events
• Dock Badge: macOS dock badge shows notification count
• Ghostty Themes: Load terminal color themes from Ghostty config
• OSC 52 Clipboard: Sync terminal clipboard events to system clipboard

Requirements

• Obsidian Desktop 1.0.0+
• macOS (primary supported platform)
• At least one CLI available locally (default profile uses claude)

Installation

From the Obsidian community directory (recommended)

1. Open Settings → Community plugins → Browse
2. Search for Terminal Agent Tabs and install
3. Enable the plugin

The Python helper scripts that drive the PTY are bundled inside main.js and extracted automatically to <plugin>/resources/ on first load — no manual setup is required.

Note on 1.0.0 and 1.0.1: those releases shipped pty-helper.py and hook-relay.py as separate files in the GitHub release. Because the Obsidian community installer only ships main.js / manifest.json / styles.css, users installing through the directory ended up without these helpers and sessions never started. 1.0.2 fixes this by embedding the helpers in main.js and writing them to disk at startup. If you were affected, just update to 1.0.2 — the missing files are restored automatically.

From GitHub Release

1. Go to the latest release
2. Download main.js, manifest.json, styles.css
3. Place them in <vault>/.obsidian/plugins/terminal-agent-tabs/
4. Reload Obsidian and enable the plugin in Settings → Community plugins

From Source

1. Clone this repository
2. Run npm install && npm run build
3. Copy main.js, manifest.json, styles.css to <vault>/.obsidian/plugins/terminal-agent-tabs/
4. Reload Obsidian and enable the plugin in Settings → Community plugins

Commands

Command	Description
New session tab	Open a new session with the default CLI
New session tab (choose target)	Open a new session after selecting a CLI profile
Send selection to current session	Send selected text to the active session
Toggle session sidebar	Show/hide the session sidebar
Focus active session	Jump to the last active session tab
Focus next / previous session	Cycle through session tabs
Split session (horizontal / vertical)	Split the current session view
Increase / decrease / reset font size	Adjust font size in the current tab

Settings

CLI Profiles

Configure one or more CLI profiles with custom executable paths, default arguments, and resume support.

Relative executable names (e.g. claude) are resolved through your login shell ($SHELL -l -i), so binaries installed via Homebrew, nvm, asdf, mise, npm-global, etc. are reachable even when Obsidian is launched from the macOS dock. If you prefer to skip shell resolution, enter an absolute path instead.

Terminal Appearance

• Color theme (Ghostty themes supported)
• Font size and font family
• Custom block glyphs toggle
• OSC 52 clipboard sync

Hook Notifications

Monitor a JSONL file for agent hook events and display notifications.

1. Enable Agent Hook Notifications in plugin settings
2. Optionally enable Play notification sound
3. Set Hook events file path (or leave empty for default)
4. Append JSON objects from your CLI hook script:

{"event":"stop","source":"claude","message":"Task finished"}

Send Selection Options

• Wrap selection in code block
• Include note file path

Development

npm install
npm run dev    # Watch mode
npm run build  # Production build

License

MIT