cinny-desktop/PLUGINS.md

Paarrot Plugin System

The Paarrot desktop client includes a powerful plugin system that allows you to extend and customize your Matrix experience.

What are Plugins?

Plugins are small JavaScript modules that run inside Paarrot and can:

• Add custom commands
• Modify the UI
• React to Matrix events
• Add new settings sections
• Enhance functionality

Installing Plugins

From the Plugin Marketplace

1. Open Settings → Plugins
2. Browse the Marketplace tab
3. Click Install on any plugin you want to add
4. The plugin will be downloaded and enabled automatically

Manual Installation

1. Download a plugin ZIP file
2. Extract it to your plugins directory:
   • Windows: %APPDATA%\paarrot\plugins\
   • Linux: ~/.config/Paarrot/plugins/
   • macOS: ~/Library/Application Support/Paarrot/plugins/
3. Restart Paarrot
4. Enable the plugin in Settings → Plugins → Installed

Managing Plugins

Viewing Installed Plugins

Go to Settings → Plugins → Installed to see all installed plugins.

Enabling/Disabling Plugins

Click the toggle switch next to any plugin to enable or disable it. Disabled plugins won't run or use resources.

Uninstalling Plugins

Click the Uninstall button next to any plugin to remove it completely.

Searching Plugins

Use the search bar to filter plugins by name, description, author, or tags.

Plugin Security

⚠️ Important Security Information

Plugins run with access to your Matrix client and can:

• Read your messages
• Send messages on your behalf
• Access your room list
• Modify app behavior

Only install plugins from trusted sources!

Safety Tips

1. Check the author: Install plugins from known developers
2. Read reviews: Look for community feedback
3. Review permissions: Understand what the plugin can do
4. Keep updated: Update plugins regularly for security fixes
5. Report issues: If a plugin behaves suspiciously, report it immediately

Developing Plugins

Want to create your own plugin? Check out the Plugin API Reference.

Quick Start

1. Create a plugin directory with:

   • index.js - Your plugin code
   • plugin-metadata.json - Plugin information

2. Implement the plugin interface:

module.exports = {
  onLoad: async (context) => {
    // Your plugin initialization
    console.log('Plugin loaded!');
  },
  onUnload: async () => {
    // Cleanup when disabled
  }
};

3. Test locally by copying to your plugins directory

4. Publish to the Plugin Directory

Plugin API

Plugins have access to:

• Matrix Client: Full matrix-js-sdk client instance
• React: For building UI components
• Commands: Register custom slash commands
• UI Buttons: Inject buttons into 11 locations across the app (nav lists, toolbars, headers, sidebar)
• UI Renderers: Custom message and content renderers
• Settings: Add custom settings sections per plugin
• Themes: Register custom themes that appear in the theme selector
• Matrix Events: Hook into raw Matrix events
• Timers: Background intervals and timeouts, auto-cleaned on unload
• Notifications: System notifications

See the Plugin API Reference and Button Registration API for complete documentation.

Example Plugins

Check out the example-plugin/ directory for a simple example, or the plugins/example-showcase-plugin/ for a full demonstration of all 11 UI button locations.

Troubleshooting

Plugin Won't Load

1. Check the browser console for errors (F12 → Console)
2. Look for [PluginLoader] messages
3. Verify index.js exists in the plugin directory
4. Ensure plugin-metadata.json is valid JSON

Plugin Crashes

1. Disable the plugin in Settings → Plugins
2. Check console for error stack traces
3. Report the issue to the plugin author
4. Try reinstalling the plugin

Performance Issues

If Paarrot becomes slow:

1. Disable plugins one by one to identify the culprit
2. Check for memory leaks in the console
3. Contact the plugin author with details

Plugin Directory

The official Paarrot Plugin Directory is maintained at: https://github.com/Paarrot/Plugin-Directory

Submit your plugins there to make them available in the marketplace!

Support

• Plugin API Reference: docs/PLUGIN_API.md
• Button API Reference: docs/PLUGIN_BUTTON_API.md
• Issues: https://github.com/Paarrot/cinny-desktop/issues
• Community: Join our Matrix room for plugin development help

License

Plugins are independent works and have their own licenses. Check each plugin's metadata for license information.