> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lukan.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> Extend Lukan with plugins for WhatsApp, Email, and custom integrations.

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

```bash theme={null}
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`:

```json theme={null}
{
  "plugins": {
    "enabled": ["whatsapp", "email"]
  }
}
```

## Plugin Registry

Lukan maintains a remote plugin registry at `https://get.lukan.ai/registry.toml`. Install plugins from it:

```bash theme={null}
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.

<Note>
  The registry URL can be customized with the `LUKAN_REGISTRY_URL` environment variable.
</Note>

## Plugin Manifest (`plugin.toml`)

```toml theme={null}
[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`:

```json theme={null}
{
  "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:

```json theme={null}
[
  {
    "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