Getting Started with Alma Plugin Development

This guide will walk you through creating your first Alma plugin from scratch.

Prerequisites

• Node.js 18 or later
• TypeScript knowledge (recommended)
• Alma installed on your system

Quick Start

1. Create Plugin Directory

Create a new directory for your plugin:

mkdir my-first-plugin
cd my-first-plugin

2. Initialize the Project

npm init -y
npm install -D typescript zod
npm install alma-plugin-api

Create a tsconfig.json:

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "esModuleInterop": true,
        "strict": true,
        "outDir": "./dist",
        "declaration": true,
        "skipLibCheck": true
    },
    "include": ["*.ts"],
    "exclude": ["node_modules"]
}

3. Create the Manifest

Create manifest.json:

{
    "id": "my-first-plugin",
    "name": "My First Plugin",
    "version": "1.0.0",
    "description": "My first Alma plugin",
    "author": {
        "name": "Your Name"
    },
    "main": "main.js",
    "engines": {
        "alma": "^0.1.0"
    },
    "type": "tool",
    "activationEvents": ["onStartup"]
}

4. Write the Plugin Code

Create main.ts:

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

export async function activate(context: PluginContext): Promise<PluginActivation> {
    const { logger, ui } = context;

    logger.info('My first plugin activated!');

    // Show a notification when the plugin loads
    ui.showNotification('Hello from my plugin!', { type: 'success' });

    return {
        dispose: () => {
            logger.info('My first plugin deactivated');
        },
    };
}

5. Build and Install

npx tsc

Copy the compiled files to Alma's plugins directory:

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

Required files:

• manifest.json
• main.js

6. Enable the Plugin

1. Open Alma
2. Go to Settings > Plugins
3. Find "My First Plugin" and enable it

Plugin Structure

A typical Alma plugin has the following structure:

my-plugin/
├── manifest.json       # Plugin metadata (required)
├── main.ts             # Source code
├── main.js             # Compiled entry point (required)
├── package.json        # npm package file
├── tsconfig.json       # TypeScript configuration
└── README.md           # Plugin documentation

Manifest Reference

The manifest.json file defines your plugin's metadata and capabilities:

{
    "id": "unique-plugin-id",
    "name": "Human Readable Name",
    "version": "1.0.0",
    "description": "What your plugin does",
    "author": {
        "name": "Author Name",
        "email": "author@example.com",
        "url": "https://example.com"
    },
    "main": "main.js",
    "engines": {
        "alma": "^0.1.0"
    },
    "type": "tool",
    "permissions": [
        "notifications"
    ],
    "activationEvents": [
        "onStartup"
    ],
    "contributes": {
        "tools": [],
        "commands": [],
        "configuration": {
            "title": "My Plugin Settings",
            "properties": {
                "myPlugin.enabled": {
                    "type": "boolean",
                    "default": true,
                    "description": "Enable the plugin feature"
                }
            }
        }
    }
}

Manifest Fields

Field	Required	Description
id	Yes	Unique identifier (lowercase, hyphens allowed)
name	Yes	Display name
version	Yes	Semantic version (e.g., "1.0.0")
description	Yes	Short description
author	Yes	Author information
main	Yes	Entry point file
engines.alma	Yes	Required Alma version
type	No	Plugin type (tool, ui, theme, provider, transform)
permissions	No	Required permissions
activationEvents	No	When to activate the plugin
contributes	No	Plugin contributions

Activation Events

Event	Description
onStartup	Activate when Alma starts
onCommand:commandId	Activate when a specific command is invoked
onLanguage:languageId	Activate for specific file types
*	Activate immediately (not recommended)

Plugin Types

Type	Description	Use Case
tool	Registers AI tools	Add capabilities the AI can use
ui	Adds UI components	Status bar items, sidebars
theme	Provides themes	Custom color schemes
provider	Adds AI providers	New AI model backends
transform	Transforms data	Modify messages/prompts
composite	Multiple types	Complex plugins

Next Steps

• API Reference - Complete API documentation
• Hooks & Events - React to application events
• UI API Guide - Build user interfaces
• Examples - Real-world plugin examples