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

Table of contents

• Use plugins
  • Quick start
• What the CLI does
• Restore your plugin setup
• Install for one project
• Any Agent Plugins 1.0 package
• Supported clients
• Already built with UAP SDK
• Find and verify plugins
• Lifecycle safety
• More commands
• Build plugins
• Contributing
• License

Keep a reproducible set of plugins and dependencies, and carry it to another computer. The manifest records what you need; the lockfile pins the exact packages to restore. This workflow ships in the published CLI; see Restore your plugin setup. For the published installer, start with the Quick start.

Our installer automation principle is to complete every ownership-safe client step automatically and ask the user only for genuine external approvals, authentication, or reloads.

Read the documentation · Browse plugins

Use plugins

Install, inspect, update, repair, and remove packages with the existing installer. The Use guide source collects this journey. See Build plugins below to create and check a package.

Quick start

With Node.js 22+, run:

npx universal-agent-plugins add context7

The CLI automatically finds compatible agents, including Codex and Claude Code. Choose agents if several are found; a single detected agent is selected automatically. Follow the printed setup steps, then start a new agent session.

The current verified native release is CLI 0.1.94, also available through Homebrew. Distribution channels can update at different times. Check agentplugins version (or npx universal-agent-plugins version) before using 0.1.94-only automatic project selection. If your selected channel is older, use the native/Homebrew installation below or keep the explicit project-scope commands supported since 0.1.93.

Other installation options

macOS

With Homebrew:

brew install 777genius/agentplugins/agentplugins
agentplugins add context7

Without Homebrew, use the native installer:

curl -fsSL https://raw.githubusercontent.com/777genius/universal-agent-plugins/main/install.sh | sh -s -- add context7

Linux

Install the matching native binary and add your first plugin:

curl -fsSL https://raw.githubusercontent.com/777genius/universal-agent-plugins/main/install.sh | sh -s -- add context7

Homebrew also works on Linux: run brew install 777genius/agentplugins/agentplugins, then agentplugins add context7.

Windows

Run in PowerShell:

irm https://raw.githubusercontent.com/777genius/universal-agent-plugins/main/install.ps1 | iex
& "$HOME\.local\bin\agentplugins.exe" add context7

To install the latest installer globally with Node.js 22+:

npm install -g universal-agent-plugins

Homebrew and the installers select the native binary for your OS and architecture. The installer scripts verify its published SHA-256 and reported version, then replace the CLI atomically. They install into $HOME/.local/bin unless AGENTPLUGINS_BIN_DIR is set.

The native CLI does not require Node.js. The npx option requires Node.js 22+ and downloads and runs the verified Go binary. Individual plugins may have their own runtime requirements, which the CLI checks before installation.

The plugin package is downloaded and verified once, then prepared for each selected agent.

Browse plugins

What the CLI does

• installs one plugin in one or several supported agents;
• updates, repairs, and removes only files it manages;
• converts the same Agent Plugins 1.0 package into each agent's native format;
• keeps activation and OAuth prompts visible to you.

Restore your plugin setup

These commands are part of the published CLI (agentplugins 0.1.90 and later). The Quick start above covers installation.

On the source computer, open a folder to use for the transfer and run:

agentplugins deps export

Copy that folder to the new computer, install the required target clients, and open the copied folder. Then restore the recorded plugins and dependencies:

agentplugins deps import --install

The optional directory argument defaults to the current folder. By default, export reads the global user environment and import writes it. Only uap.toml and uap.lock are transferred. Restore verifies exact locked packages from still-available sources or the destination cache for supported dependency clients: Claude Code, Codex, OpenCode, Cursor and Gemini CLI.

Authentication, client settings, secrets and plugin data need separate setup or backup. Transferring the files does not guarantee offline installation. See Restore on another machine for confirmation prompts, supported restore behavior and recovery.

Install Agent Skills with agentplugins skills add from a GitHub repository or from an HTTPS publisher that serves a .well-known Skills index. Publisher installs take an exact --skill name. The local browser picker and saved dependencies are included.

Install for one project

