Plugins

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:

Discovery - Plugins are installed to ~/.config/lukan/plugins/
Manifest - Each plugin defines a plugin.toml with metadata, commands, tools, and auth requirements
Lifecycle - Init -> Ready (60s timeout) -> Running -> Shutdown
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

Field	Description
`name`	Plugin identifier
`runtime`	Required runtime (node, python, bun, deno)
`commands`	CLI aliases the plugin registers
`tools.default`	Default tools available to the plugin
`auth.type`	Authentication method (qr, token, command)
`security`	Security 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

CLI

Configuration

Extensions

Advanced

Plugin Architecture

Managing Plugins

CLI Commands

Auto-Start

Plugin Registry

Plugin Manifest (`plugin.toml`)

Key Manifest Fields

Plugin Overrides

CLI Aliases

Plugin Authentication

Custom Tools

Plugin Prompt

Activity Bar & Views

​Plugin Architecture

​Managing Plugins

​CLI Commands

​Auto-Start

​Plugin Registry

​Plugin Manifest (plugin.toml)

​Key Manifest Fields

​Plugin Overrides

​CLI Aliases

​Plugin Authentication

​Custom Tools

​Plugin Prompt

​Activity Bar & Views

Plugin Architecture

Managing Plugins

CLI Commands

Auto-Start

Plugin Registry

Plugin Manifest (`plugin.toml`)

Key Manifest Fields

Plugin Overrides

CLI Aliases

Plugin Authentication

Custom Tools

Plugin Prompt

Activity Bar & Views