Alma Plugin Development Documentation

Welcome to the official documentation for developing plugins for Alma.

Quick Links

Document	Description
Getting Started	Create your first plugin
API Reference	Complete API documentation
Hooks & Events	React to application events
UI API Guide	Build user interfaces
Examples	Real-world plugin examples

Overview

Alma plugins extend the functionality of the AI assistant with custom tools, UI components, themes, and integrations. Plugins are written in TypeScript/JavaScript and have access to a rich set of APIs.

Plugin Types

Type	Description	Example Use Cases
tool	Register tools for the AI	Weather lookup, code execution, file operations
ui	Add UI components	Status bar items, sidebars, custom panels
theme	Provide color themes	Dark themes, brand colors
provider	Add AI providers	Custom model backends, local LLMs
transform	Transform data	Prompt enhancement, response formatting
composite	Multiple types	Full-featured integrations

Core Concepts

1. Activation: Plugins export an activate function that receives a PluginContext
2. Disposables: Resources must be cleaned up when the plugin deactivates
3. Hooks: Subscribe to lifecycle events to react to application state changes
4. Settings: Persist configuration across sessions

Minimal Example

import type { PluginContext, PluginActivation } from 'alma-plugin-api';

export async function activate(context: PluginContext): Promise<PluginActivation> {
    context.logger.info('Plugin activated!');

    return {
        dispose: () => {
            context.logger.info('Plugin deactivated');
        },
    };
}

Installation

For Users

Copy plugins to:

• macOS: ~/Library/Application Support/Alma/plugins/
• Windows: %APPDATA%/Alma/plugins/
• Linux: ~/.config/Alma/plugins/

For Developers

npm install alma-plugin-api

API Summary

API	Description
logger	Logging (info, warn, error, debug)
storage	Persistent key-value storage
tools	Register AI tools
commands	Register command palette commands
events	Subscribe to lifecycle hooks
ui	Notifications, dialogs, status bar
chat	Access threads and messages
providers	Manage AI providers
workspace	File system operations
settings	Read/write plugin settings
i18n	Internationalization

Available Hooks

Hook	Description
chat.message.willSend	Before sending a message
chat.message.didReceive	After receiving a response
thread.activated	When switching threads
tool.willExecute	Before tool execution
tool.didExecute	After tool completion
tool.onError	When a tool fails
app.ready	Application startup
app.willQuit	Before closing

Contributing

Plugins can be submitted to the Alma Plugin Registry for distribution through the marketplace.

Submission Requirements

1. Valid manifest.json with all required fields
2. Compiled JavaScript entry point
3. README with usage instructions
4. MIT or compatible license
5. No malicious code or security vulnerabilities

Resources

• Official Plugin Repository
• Plugin API Package
• Issue Tracker

License

MIT