Plugin Development

Extend Phoenix Agent with custom commands, providers, and behaviors.

Creating a Plugin

/plugins create myplugin

This generates a template in %LOCALAPPDATA%\phoenix-agent\plugins\myplugin\:

myplugin/
├── phoenix.json    # Manifest
└── __init__.py     # Plugin code

Plugin Manifest

{
  "name": "myplugin",
  "version": "0.1.0",
  "description": "My custom plugin",
  "author": "Your Name",
  "commands": ["mycommand"],
  "tags": ["utility"]
}

Plugin Code

"""Phoenix Agent Plugin: myplugin."""

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from phoenix_agent.core.engine import PhoenixEngine

PHOENIX_PLUGIN = {
    "name": "myplugin",
    "version": "0.1.0",
    "description": "My custom plugin",
}


def register(engine: "PhoenixEngine") -> None:
    """Called when the plugin is loaded."""
    from phoenix_agent.core.registry import Command, CommandCategory

    async def cmd_mycommand(eng: "PhoenixEngine", *args: str) -> str:
        return "[green]Hello from myplugin![/green]"

    engine.commands.register(Command(
        name="mycommand",
        description="My custom command",
        handler=cmd_mycommand,
        category=CommandCategory.TOOLS,
    ))


def unregister(engine: "PhoenixEngine") -> None:
    """Called when the plugin is unloaded."""
    pass

Lifecycle

Accessing Engine APIs

The engine parameter gives access to everything:

engine.settings          # User settings
engine.security          # Permissions, trust, encryption
engine.memory            # Persistent memory
engine.providers         # AI providers
engine.mouse             # Win32 mouse control
engine.keyboard          # Win32 keyboard control
engine.events            # Event bus (subscribe/publish)
engine.commands          # Command registry
engine.journal           # Decision journal

Subscribing to Events

from phoenix_agent.core.events import EventType

async def on_trust(event):
    print("Trust mode changed!")

def register(engine):
    engine.events.subscribe(EventType.TRUST_ENABLED, on_trust)

Managing Plugins

/plugins list            # List loaded plugins
/plugins load myplugin   # Load a plugin
/plugins unload myplugin # Unload
/plugins reload myplugin # Reload after changes