plugin-kit-ai

Build one plugin and ship it to many AI agents.

plugin-kit-ai keeps authored source under plugin/, generates the supported outputs you need, and helps you validate the repo before handoff. The honest promise is one repo / many supported outputs, not fake parity everywhere.

Install Agent Plugins 1.0

Want to use a plugin rather than author one? universal-agent-plugins is the standard-first npm installer built on this repository's lifecycle engine:

npx universal-agent-plugins add context7

It reads the root plugin.json defined by Agent Plugins 1.0 and plans, prepares, or installs one explicit target at a time across Codex, ChatGPT, Cursor, GitHub Copilot/VS Code, and Kiro. v0.1 supports user scope; client-native limits are reported before mutation. The first catalog contains 26 portable plugins. Accepted source shapes are either a portable root plugin.json with optional mcp.json, .app.json, and skills/, or an official .codex-plugin/plugin.json with its declared root .mcp.json, .app.json, and skills/ inputs. A portable root manifest wins when both exist. Codex and ChatGPT retain bundled .mcp.json; ChatGPT MCP additionally requires a valid .app.json mapping to a connection registered in Developer Mode. Both targets receive an official generated .codex-plugin/plugin.json. Starting with agentplugins 0.1.6, direct package sources can use --target chatgpt; catalog short names stay fail-closed unless their catalog v2 entry includes pinned ChatGPT compatibility evidence. Catalog v1 remains readable without ChatGPT binding metadata.

When GitHub Copilot CLI is detected, agentplugins installs, updates, and removes the plugin automatically through a managed local marketplace. VS Code discovers that installation automatically, so selecting either Copilot or VS Code once is enough. Codex, ChatGPT, and Kiro keep their required client confirmation and receive an exact, path-specific next step in human-readable output.

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

Short names resolve through the pinned catalog, while a local directory or an exact GitHub source such as owner/repo@ref//path/to/plugin can install any valid Agent Plugins 1.0 package directly. The installed command is agentplugins.

universal-agent-plugins is an independent community installer, not an official OpenAI CLI. OAuth and required client confirmations remain under the user's client. Prepared, auth-pending, and manual-activation states are never labelled installed.

This is separate from the plugin-kit-ai authoring flow below: plugin.json and legacy plugin/plugin.yaml are never merged or silently converted.

Docs site:

• 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
• delivery model guide: Choose A Target
• honest caveat: Support Boundary

Project policies:

• support boundary: docs/SUPPORT.md
• contributing: CONTRIBUTING.md
• security: SECURITY.md
• code of conduct: CODE_OF_CONDUCT.md

Choose What You Are Building

Connect an online service

Use this when the plugin should connect to a hosted service like Notion, Stripe, Cloudflare, or Vercel.

plugin-kit-ai init my-plugin --template online-service
cd my-plugin
plugin-kit-ai inspect . --authoring
plugin-kit-ai generate .
plugin-kit-ai generate --check .
plugin-kit-ai validate . --platform claude --strict

Real examples:

• notion
• stripe
• cloudflare
• vercel

Connect a local tool

Use this when the plugin should call into a repo-owned tool or CLI like Docker Hub, Chrome DevTools, or HubSpot Developer.

plugin-kit-ai init my-plugin --template local-tool
cd my-plugin
plugin-kit-ai inspect . --authoring
plugin-kit-ai generate .
plugin-kit-ai generate --check .
plugin-kit-ai validate . --platform claude --strict

Real examples:

• docker-hub
• hubspot-developer
• chrome-devtools

Build custom plugin logic - Advanced

Use this when the product is defined by hooks, runtime behavior, or custom plugin code.

This path is more powerful and more engineering-heavy than the first two starters. Plain plugin-kit-ai init my-plugin still exists as the legacy compatibility path for the older Codex runtime Go starter.

plugin-kit-ai init my-plugin --template custom-logic
cd my-plugin
plugin-kit-ai inspect . --authoring
plugin-kit-ai validate . --platform codex-runtime --strict
plugin-kit-ai test . --platform codex-runtime --event Notify

Guide:

• Build Custom Plugin Logic

Quick Start

Want to try a real Agent Plugin without installing a CLI permanently?

npx universal-agent-plugins add context7

Building a plugin instead? Use plugin-kit-ai for authoring and generated output delivery. Its older plugin-kit-ai add lifecycle is not the default installer for portable Agent Plugins 1.0. Start with Choose What You Are Building.

Recommended authoring CLI install path:

brew install 777genius/homebrew-plugin-kit-ai/plugin-kit-ai
plugin-kit-ai version

Then create a repo from the path that matches the job:

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

Plain plugin-kit-ai init my-plugin still exists for backward compatibility, but it is no longer the recommended first start for new repos. Use one of the three job-first templates above unless you are intentionally maintaining the older Codex runtime Go path.

What You Get

• one plugin repo that stays the source of truth
• authored files under plugin/
• generated root files that stay managed
• supported outputs for Claude, Codex, Gemini, Cursor, and OpenCode where the repo shape allows it
• a clean readiness check through generate, generate --check, and validate --strict

Works Across Multiple Outputs

• Claude
• Codex package
• Codex runtime
• Gemini
• OpenCode
• Cursor

That depth stays available, but you do not need to understand the whole target model before creating the repo.

What To Do Next

• run plugin-kit-ai inspect . --authoring
• edit the repo under plugin/
• regenerate after changes
• validate the supported output you actually plan to ship first
• only then add more outputs when the product really needs them

Other supported CLI install methods:

