Plugins
TUICommander has an Obsidian-style plugin system. Plugins can watch terminal output, push notifications to the Activity Center, render markdown panels, control PTY sessions, and more.
Installing Plugins
From the Community Registry
- Open Settings (
Cmd+,) → Plugins tab → Browse - Browse available plugins — each shows name, description, and author
- Click Install on any plugin
- The plugin is downloaded and activated immediately
An “Update available” badge appears when a newer version exists in the registry.
From a ZIP File
- Open Settings → Plugins → Installed
- Click Install from file…
- Select a
.ziparchive containing the plugin
Via Deep Link
Click a link like tuic://install-plugin?url=https://example.com/plugin.zip — TUICommander shows a confirmation dialog, then downloads and installs the plugin. Only HTTPS URLs are accepted.
Manual Installation
Copy the plugin directory to:
- macOS:
~/Library/Application Support/com.tuic.commander/plugins/my-plugin/ - Linux:
~/.config/tuicommander/plugins/my-plugin/ - Windows:
%APPDATA%/com.tuic.commander/plugins/my-plugin/
A plugin directory contains at minimum manifest.json and main.js.
Managing Plugins
Settings → Plugins → Installed
The Installed tab lists all plugins (built-in and external):
- Toggle switch — Enable or disable a plugin. Disabled plugins are not loaded but remain installed.
- Logs — Click to expand the plugin’s log viewer. Shows recent activity and errors (500-entry ring buffer).
- Uninstall — Remove the plugin directory (confirmation required). Built-in plugins cannot be uninstalled.
Error count badges appear on plugins that have logged errors.
Built-in Plugins
TUICommander ships with built-in plugins (e.g., Plan Tracker). These show a “Built-in” badge in the list. They can be disabled but not uninstalled.
How Plugins Work
Plugins interact with the app through a PluginHost API organized in 4 capability tiers:
| Tier | Access | Examples |
|---|---|---|
| 1 | Always available | Watch terminal output, add Activity Center items, provide markdown content |
| 2 | Always available | Read repository list, active branch, terminal sessions (read-only) |
| 3 | Requires capability | Send input to terminals (pty:write — raw writePty or agent-aware sendAgentInput), open markdown panels (ui:markdown), play sounds (ui:sound), read/list/watch files (fs:read, fs:list, fs:watch) |
| 4 | Requires capability | Invoke whitelisted Tauri commands (invoke:read_file, invoke:list_markdown_files) |
Capabilities are declared in the plugin’s manifest.json. A plugin without pty:write cannot send input to your terminals.
Activity Center
The toolbar bell icon is the Activity Center. Plugins contribute sections and items here:
- Sections — Grouped headings (e.g., “ACTIVE PLAN”, “CI STATUS”)
- Items — Individual notifications with icon, title, subtitle
- Actions — Click an item to open its detail (usually a markdown panel), or dismiss it
The bell shows a count badge when there are active items.
Hot Reload
When you edit a plugin’s files, TUICommander detects the change and automatically reloads the plugin — no restart needed. Save main.js and see changes in seconds.
Example Plugins
TUICommander ships with example plugins in examples/plugins/:
| Plugin | What it does |
|---|---|
hello-world | Minimal example — watches terminal output, adds Activity Center items |
auto-confirm | Auto-responds to Y/N prompts in terminal |
ci-notifier | Sound notifications and markdown panels for CI events |
repo-dashboard | Reads repo state, generates dynamic markdown summaries |
report-watcher | Watches terminal for generated report files, shows them in Activity Center |
Writing Your Own Plugin
See the Plugin Authoring Guide for the full API reference, manifest format, capability details, structured event types, and testing patterns.
Troubleshooting
| Problem | Fix |
|---|---|
| Plugin not appearing | Check that manifest.json exists and id matches the directory name |
| “Requires app version X.Y.Z” | Update TUICommander or lower minAppVersion in the manifest |
| “Requires capability X” | Add the capability to the capabilities array in manifest.json |
| Changes not taking effect | Save the file again to trigger hot reload, or restart the app |
| Plugin errors | Check Settings → Plugins → Logs for the plugin’s error log |