agentrig plugin

agentrig plugin is the plugin workflow. Plugins are the primary AgentRig distribution unit. Agent Plugins v1 makes skills and MCP servers portable; AgentRig can additionally carry hooks, commands, agents, rules, assets, and supporting files under its ai.agentrig extension and emit native provider layouts.

AgentRig plugin manifests are Agent Plugins 1.0.0 conformant. AgentRig-specific fields live under extensions["ai.agentrig"].

If you are consuming plugins from registries, use the top-level commands instead:

agentrig search <query>
agentrig view <plugin-spec>
agentrig plugin install <provider> <plugin-spec>

For public installs, <plugin-spec> must be the canonical registry ref <registryAlias>/<namespace.plugin>. Add @<version> only when you need to pin an exact version for reproducibility or rollback.

Full plugin install

Use plugin install when you want the complete bundle:

agentrig plugin install codex agentrig/agentrig.core-committer
agentrig plugin uninstall codex agentrig/agentrig.core-committer

This is the main path for installing an entire published plugin. The install ledger records the resolved concrete version, registry identity, and snapshot digest even when you use the unversioned latest ref. The CLI resolves the ref by fetching an AgentRig InstallBundle from agentrig.ai.

For Codex, installs are enabled automatically through codex app-server when Codex 0.113.0 or newer is available. Use --no-enable to install the plugin but leave it disabled for manual opt-in from the Codex TUI /plugins view.

Selected artifact install

Use top-level install --pick when you want only specific artifacts from an installable plugin:

agentrig install codex agentrig/agentrig.core-committer \
  --pick skill:codex-analysis \
  --pick skill:gitwhat

Kind-specific helpers are available when all picks have the same kind:

agentrig skill install codex agentrig/agentrig.core-committer \
  --pick codex-analysis \
  --pick gitwhat

agentrig mcp install claude agentrig/acme.tools --pick github
agentrig hook install cursor agentrig/acme.workflow --pick pre-submit

Standalone skills can be installed and uninstalled directly without --pick:

agentrig skill install codex agentrig/acme.review
agentrig skill uninstall codex agentrig/acme.review

Standalone MCP and hook installs without --pick are not a public V1 flow. Install MCPs and hooks from plugin bundles with --pick.

AgentRig records selected-artifact installs as Selection Bundles. A Selection Bundle is one local ledger record with source provenance, selected artifact selectors, closure status, written files, and hash-owned JSON writes. Uninstall removes only files and JSON entries still matching the recorded hashes; user modified files or MCP entries are kept and reported.

Selection install resolves from the same AgentRig InstallBundle as full-plugin install. For arbitrary third-party repos, use inspect and use to scan and materialize a local plugin first.

For third-party repos that are not in a signed registry, use the top-level inspect and use commands. Those commands create external-repo provenance, not registry trust.

inspect and use

agentrig inspect jxnl/dots
agentrig inspect github:jxnl/dots --only-kind skill,mcp --json
agentrig use jxnl/dots --as-plugin acme.dots-pick --pick skills/foo
agentrig use jxnl/dots --install --provider codex --pick prompts/review

inspect and use scan third-party repos deterministically. The scan digest is computed from detector output only; AI output never changes it.

use --as-plugin <name> writes a canonical local Agent Plugins package. use --install stages the same package and installs it through the provider installer. Both paths record external-repository provenance in AgentRig's local ledger and scan records, not in plugin.json, and never convert it into registry trust.

Local BYOK enrichment

CLI AI enrichment is opt-in and local only:

export AGENTRIG_AI_BASE_URL="https://api.openai.com/v1"
export AGENTRIG_AI_API_KEY="..."
export AGENTRIG_AI_MODEL="gpt-4.1-mini"
export AGENTRIG_AI_TIMEOUT_MS="30000"      # optional
export AGENTRIG_AI_MAX_TOKENS="2000"       # optional; useful for reasoning models

agentrig use jxnl/dots \
  --as-plugin acme.dots-pick \
  --pick skills/foo \
  --enrich-ai=local

--enrich-ai resolves to --enrich-ai=local. No hosted CLI enrichment exists in v1. If any required AGENTRIG_AI_* variable is missing, the command fails and prints the required variables instead of falling back to AgentRig-hosted AI.

The CLI posts to {AGENTRIG_AI_BASE_URL}/chat/completions with plain fetch. Your provider key stays on your machine and is sent only to your configured OpenAI-compatible provider. AgentRig servers do not receive the key or the prompt. Use the provider's OpenAI-compatible base URL without /chat/completions; the CLI adds that path. Some reasoning models spend output budget on hidden reasoning, so raise AGENTRIG_AI_MAX_TOKENS if the provider reports a token-limit truncation.

The response must pass the shared AiEnrichmentDraft schema. Suggested description, keywords, and manifest name fields are draft metadata only.

Hosted AI enrichment is disabled for AgentRig 2.0. AI-assisted CLI metadata is local BYOK only.

init

agentrig plugin init acme.my-plugin

init requires the canonical plugin id format namespace.plugin. The scaffold writes that value to plugin.json as the Agent Plugins name; the display label is stored at extensions["ai.agentrig"].displayName.

Options: --template, --dir, --title, --description, --author, --force.

create

The scaffold already writes plugin.json. Use plugin create when you need to generate a manifest for an existing plugin directory:

agentrig plugin create ./acme.my-plugin --out ./acme.my-plugin/plugin.json

Scans an existing plugin directory and writes plugin.json.

export

agentrig plugin export --agent all --pluginsDir ./acme.my-plugin --out dist/plugins

Exports local plugin directories as provider-native plugin marketplaces for claude, codex, cursor, or all.

Options: --agent, --pluginsDir, --out, --config, --marketplaceName, --ownerName, --ownerEmail, --pluginPrefix, --plugin, --clean.