plugin-forge

plugin-forge

English | 한국어 | 日本語 | 简体中文 | 繁體中文 | Español | Français | Deutsch | Português | Русский | Italiano

Multi-host plugin manager — Claude Code · Codex · agy · hermes. Scaffold, doctor, install-validate, and publish plugins from one engine.

Born from the manifest juggling in toefl-prep and byoh: every plugin needs 5+ manifests (root plugin.json for agy, root plugin.yaml for hermes, .claude-plugin/{plugin,marketplace}.json for Claude, .codex-plugin/plugin.json for Codex, plus host-discovery SKILL copies). plugin-forge generates them, validates them, checks local installability, and ships to GitHub + the marketplace.

Commands

Subcommand	What it does
create <name> [--hosts ...]	Scaffold a new plugin with selected hosts' manifests + SKILL + discovery copies
doctor [PATH] [--fix]	Validate manifests, sync host copies, structure check, install dry-run, remote sync
install <PATH> [--host ...]	Validate local installability per host (staging + rollback)
publish [PATH] [--marketplace]	git init + gh repo create + push + tag + marketplace registration

Install

# Claude Code
claude plugin marketplace add epicsagas/plugins
claude plugin install epicsagas@plugin-forge

# Codex
codex plugin marketplace add epicsagas/plugins
codex plugin add epicsagas@plugin-forge

# agy (repo URL, no .git)
agy plugin install https://github.com/epicsagas/plugin-forge
agy plugin enable plugin-forge

# hermes (repo URL)
hermes plugins install https://github.com/epicsagas/plugin-forge
hermes plugins enable plugin-forge

Usage

Cross-platform: runs on Windows / Linux / macOS with any Python 3.8+. Standard library only (no pip installs).

# Scaffold a 4-host plugin
python3 scripts/forge.py create my-plugin --hosts claude,codex,agy,hermes --desc "Does X"

# Check it (manifests, sync, install dry-run, remote)
python3 scripts/forge.py doctor my-plugin/

# Validate local installability
python3 scripts/forge.py install my-plugin/ --host all

# Publish + register in the suite marketplace
python3 scripts/forge.py publish my-plugin/ --marketplace

On Windows use py or python instead of python3. No bash required.

Manifest pattern (toefl-prep / byoh)

File	Host
plugin.json (root)	agy
plugin.yaml (root) + __init__.py	hermes
.claude-plugin/plugin.json	Claude Code
.claude-plugin/marketplace.json	Claude marketplace
.codex-plugin/plugin.json	Codex
.claude/skills/<n>/, .codex/skills/<n>/, .hermes/skills/<n>/	discovery copies

hermes uses a YAML manifest (plugin.yaml) and requires an __init__.py with a register(ctx) entry point — distinct from the JSON manifests of the other three hosts. See the Hermes plugin spec.

Honest limitations

• doctor/install are dry-run — they validate local structure, not actual host CLI load.
• publish never overwrites an existing remote.
• Versions are pinned at create (0.1.0); never invented by doctor/publish.

Updating

plugin-forge itself is versioned at create time (currently 0.1.3). To get the latest:

# Claude Code
claude plugin update plugin-forge

# Codex
codex plugin update plugin-forge

# agy — re-install from the latest remote
agy plugin install https://github.com/epicsagas/plugin-forge
agy plugin enable plugin-forge

# hermes — re-install from the latest remote
hermes plugins install https://github.com/epicsagas/plugin-forge
hermes plugins enable plugin-forge

Check the version:

python3 scripts/forge.py --version

See CHANGELOG.md for changes between releases.

Community