registry

@elizaos/registry

In-repo source of truth for the elizaOS community plugin registry.

This package replaces the archived, read-only elizaos-plugins/registry GitHub repository that the publish docs used to point at (see elizaOS/eliza#8173). Third-party plugins are now listed by adding one JSON file here and opening a pull request against this monorepo.

What's in here

packages/registry/
├── entries/third-party/        one <package>.json per community package (source of truth)
├── schema/registry-entry.schema.json   JSON Schema for an entry
├── generated-registry.json     wire format the runtime fetches (built from entries/)
└── src/
    ├── types.ts                RegistryEntry + GeneratedRegistry types
    ├── schema.ts               dependency-free entry validation
    ├── loader.ts               read + validate entries/third-party/*.json
    ├── generate.ts             import-safe entries → wire conversion API
    ├── generate-cli.ts         explicit generated-registry.json writer
    ├── validate-cli.ts         `bun run validate`
    └── index.ts                typed loader for programmatic consumers

Two formats live here:

1. Source entry (entries/third-party/*.json) — what contributors and elizaos plugins submit --dry-run author. One file per package.
2. Generated wire registry (generated-registry.json) — the { registry: { "<package>": { … } } } shape the runtime consumes from plugins.eliza.app/generated-registry.json. Produced by bun run generate through generate-cli.ts; never hand-edited.

Commands

bun run --cwd packages/registry validate    # validate every entry against the schema
bun run --cwd packages/registry generate    # regenerate generated-registry.json
bun run --cwd packages/registry test        # unit tests
bun run --cwd packages/registry typecheck

Adding a third-party plugin

The runtime auto-discovers any npm package whose keywords include elizaos, so a listing here is for discoverability and curation, not a hard requirement to run a plugin. To get listed:

1. Publish your plugin to npm under your own scope or an unscoped elizaos-plugin-* name. The @elizaos/* scope is reserved for first-party packages and is rejected by the validator.

2. Generate the entry metadata from your plugin project:

   elizaos plugins submit . --dry-run

   This prints the entries/third-party/<package>.json the CLI derives from your package.json (name, repository, kind, description, tags).

3. Add the file under entries/third-party/, named after the package (/ → __, @ dropped). For example-plugin:

   {
     "package": "example-plugin",
     "repository": "github:example/example-plugin",
     "kind": "plugin",
     "description": "Example community plugin.",
     "homepage": "https://github.com/example/example-plugin",
     "version": "1.0.0",
     "tags": ["utility"]
   }

   Required: package, repository, kind (plugin · connector · app). Optional: description, homepage, version, directory, tags.

4. Validate and regenerate:

   bun run --cwd packages/registry validate
   bun run --cwd packages/registry generate

5. Open a pull request with the new entry file and the regenerated generated-registry.json. Community entries are reviewed for security, functionality, and documentation quality before merge.