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.

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.

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.

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.

ai-devkit plugin list

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

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.

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:

Field	Required	Description
name	Yes	CLI command name contributed by the plugin. Use lowercase letters, numbers, and hyphens. It must start with a letter.
description	No	Short help text shown by the CLI.
entry	Yes	Path to a built JavaScript file inside the package. Supported extensions are .js, .mjs, and .cjs.

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.

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:

Runtime field	Description
cwd	Current working directory where the user ran ai-devkit.
homeDir	User home directory.
configPath	Path to ~/.ai-devkit/.ai-devkit.json.
getConfig()	Reads the global AI DevKit config.
getMemoryDbPath()	Returns global config memory.path, or ~/.ai-devkit/memory.db when not configured.
logger.info()	Print an informational message using AI DevKit output formatting.
logger.warn()	Print a warning message using AI DevKit output formatting.
logger.error()	Print an error message using AI DevKit output formatting.

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}`);
  });
}

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.

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

Install a plugin:

ai-devkit plugin add <npm-package>

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

Run:

ai-devkit plugin list

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

The command entrypoint must export register. For ESM packages:

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

• 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