• 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
• fallback one-shot command: curl -fsSL https://raw.githubusercontent.com/777genius/plugin-kit-ai/main/scripts/install.sh | sh -s -- add notion --dry-run
• source build for maintainers of this repo: go build -o bin/plugin-kit-ai ./cli/plugin-kit-ai/cmd/plugin-kit-ai

Keep This Rule In Mind

• start with the job you need today
• keep authored source under plugin/ for new repos
• let generated root files stay managed
• add deeper target-specific behavior only when you need it
• use advanced docs when you need exact target and support details

Deep Product Details

Everything below this point is for people comparing delivery models, import paths, and detailed support boundaries. If you only needed the main promise and first path, you can stop above.

Go Deeper By Goal

Fast Local Plugin

Choose this when the plugin stays local to the repo and your team already works in Python or Node.

• Main flow: init -> doctor -> bootstrap -> generate -> validate --strict
• Runtime note: the execution machine still needs Python 3.10+ or Node.js 20+
• Delivery options: vendored helper by default, shared plugin-kit-ai-runtime when you want a reusable dependency, bundle handoff when the repo must travel

This is a supported non-Go path, not a hidden fallback. Use the starter templates for Codex and Claude across Go, Python, and Node/TypeScript when you want the fastest copy-first path into a working repo.

Start here:

• examples/starters/README.md
• examples/local/README.md
• docs/CHOOSING_HELPER_DELIVERY_MODE.md

Production-Ready Plugin Repo

Choose this when you want the strongest supported release and distribution story.

• Online service path: plugin-kit-ai init my-plugin --template online-service
• Local tool path: plugin-kit-ai init my-plugin --template local-tool
• Advanced runtime path: plugin-kit-ai init my-plugin --template custom-logic
• Package/config expansion later: codex-package, gemini, opencode, cursor
• Real multi-target MCP-first example: context7 in universal-plugins-for-ai-agents

Already Have Native Config

Choose this when you are migrating existing Claude/Codex/Gemini/OpenCode/Cursor native files into the repo-owned workflow.

./bin/plugin-kit-ai import ./native-plugin --from codex-runtime
./bin/plugin-kit-ai normalize ./my-plugin
./bin/plugin-kit-ai generate ./my-plugin
./bin/plugin-kit-ai validate ./my-plugin --platform codex-runtime --strict

Stability Snapshot

Stable by default:

• the main public CLI contract
• the recommended Go SDK path
• Go scaffolds for the default Codex and Claude runtime lanes
• 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

Use carefully:

• generate, import, and normalize are still public-beta
• package and workspace-config targets have different guarantees than runtime targets
• shell remains a bounded public-beta escape hatch

For the precise contract:

• docs/generated/target_support_matrix.md
• docs/generated/support_matrix.md
• docs/SUPPORT.md

Path Summary

• Go is the recommended path when you want the strongest production story and the least downstream runtime friction.
• Node/TypeScript is the main supported non-Go path for repo-local runtime plugins.
• Python is the supported Python-first repo-local path.
• Package and workspace-config targets are for packaging and configuration outputs, not for pretending every target behaves like a runtime plugin.

SDK And CLI

Go SDK packages:

• github.com/777genius/plugin-kit-ai/sdk
• github.com/777genius/plugin-kit-ai/sdk/claude
• github.com/777genius/plugin-kit-ai/sdk/codex
• github.com/777genius/plugin-kit-ai/sdk/gemini

Useful starting points:

• sdk/README.md
• docs/generated/support_matrix.md
• docs/SUPPORT.md

Common CLI commands:

./bin/plugin-kit-ai init my-plugin
./bin/plugin-kit-ai doctor ./my-plugin
./bin/plugin-kit-ai bootstrap ./my-plugin
./bin/plugin-kit-ai generate ./my-plugin
./bin/plugin-kit-ai validate ./my-plugin --platform codex-runtime --strict
./bin/plugin-kit-ai import ./native-plugin --from codex-runtime
./bin/plugin-kit-ai capabilities --format json

plugin-kit-ai install stays intentionally narrow: it installs third-party plugin binaries from GitHub Releases, verifies checksums.txt, and does not act as a self-update path for the CLI itself.

For automation, plugin-kit-ai validate --format json now emits the versioned plugin-kit-ai/validate-report contract with schema_version: 1 and explicit outcomes passed, failed, or failed_strict_warnings. For Codex lane selection, use docs/CODEX_TARGET_BOUNDARY.md. For the validation ABI itself, use docs/VALIDATE_JSON_CONTRACT.md.

Build And Test

Requirements:

• Go 1.25.12 for this monorepo workspace and its CI lanes
• generated Go plugin projects created by plugin-kit-ai init remain on Go 1.22+

Common commands from repo root:

go run ./cmd/plugin-kit-ai-gen
go build -o bin/plugin-kit-ai ./cli/plugin-kit-ai/cmd/plugin-kit-ai
./bin/plugin-kit-ai version
make test-polyglot-smoke
go test ./...

Repository And Docs Map

Main repo areas:

• sdk
• cli/plugin-kit-ai
• install/plugininstall
• examples/starters
• examples/local
• examples/plugins
• repotests
• docs

Canonical docs:

• docs/generated/support_matrix.md
• docs/generated/target_support_matrix.md
• docs/SUPPORT.md
• docs/CODEX_TARGET_BOUNDARY.md
• docs/VALIDATE_JSON_CONTRACT.md
• docs/PRODUCTION.md
• docs/INSTALL_COMPATIBILITY.md
• docs/STATUS.md

Maintainer-only historical context:

• docs/ARCHITECTURE.md
• docs/FOUNDATION_REWRITE_VNEXT.md
• docs/adr/README.md