Released in CLI 0.1.93: select project scope explicitly:

agentplugins add owner/repo --alias review --target cursor \
  --scope project --project-root /path/to/project
agentplugins install --locked --scope project --project-root /path/to/project
agentplugins skills add owner/repository --ui \
  --scope project --project-root /path/to/project

The portable uap.toml and uap.lock live in that project. Local receipts, recovery state and retained data live under .uap/; the user's environment remains separate. Add and maintenance commands default to user scope; explicit project scope without --project-root uses the current directory. In CLI 0.1.94, argumentless agentplugins install selects project scope when that exact directory contains a regular uap.toml; it never searches parents. Explicit scope wins. An existing lock is checked strictly before install/repair, while a missing lock permits first-install resolution. Use update to advance pins; --locked also requires a lock to exist. Native capabilities and activation requirements depend on the client. ChatGPT has no native project installation. See Project installation for supported-target reporting, update/repair/removal and portable restore. The current project support table records each client's component paths and activation limits; user-scope compatibility below is a separate contract.

VS Code project scope prepares .github/skills and owned .vscode/mcp.json servers for one local folder. Its Prepared result leaves workspace/server trust and runtime selection to the client. See VS Code project preparation.

Any Agent Plugins 1.0 package

Install from the registry, a local package, Git over HTTPS or SSH, or a complete HTTPS archive. plugin.json is the sole supported authoring manifest.

Package layout and portability

The installed package is standard-first:

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

Skills and MCP are portable components. Hooks and other client-specific extensions depend on the target client; they do not imply portable behavior.

You can also install a local package or a pinned GitHub package without adding it to the registry. Direct-install examples are collected near the end of this README.

Released in CLI 0.1.93: direct sources include arbitrary HTTPS and SSH Git, GitHub/GitLab/Azure browser URLs, and complete HTTPS/local ZIP/TAR/TAR.GZ/TGZ packages. See Direct complete package sources for syntax, native credentials, immutable archive byte pins and supported limits. These complete-package agentplugins add transports do not import standalone skill files as plugins. The separate agentplugins skills add workflow above installs raw Agent Skills through deterministic normalization.

Other manifest formats are ignored and cannot override plugin.json.

Supported clients

The CLI has adapters for:

Client	Delivery
Codex	plugin package prepared for Codex
ChatGPT	app setup; Context7 includes guided personal setup (Developer Mode and custom apps required)
Cursor	native plugin with skills and MCP servers
GitHub Copilot CLI	native plugin installed through a managed marketplace
VS Code	plugin package prepared for Copilot
Kiro	skills and MCP setup; OAuth/restart may be required
Claude Code	native Claude Code plugin installation
Gemini CLI	skills and MCP configuration
OpenCode	skills and MCP configuration
Cline	skills and MCP configuration
Windsurf	MCP configured; skills prepared for manual use
Grok Build	native skills/MCP plugin; Grok CLI install and verification when available
Kimi Code	native skills/MCP plugin and managed user registry; reload required
Qoder	native skills/MCP plugin; Qoder CLI install and verification when available
Pi	native Pi extensions only; user-scope installation and reload required

Pi installs packages that declare a native Pi extension. Run npx universal-agent-plugins add ./my-plugin --target pi, then reload resources or restart Pi. The Pi adapter supports native extensions only; portable skills and MCP projection are outside its current scope.

Grok Build, Kimi Code, and Qoder accept automatic user-scope installation of portable skills and MCP servers through agentplugins add ./my-plugin --target grok,kimi,qoder. Grok Build and Kimi Code support stdio/HTTP MCP; the Qoder adapter currently supports stdio MCP. The CLI verifies native registration and supports update and removal. A running client still needs a reload, and MCP authentication/connectivity is verified in that client.

