Skip to main content
Plugins are the primary extension mechanism for Lukan. They add new tools, CLI commands, channels, and UI views.

​
Plugin Architecture

Each plugin is a standalone process that communicates with the Lukan agent via IPC:
  1. Discovery - Plugins are installed to ~/.config/lukan/plugins/
  2. Manifest - Each plugin defines a plugin.toml with metadata, commands, tools, and auth requirements
  3. Lifecycle - Init -> Ready (60s timeout) -> Running -> Shutdown
  4. Tools - Declared in tools.json and executed via a handler script (e.g., tools.js)

​
Managing Plugins

​
CLI Commands

lukan plugin list                # List installed plugins
lukan plugin install <path>      # Install from local path
lukan plugin list-remote         # List plugins from registry
lukan plugin remove <name>       # Remove a plugin
lukan plugin start <name>        # Start a plugin
lukan plugin stop <name>         # Stop a plugin
lukan plugin status              # Show status of all plugins
lukan plugin logs <name>         # View plugin logs
lukan plugin config <name>       # Manage plugin configuration
lukan plugin exec <name> <cmd>   # Execute a plugin command

​
Auto-Start

Configure plugins to auto-start in config.json: 
{
  "plugins": {
    "enabled": ["whatsapp", "email"]
  }
}

​
Plugin Registry

Lukan maintains a remote plugin registry at https://get.lukan.ai/registry.toml. Install plugins from it: 
lukan plugin list-remote         # Browse available plugins
lukan plugin install-remote      # Install from registry (via Web UI)
The registry supports platform-specific binaries (linux-x86_64, linux-aarch64, darwin, etc.) and universal Node.js plugins.
The registry URL can be customized with the LUKAN_REGISTRY_URL environment variable.

​
Plugin Manifest (plugin.toml)

[plugin]
name = "whatsapp"
version = "1.0.0"
description = "WhatsApp channel for Lukan"
runtime = "node"

[commands]
wa = "WhatsApp management commands"

[tools]
default = ["ReadFiles", "Grep", "Glob", "WebSearch", "WebFetch"]

[auth]
type = "qr"

[security]
allowed_dirs = true
hidden_file_blocking = true

​
Key Manifest Fields

FieldDescription
namePlugin identifier
runtimeRequired runtime (node, python, bun, deno)
commandsCLI aliases the plugin registers
tools.defaultDefault tools available to the plugin
auth.typeAuthentication method (qr, token, command)
securitySecurity configuration injection

​
Plugin Overrides

Override plugin behavior per-plugin in config.json: 
{
  "plugins": {
    "overrides": {
      "whatsapp": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-5-20250929",
        "tools": ["ReadFiles", "WebSearch"],
        "maxResponseLen": 10000,
        "autoRestart": true
      }
    }
  }
}

​
CLI Aliases

Plugins can register CLI command aliases. For example, the WhatsApp plugin registers wa so lukan wa auth works directly. Reserved aliases (chat, setup, doctor, plugin, sandbox, etc.) cannot be used by plugins.

​
Plugin Authentication

Plugins support three authentication methods:
  • QR Code - Scan a QR code (e.g., WhatsApp)
  • Token - Enter an API key or token
  • Command - Run a custom auth command

​
Custom Tools

Plugins declare tools in a tools.json file: 
[
  {
    "name": "EmailSend",
    "description": "Send a new email",
    "parameters": {
      "to": { "type": "string", "description": "Recipient email" },
      "subject": { "type": "string", "description": "Email subject" },
      "body": { "type": "string", "description": "Email body" }
    }
  }
]
Tools are executed through the plugin’s handler script, typically tools.js running with Node.js.

​
Plugin Prompt

Plugins can include a prompt.txt file that is automatically loaded into the system prompt when the plugin is active. This allows plugins to provide context-specific instructions to the agent.

​
Activity Bar & Views

Plugins can contribute to the desktop/web UI:
  • Activity Bar - Custom sidebar icons and labels
  • Views - Custom UI views with unique IDs and view types