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.
Registry plugins include file viewers such as DOCX Preview, which opens Word .docx/.dotx files from the File Browser as an HTML preview tab; XLSX Preview, which opens Excel and OpenDocument spreadsheets as sortable tables; and SQLite Viewer, which browses schema and indexes, filters and paginates rows, explains read-only queries, copies CSV, and explicitly edits primary-key tables for .db, .sqlite, .sqlite3, .db3, and .s3db files. SQLite Viewer bundles its JavaScript and WebAssembly engine, makes no CDN request, and releases its live database engine when the viewer tab closes. Stock sql.js cannot open SQLCipher-encrypted databases; the viewer reports that case instead of prompting for an unusable key.
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 installed plugins:
- 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).
Error count badges appear on plugins that have logged errors.
Preinstalled External Plugins
Plan Tracker and Stories Ticker are ordinary external plugins. TUICommander installs them once when upgrading from the compiled-in implementations, after which they can be disabled, uninstalled, or updated like any other plugin. An explicit uninstall is permanent; later launches do not recreate the plugin.
External plugins load in the desktop app. Browser/PWA mode does not execute locally installed plugin code, so these two integrations are unavailable there.
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 |