Qoder also preserves target-native hooks/**, commands/**, and bundled bin/** files for native discovery. Its Go SDK supports SessionStart, UserPromptSubmit, PostToolUse, and Stop. These native files are separate from portable hook and command conversion; portable agents, hooks, commands, and LSP components remain outside these three adapters' supported scope.

Compatibility depends on the package and client. The CLI tells you what is installed, prepared, or still needs activation or sign-in.

See the client compatibility evidence for tested client versions, platforms, and release-specific limitations.

Context7 setup for ChatGPT and Kiro

npx universal-agent-plugins add context7 --target chatgpt,kiro --no-save

This mixed example uses --no-save because ChatGPT preparation is not a saved portable dependency. To keep other clients in a saved environment, prepare ChatGPT separately.

• ChatGPT: the CLI guides you to create a Developer Mode app for https://mcp.context7.com/mcp with No authentication, accepts the resulting asdk_app_... ID, and prepares a personal marketplace package. You still install that package and select Context7 in a new chat. When other clients are selected too, the CLI installs them first and reports ChatGPT as a separate setup step instead of cancelling the whole batch.
• Kiro: the CLI installs its owned skills and MCP entry while preserving unrelated configuration. On macOS and Windows it reports the remaining Kiro OAuth/restart step instead of claiming automatic runtime verification.

The same retained installation supports repeat add, update, repair, remove, and reinstall. ChatGPT availability still depends on an account or workspace where Developer Mode and custom apps are enabled.

See the real Context7 ChatGPT and Kiro E2E evidence.

Compatibility and Codex MCP transport limits

A schema pass means that the package is well-formed; it does not prove runtime, OAuth, or activation in every client.

For Codex, declared MCP SSE is unsupported; stdio and Streamable HTTP retain their existing adapter support. Valid SSE components are excluded from Codex delivery without invalidating the package. See transport evidence and lifecycle behavior.

Already built with UAP SDK

Build with reusable Go installer components and typed runtime hooks. The TypeScript Management SDK is available in source as a development package; it has no public npm release.

Agent Notifications Desktop notifications, sounds, and click-to-focus for AI coding agents.

Read the Go SDK integration guide for typed runtime hooks and client-specific handlers.

Find and verify plugins

Use agentplugins search or browse the registry to find plugins. Reviewed registry entries and unreviewed discovery results are labelled separately.

How discovery results are verified

search combines the reviewed Registry Directory with a signed public Discovery Index containing 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

The CLI checks packages before installation and changes only files it manages. Use --dry-run to preview changes. OAuth and consent stay under your control. No install telemetry is sent.

Removal checks recorded ownership before changing managed files or configuration entries. Foreign content and externally edited entries are preserved; unresolved ownership produces a conflict or a recovery instruction. Plugin data and shared source caches can be retained intentionally. Some clients require an explicit external uninstall before UAP can settle its own binding.

Lifecycle tests include file inventories and foreign-content checks. Real native runs, deterministic adapter tests and manual setup are different kinds of evidence; their coverage depends on the client, version, platform and scope. See removal safety and the client compatibility reference for those boundaries.

Ownership and rollback

Before changing a client, the CLI validates the source and preflights every selected target. --dry-run prints the plan without applying managed client changes. Security checks may still acquire scanner binaries or metadata. Managed files and state are committed together; failures roll back what ownership proves safe or stop with a repair command. Preview does not activate a plugin or sign you in. Repair checks managed files; it does not prove external OAuth or runtime behavior. A multi-target operation can have partial results; inspect each target and its recovery instruction before retrying.

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

More commands

For normal interactive use, omit --target and choose agents in the prompt. Use --target in scripts, CI, or whenever you want to name clients explicitly.

# Find and inspect plugins
agentplugins search docs
agentplugins info context7

# Install in specific agents
agentplugins add context7 --target codex,claude

# Manage an installed plugin
agentplugins update context7 --target codex,claude
agentplugins repair context7 --target codex,claude
agentplugins remove context7 --target codex,claude
agentplugins outdated --all
agentplugins update --all
agentplugins doctor

# Install a local Agent Plugins 1.0 package
agentplugins validate ./my-plugin
agentplugins add ./my-plugin

Install directly from an exact GitHub commit

# Install the only Agent Plugins package found at an exact commit
agentplugins add \
  owner/repository@0123456789abcdef0123456789abcdef01234567

# Choose a package explicitly when a repository contains several
agentplugins add \
  owner/repository@0123456789abcdef0123456789abcdef01234567//path/to/plugin

These historical GitHub selectors require a full 40-character commit SHA. Branches, tags, and abbreviated SHAs are rejected in this spelling. When no package path is given, the CLI uses a valid root plugin.json or auto-selects the only valid nested package that has mcp.json or skills/. If several packages match, it lists them and asks for an explicit //path. Repositories with more than 16 possible packages require an explicit path before candidate packages are fetched. The selected canonical path and package digest are stored for safe replay. Direct full-SHA installations remain immutable; use switch to move to another exact source. repair reapplies the recorded source, and remove changes only files owned by the CLI.

Build plugins

Create a portable Agent Plugins 1.0 package manually from a root plugin.json, with optional skills/ and mcp.json, then validate and install it with the commands above. The current npm and native installer releases do not include agentplugins author.

The Build guide covers package structure, remote MCP, stdio MCP, hybrid packages, and the handoff to installation. Its authoring commands require a qualified authoring build or a source build. See the Use / Build quickstart. Native Agent Plugins releases use the agentplugins-v* tag prefix.

Qualified/source-build authoring commands (not in the current installer release)

In qualified authoring builds, agentplugins author is the public authoring entrypoint. These examples require such a build or a current source build; installing the latest npm or native installer does not provide them.

Create and check a Skill package:

agentplugins author init ./my-plugin --template skill --name my-plugin
agentplugins author validate ./my-plugin
agentplugins author inspect ./my-plugin
agentplugins author test ./my-plugin

Current source builds also include JSON maintenance, dependency bootstrap, and a continuous MCP development loop. For a separate stdio MCP package, start with an absent ./local-tools destination:

agentplugins author init ./local-tools --template mcp-stdio --runtime node \
  --name local-tools --description "Local Node MCP tools"
agentplugins author normalize ./local-tools --document plugin.json
agentplugins author normalize ./local-tools --document mcp.json --write

After reviewing the generated source and satisfying the Linux dependency and runtime prerequisites in the stdio guide, select its actual server explicitly:

agentplugins author bootstrap ./local-tools --dry-run
agentplugins author bootstrap ./local-tools
agentplugins author dev ./local-tools --server local-tools

Normalization plans are read-only until --write. To import an existing Claude MCP configuration, select its actual strict-JSON file and a new absent output:

agentplugins author import native ./claude.json --from claude \
  --output /absolute/path/to/new-plugin --name new-plugin \
  --description "Imported Claude MCP package" --write

Native import reads only the explicit strict-JSON Claude file and accepts safe stdio command/args entries. Entries with env, type or url, including HTTP servers, are skipped; it publishes only to an absent output. These commands become supported installation guidance after a signed agentplugins authoring release passes the public-channel checks.

Authoring validation and project doctor are distinct from installer agentplugins validate and agentplugins doctor. In qualified/source builds, MCP execution is available through author test and author dev. Dependency bootstrap apply currently requires Linux; dry-run planning can be used on other platforms. Local stdio runtime checks and development also require Linux, successful process-containment and bubblewrap preflights, and a supported system Node path. See the stdio guide for those prerequisites. Client projection, export/bundle, and publication are not exposed by the current authoring CLI. OAuth and activation inside a supported client still require client-specific verification. plugin.json is the only supported authoring manifest. JSON maintenance does not add a YAML reader, fallback, or migration workflow.

Contributing

Contributor checks:

go test ./...
make vet

• Contributing: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support boundary: docs/SUPPORT.md
• Native CLI installation: docs/NATIVE_INSTALL.md
• Portable commands: docs/UAP_COMMANDS.md
• Client E2E evidence: docs/AGENTPLUGINS_CLIENT_E2E.md
• Registry repository: https://github.com/777genius/universal-agent-plugins-registry

License

Universal Agent Plugins is licensed under the Apache License 2.0. Third-party components retain their original licenses; see NOTICE for attribution.