Home/Documentation/Developers/Getting Started

Getting Started

Build your first Elysium plugin in under 10 minutes. This guide walks you through setup, development, and testing.

Prerequisites

Elysium installed
Download the latest version from elysium.is.
JavaScript knowledge
Plugins are written in JavaScript (ES6+). Familiarity with modern JS helps.
A text editor
VS Code, Sublime Text, or any editor you prefer for writing JavaScript.

Create Your Plugin Folder

Create a new folder for your plugin in the Elysium plugins directory. The folder name should be your plugin ID.

# Create your plugin folder
mkdir -p ~/Library/Application\ Support/Elysium/Plugins/com.yourname.my-plugin
cd ~/Library/Application\ Support/Elysium/Plugins/com.yourname.my-plugin

Use reverse domain notation for your plugin ID (e.g., com.yourname.plugin-name).

Create manifest.json

Create a manifest.json file with your plugin's metadata and permissions:

{
  "id": "com.yourname.my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "author": "Your Name",
  "description": "A brief description of what your plugin does.",
  "main": "main.js",
  "permissions": [
    "read:tasks",
    "read:habits"
  ]
}

Only request the permissions your plugin actually needs. See the full permissions list.

Create main.js

Create a main.js file with your plugin's logic. Use lifecycle hooks to initialize and respond to events:

// Called when the plugin is loaded
function onLoad() {
  console.log("My plugin loaded!");
}

// Called when the plugin is enabled
function onEnable() {
  // Listen for habit completions
  elysium.events.on("habit.completed", (habit) => {
    elysium.ui.showNotification({
      title: "Great job!",
      message: `You completed: ${habit.title}`
    });
  });
}

// Called when the plugin is disabled
function onDisable() {
  // Clean up event listeners
}

Test Your Plugin

Your plugin folder should now contain:

~/Library/Application Support/Elysium/Plugins/com.yourname.my-plugin/
├── manifest.json
└── main.js

Open Elysium, go to Settings → Plugins & Recipes, and your plugin should appear. Enable it to test.

Tip: Check the Console app for debug output from your plugin. Filter by “Elysium” to see plugin logs.

Share Your Plugin

When you're ready to share your plugin with the community:

Push your code to a public GitHub repository

Add a README with installation instructions and screenshots

Submit your plugin for review and inclusion in the community directory

Plugin Structure

com.yourname.my-plugin/
├── manifest.json     # Plugin metadata & permissions
├── main.js           # Main entry point
├── icon.png          # Optional: Plugin icon (256x256)
└── README.md         # Optional: Documentation

That's it! Just two required files. No build step, no compilation—edit and reload.