plugin-kit-ai

Build one plugin repo and ship it to many AI agents.

plugin-kit-ai keeps authored source under plugin/, still supports legacy src/ repos, 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.

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

If you do not know which path to choose yet, start here:

Try a real plugin now without installing the CLI permanently:

npx plugin-kit-ai@latest add notion --target claude
npx plugin-kit-ai@latest add notion

The first command is the safe single-target path. The second installs every supported output for that plugin.

Recommended daily-use 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/ for new repos, with legacy src/ still supported
• 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/ unless you are intentionally maintaining a legacy src/ repo
• 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
• 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.9 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