Universal Agent Plugins

Install and manage Agent Plugins 1.0 across your AI agents with one CLI.

npx universal-agent-plugins add context7 --target cursor

The command downloads a package once, verifies it, prepares the native format for
the selected client or clients, and tells you about any remaining activation or
OAuth step.

This repository is the product home and npm facade source. The facade installs the agentplugins binary; plugin-kit-ai is the shared Go implementation engine
during the repository rename and is not duplicated here.

Quick start

You need Node.js 22 or newer.

1. Pick a plugin from the Universal Agent Plugins Registry:
   https://777genius.github.io/universal-agent-plugins-registry/

2. Choose one or several clients explicitly:

   npx universal-agent-plugins add context7 --target codex,cursor
   

3. Open a new session in the client and follow the printed activation hint.

4. Ask the agent to use the plugin. A real tool call is the useful runtime check.

The same package is acquired once and planned for every selected target. The CLI
does not silently modify every detected client.

For an interactive terminal, omit --target to detect compatible installed
clients and choose them in a multi-select. Scripts and CI should always pass
--target.

Everyday commands

npx universal-agent-plugins search docs
npx universal-agent-plugins info context7
npx universal-agent-plugins add context7 --target codex,cursor,kiro
npx universal-agent-plugins update context7 --target codex,cursor
npx universal-agent-plugins repair context7 --target codex,cursor
npx universal-agent-plugins switch context7 --to 777genius/context7
npx universal-agent-plugins outdated --all
npx universal-agent-plugins update --all
npx universal-agent-plugins remove context7 --target codex,cursor
npx universal-agent-plugins doctor

update keeps the recorded source. repair reapplies that source. switch is the
explicit way to move to another reviewed distribution or exact source. remove
changes only files owned by the CLI.

Any Agent Plugins 1.0 package

The installed package is standard-first:

plugin.json
├── skills/       optional reusable instructions
├── mcp.json      optional MCP servers
└── hooks/        optional client-supported hooks

Use a local package or a pinned GitHub source without submitting it to the
registry:

npx universal-agent-plugins validate ./my-plugin
npx universal-agent-plugins add ./my-plugin --target cursor
npx universal-agent-plugins add \
  owner/repository@0123456789abcdef0123456789abcdef01234567//path/to/plugin \
  --target codex,cursor

Use a full 40-character commit SHA. Branches, tags, and abbreviated SHAs are
rejected for remote installs.

plugin.yaml is the legacy plugin-kit-ai authoring format. It is not merged with
or allowed to override plugin.json.

Supported clients

The CLI has adapters for:

Compatibility is package-specific. A schema pass means that the package is
well-formed; it does not prove runtime, OAuth, or activation in every client.
The CLI prints installed, prepared, activation required, and authentication
pending as separate outcomes.

Find and verify plugins

search combines the reviewed Registry Directory with a signed public Discovery
Index containing 2,500+ conformant package paths. Discovery records are
unreviewed metadata, not endorsements. They install only through a
publisher-qualified exact-SHA selector and are validated again before mutation.

The registry is optional for direct installs, but it makes reviewed short names,
provenance, compatibility notes, and safe discovery convenient:

Browse the registry ·
Submit a package

Lifecycle safety

Before changing a client, the CLI validates the source and preflights every
selected target. --dry-run prints the same plan without writing. Managed files
and state are committed together; failures roll back what ownership proves safe
or stop with a repair command. OAuth and consent remain visible and controlled
by you. No install telemetry is sent.

The CLI is an independent community project. It is not affiliated with OpenAI,
Agent Plugins, or the vendors shown above.

Authoring and development

This repository also retains the original plugin-kit-ai authoring tools. Use
the authoring guide at docs/PLUGIN_KIT_AI_AUTHORING.md when you want to build,
validate, or export a package rather than install one.

Build one plugin and ship it to many AI agents. The repository includes starter templates for Codex and Claude across Go, Python, and Node/TypeScript.

plugin-kit-ai keeps authored source under plugin/, generates the supported outputs you need, and helps you validate the repo before handoff. This includes supported outputs for Claude, Codex, Gemini, Cursor, and OpenCode where the repo shape allows it. The honest promise is one repo / many supported outputs, not fake parity everywhere.

overview: plugin-kit-ai documentation
fastest start: Quickstart
choose by job first: Choose What You Are Building
one repo, many outputs: What You Can Build
honest caveat: Support Boundary

Choose What You Are Building

Connect an online service

Connect a local tool

Build custom plugin logic

Quick Start

brew install 777genius/homebrew-plugin-kit-ai/plugin-kit-ai
npm: `npm i -g plugin-kit-ai` or `npx plugin-kit-ai@latest ...`
pipx (`public-beta`, only when that release is published to PyPI): `pipx install plugin-kit-ai`
fallback installer: `curl -fsSL https://raw.githubusercontent.com/777genius/plugin-kit-ai/main/scripts/install.sh | sh`
plugin-kit-ai init my-plugin --template online-service
plugin-kit-ai init my-plugin --template local-tool
plugin-kit-ai init my-plugin --template custom-logic
plugin-kit-ai init my-plugin
plugin-kit-ai generate .
plugin-kit-ai validate . --platform codex-runtime --strict

Works Across Multiple Outputs

What To Do Next

Keep This Rule In Mind

Deep Product Details

Go Deeper By Goal

Fast Local Plugin

Production-Ready Plugin Repo

Already Have Native Config

examples/starters/README.md
examples/local/README.md
docs/CHOOSING_HELPER_DELIVERY_MODE.md
the stable local Python and Node subset on codex-runtime and claude
doctor, bootstrap, validate --strict, export, and bundle handoff for that stable local subset
generate, import, and normalize are still public-beta
docs/generated/target_support_matrix.md
docs/generated/support_matrix.md
docs/SUPPORT.md

SDK And CLI

Go SDK packages: github.com/777genius/plugin-kit-ai/sdk/claude, github.com/777genius/plugin-kit-ai/sdk/codex, and github.com/777genius/plugin-kit-ai/sdk/gemini.

./bin/plugin-kit-ai doctor ./my-plugin
./bin/plugin-kit-ai bootstrap ./my-plugin
./bin/plugin-kit-ai import ./native-plugin --from codex-runtime
./bin/plugin-kit-ai capabilities --format json

plugin-kit-ai validate --format json now emits the versioned plugin-kit-ai/validate-report contract.
docs/CODEX_TARGET_BOUNDARY.md
docs/VALIDATE_JSON_CONTRACT.md

go test ./...
make vet

• Contributing: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support boundary: docs/SUPPORT.md
• Client E2E evidence: docs/AGENTPLUGINS_CLIENT_E2E.md
• Registry: https://github.com/777genius/universal-agent-plugins-registry

License

The Go engine and this repository remain under the existing MIT license. The
registry keeps its Apache 2.0 license and third-party attribution. No code is
relicensed by the repository rename.