cao-plugin

CAO Plugin Creator

Guide for creating a new CAO plugin. A "plugin" is a Python package installed alongside CAO that subscribes to CAO lifecycle and messaging events via typed async hooks.

What You're Building

A CAO plugin is a standalone Python package that:

1. Subclasses CaoPlugin from cli_agent_orchestrator.plugins
2. Registers async hook methods with @hook("<event_type>") decorators
3. Is discovered via the cao.plugins Python entry-point group at cao-server startup
4. Runs fire-and-forget — plugin exceptions are caught and logged as warnings, never propagated back into CAO

Typical uses: forwarding inter-agent messages to chat apps, logging/observability, external dashboards, metrics export, alerting on session or terminal lifecycle.

Before You Start

Gather this information:

• Which events do you need? See references/hook-events.md for the full catalog.
• Does the plugin need persistent state across events? (HTTP client, DB connection, buffer) — if so, use setup() / teardown().
• How is it configured? v1 has no injected config API — read env vars in setup(), optionally via python-dotenv.
• What are the failure semantics of your integration? Remember CAO swallows hook exceptions — you must decide whether to log, retry, or drop on your own.

Hard Requirements

These are the non-negotiable contracts a plugin must satisfy to be loaded and dispatched to. Verify each one before calling your plugin complete.

1. Package layout

Minimum viable layout:

my-cao-plugin/
├── pyproject.toml          # Build config + entry-point declaration
├── my_cao_plugin/
│   ├── __init__.py         # Can be empty
│   └── plugin.py           # Contains the CaoPlugin subclass
├── tests/                  # Optional but strongly recommended
│   └── test_plugin.py
├── env.template            # Optional; only if the plugin reads env vars
└── README.md               # Optional; install + config instructions for users

See examples/plugins/cao-discord/ in this repo for a complete reference implementation.