---
summary: How a plugin becomes a KimaAI add-on, a class that KimaAI starts with its own services, with its hooks and a WP-CLI command.
area: tools-addons
hooks: [kimaai_register_addons, kimaai_loaded]
---

# Build an add-on

An add-on is a WordPress plugin that extends KimaAI through its hooks. Its main file registers an add-on class on `kimaai_register_addons`, and KimaAI starts the class once its own services are ready: the class adds the add-on's hooks and, in a WP-CLI run, its commands. Nothing of it runs on a site without KimaAI. This guide builds an add-on that tells the chatbot about the shop's holidays: a plugin file, the add-on's class, and a command that shows the notice.

## Example

```php
/**
 * Plugin Name: My holiday notice for KimaAI
 * Description: Tells the KimaAI chatbot when the shop is closed.
 * Version: 1.0.0
 */

defined('ABSPATH') || exit;

add_action(
  'kimaai_register_addons',
  function (\KimaAI\Addons\AddonManager $manager): void {
    require_once __DIR__ . '/src/HolidayAddon.php';
    $manager->register(new \MyHolidayNotice\HolidayAddon());
  }
);
```

This is the plugin's main file, `my-holiday-notice/my-holiday-notice.php`. It adds the callback when WordPress loads the plugin, before KimaAI fires the action on `plugins_loaded`. The class is required inside the callback, so its file loads only when KimaAI runs: it implements KimaAI's interface, which does not exist without KimaAI, and a plugin that declares the class at the top of its main file stops the site with a fatal error when KimaAI is inactive or loads later.

## The add-on's class

`my-holiday-notice/src/HolidayAddon.php`:

```php
<?php
namespace MyHolidayNotice;

use KimaAI\Addons\AddonInterface;
use KimaAI\Main;
use KimaAI\Surfaces\ClassesSurface;

defined('ABSPATH') || exit;

final class HolidayAddon implements AddonInterface {

  public function register(Main $main, ClassesSurface $classes): void {
    add_filter('kimaai_chatbot_instructions', [$this, 'addNotice']);
  }

  public function registerCommands(Main $main, ClassesSurface $classes): void {
    \WP_CLI::add_command('my-holiday-notice show', [$this, 'showNotice']);
  }

  public function addNotice(string $instructions): string {
    $notice = $this->notice();

    return $notice === '' ? $instructions : $instructions . "\n" . $notice;
  }

  /**
   * Shows the notice the chatbot gets.
   */
  public function showNotice(): void {
    $notice = $this->notice();
    \WP_CLI::log($notice === '' ? 'No holiday notice is set.' : $notice);
  }

  private function notice(): string {
    return trim((string) get_option('my_holiday_notice', ''));
  }
}
```

`register()` is the one method of `KimaAI\Addons\AddonInterface`. The add-on adds its hooks there; here it adds the notice from the option `my_holiday_notice` to the chatbot's instructions. `registerCommands()` is optional: KimaAI calls it in a WP-CLI run, so `wp my-holiday-notice show` prints the notice.

## When it starts

On every request, on `plugins_loaded` at priority 10, KimaAI:

1. builds its services and registers its own hooks,
2. fires `kimaai_register_addons`, where add-ons register,
3. calls `register()` of each add-on, in the order they registered,
4. fires `kimaai_loaded`,
5. in a WP-CLI run, calls `registerCommands()` of each add-on that has one, on `cli_init`.

WordPress's `init` comes later, so an add-on can still add callbacks to it in `register()`. Keep `register()` to adding hooks: it runs on every page view, the admin and REST requests included.

## The services

`$main` and `$classes` give access to KimaAI's own objects: `$classes->get(<class name>)` returns the service of a class. They are KimaAI's internal classes, not a public interface, and they can change in any release. Build on hooks where one fits; the hook pages list them by area.

## Without an add-on class

A few hooks need no class. `kimaai_loaded` fires once KimaAI and its add-ons are loaded and not at all without KimaAI:

```php
add_action(
  'kimaai_loaded',
  function (): void {
    add_filter(
      'kimaai_chatbot_instructions',
      function (string $instructions): string {
        return $instructions . "\nOur support line is open Monday to Friday, 9:00 to 17:00.";
      }
    );
  },
  10,
  0
);
```

## Next steps

- A settings page for the add-on: the guide "Your own setting field" (`docs/guides/field-components.md`).
- A tool the chatbot can call: the guide "A tool for the chatbot" (`docs/guides/custom-tool.md`).

## Related

- [kimaai_register_addons](https://kimaai.com/docs/hooks/kimaai_register_addons/): registers the add-on.
- [kimaai_loaded](https://kimaai.com/docs/hooks/kimaai_loaded/): fires once KimaAI and its add-ons are loaded.
- [kimaai_chatbot_instructions](https://kimaai.com/docs/hooks/kimaai_chatbot_instructions/): the filter the example uses.
