Plugins

AI DevKit plugins are npm packages that add commands to the ai-devkit CLI.

Use plugins for capabilities that should live outside the core CLI, such as dashboards, visual tools, project-specific command sets, or heavier integrations. The first plugin system supports global npm plugins only.

Important: Installing a plugin means installing and running npm package code on your machine. Install plugins only from sources you trust.

Available First-Party Plugins#

After installation, run ai-devkit memory-dashboard for the memory UI or ai-devkit task --help for task commands.

How Plugins Work#

AI DevKit keeps plugins in a dedicated npm workspace under your home directory:

~/.ai-devkit/npm
└── node_modules/
    └── <plugin-package>/

Enabled plugins are listed in the global AI DevKit config:

{
  "plugins": ["@ai-devkit/memory-dashboard"]
}

On startup, AI DevKit:

1. Reads ~/.ai-devkit/.ai-devkit.json.
2. Loads each package listed in plugins.
3. Reads the package's package.json plugin manifest.
4. Validates the contributed command names and JavaScript entrypoints.
5. Registers the plugin commands with the CLI.

Because plugins live under ~/.ai-devkit/npm, they work the same way whether you run AI DevKit with npx ai-devkit, a globally installed ai-devkit, or a local binary.

Install a Plugin#

Use ai-devkit plugin add with an npm package name:

ai-devkit plugin add @ai-devkit/memory-dashboard

The command:

1. Creates ~/.ai-devkit/npm/package.json if needed.
2. Runs npm install <package> inside ~/.ai-devkit/npm.
3. Validates the plugin manifest.
4. Adds the package name to ~/.ai-devkit/.ai-devkit.json.

If the package installs but does not contain a valid plugin manifest, AI DevKit uninstalls it and does not add it to the global config.

Only npm package names are supported in this version. Local paths, tarballs, git URLs, and version specs are not accepted by plugin add.

Run a Plugin Command#

After installation, run the command contributed by the plugin:

ai-devkit memory-dashboard

Use the plugin package documentation to know which command names and flags it provides.

List Plugins#

ai-devkit plugin list

The list shows each configured package and whether its manifest is valid.

Remove a Plugin#

ai-devkit plugin remove @ai-devkit/memory-dashboard

This uninstalls the package from ~/.ai-devkit/npm and removes the package name from ~/.ai-devkit/.ai-devkit.json.

Plugin Manifest#

A plugin package declares commands in its package.json with aiDevkit.commands:

{
  "name": "@ai-devkit/memory-dashboard",
  "version": "0.1.0",
  "type": "module",
  "aiDevkit": {
    "commands": [
      {
        "name": "memory-dashboard",
        "description": "Open the AI DevKit memory dashboard",
        "entry": "./dist/command.js"
      }
    ]
  }
}

Each command has:

Command names cannot conflict with built-in AI DevKit commands such as memory, skill, agent, docs, or plugin.

Command entries must point inside the plugin package. AI DevKit rejects entries that resolve outside the package root or point to missing files.

Command Entrypoint#

Each command entrypoint exports a register function:

export async function register(command, runtime) {
  command
    .description('Open the AI DevKit memory dashboard')
    .option('--port <port>', 'Port to bind')
    .action(async options => {
      const memoryDbPath = await runtime.getMemoryDbPath();
      runtime.logger.info(`Starting dashboard for ${memoryDbPath}`);
    });
}

The command argument is a Commander command instance for the command declared in the manifest. Add options, arguments, and an action inside register.

The runtime argument gives the plugin access to stable AI DevKit context:

Develop a Plugin#

Create a normal npm package and point the manifest to built JavaScript:

my-plugin/
├── package.json
├── src/
│   └── command.ts
└── dist/
    └── command.js

TypeScript is fine for development, but AI DevKit loads JavaScript at runtime. Build the plugin before publishing and set aiDevkit.commands[].entry to the compiled file.

Minimal package example:

{
  "name": "@my-org/hello-ai-devkit",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": "./dist/command.js"
  },
  "aiDevkit": {
    "commands": [
      {
        "name": "hello-devkit",
        "description": "Print a test message",
        "entry": "./dist/command.js"
      }
    ]
  }
}

Minimal command:

export function register(command, runtime) {
  command.action(() => {
    runtime.logger.info(`Hello from ${runtime.cwd}`);
  });
}

Local Smoke Test#

Until local plugin development commands are available, you can manually create a test package under the managed plugin directory:

mkdir -p ~/.ai-devkit/npm/node_modules/@my-org/hello-ai-devkit

Create ~/.ai-devkit/npm/node_modules/@my-org/hello-ai-devkit/package.json:

{
  "name": "@my-org/hello-ai-devkit",
  "version": "0.0.0",
  "type": "module",
  "aiDevkit": {
    "commands": [
      {
        "name": "hello-devkit",
        "description": "Print a test message",
        "entry": "./command.js"
      }
    ]
  }
}

Create ~/.ai-devkit/npm/node_modules/@my-org/hello-ai-devkit/command.js:

export function register(command, runtime) {
  command.action(async () => {
    console.log('hello from an AI DevKit plugin');
    console.log(`memory db: ${await runtime.getMemoryDbPath()}`);
  });
}

Then add the plugin package name to ~/.ai-devkit/.ai-devkit.json:

{
  "plugins": ["@my-org/hello-ai-devkit"]
}

Run the command:

ai-devkit hello-devkit

This manual flow is only for quick local testing. Published plugins should be installed with ai-devkit plugin add.

Troubleshooting#

No global plugins configured.#

No package names are listed in ~/.ai-devkit/.ai-devkit.json.

Install a plugin:

ai-devkit plugin add <npm-package>

Plugin install succeeds, then rolls back#

AI DevKit uninstalls a package after install if validation fails. Common causes:

• Missing aiDevkit.commands in package.json
• Empty command list
• Command name conflicts with a built-in command
• Command name contains spaces, arguments, options, uppercase letters, or punctuation
• Entry path points to TypeScript source instead of built JavaScript
• Entry path points outside the package root
• Entry file does not exist

Plugin command does not appear#

Run:

ai-devkit plugin list

If the plugin is invalid, fix the package manifest or remove and reinstall the package.

register() is missing#

The command entrypoint must export register. For ESM packages:

export function register(command, runtime) {
  command.action(() => {
    runtime.logger.info('plugin command ran');
  });
}

Related Pages#

• Configuration File — global config and the plugins field
• Memory — memory database path used by runtime.getMemoryDbPath()
• Skills — agent skills, which are separate from CLI plugins