Modellix Plugin

Agent plugin for Modellix, a unified Model-as-a-Service (MaaS) platform for image, video, and audio workflows.

This repository conforms to the Agent Plugins 1.0.0 specification: root plugin.json is the portable manifest, skills/ is the fixed skill location, and root mcp.json declares the portable Docs MCP. Cursor, Claude Code, Codex, OpenClaw, OpenCode, Pi, and Hermes adapters remain alongside that core for hosts with additional or legacy capabilities.

Official install guide: docs.modellix.ai/ways-to-use/plugin.

What this plugin provides

CLI-first workflow: automatic latest-version preflight → modellix-cli doctor → model run --wait → task download
Image prompt engineering for covers, posters, infographics, mockups, edits, and coherent asset sets before execution
REST fallback when the CLI is unavailable
Default models when the user does not specify one
Model discovery via modellix-cli model list / model describe / model get-schema, plus live docs at llms.txt
Optional Docs MCP (mcp.json, plus host adapter .mcp.json → docs.modellix.ai/mcp) for searching and reading official documentation — not for running generation tasks
Slash commands under commands/: /modellix:prompt, /modellix:image, /modellix:video, /modellix:audio, /modellix:doctor, /modellix:models, /modellix:tasks, /modellix:download
Persistent host rules under rules/ (.mdc): CLI-first defaults, paid-submit safety, credential/docs guardrails
Optional hooks under hooks/: confirm before a repeated paid submit or an unbounded model batch, and remind the agent to download results before they expire
Retry and error guidance aligned with CLI exit codes and paid-submit safety
Credential handling for MODELLIX_API_KEY and CLI auth profiles

Requirements

Prompt preparation needs no credential. Generation and authenticated API/CLI operations need a Modellix API key from the Console or a saved CLI profile.
modellix-cli requires Node.js 18.17+; the plugin preflight installs or refreshes it automatically from the public npm latest tag
Python 3.10+ for automatic CLI preflight and optional hooks; direct CLI/REST use remains available when Python is unavailable

python3 skills/modellix-design/scripts/preflight.py --json

Preflight checks the installed version, upgrades only to a newer exact public npm version, then runs doctor. Registry/install failure keeps a working installed CLI; if no CLI is usable it recommends REST when MODELLIX_API_KEY is available. Set MODELLIX_CLI_AUTO_UPDATE=0 only when an environment must pin its installed CLI.

Install and update

After install, use an existing authenticated CLI profile or set MODELLIX_API_KEY (see Setup).

Prefer Plugin when the host supports Agent Plugins or marketplace plugins. Use Skill when you only need execution (skills/modellix-design) or image prompt engineering (skills/modellix-image-prompt-engineering), or when the host has no plugin marketplace.

1) Plugin

Installs the repository root as a plugin, including both skills under skills/.

npm / npx

The public npm package contains the complete portable plugin bundle. For Cursor, the installer copies it into Cursor's local-plugin directory:

npx --yes @modellix/modellix-plugin@latest install --host cursor

# update an existing npm-installed local plugin; the previous directory is kept as a backup
npx --yes @modellix/modellix-plugin@latest install --host cursor --force

For another Agent Plugins-compatible host, materialize a versioned bundle and point the host's local-plugin flow at that directory:

npx --yes @modellix/modellix-plugin@latest install --host portable --target ./modellix-plugin

Plain npm install @modellix/modellix-plugin only downloads the package into node_modules; it does not register the plugin with every host. Prefer the host-specific marketplace commands below when available. Pi and OpenClaw can consume the npm package directly through their own package installers.

Claude Code

Install:

/plugin marketplace add Modellix/modellix-plugin
/plugin install modellix@modellix

Update:

/plugin marketplace update modellix
/plugin update modellix@modellix

Or use the /plugin UI, then /reload-plugins if needed.

Local development:

claude --plugin-dir /path/to/modellix-plugin
claude plugin validate /path/to/modellix-plugin

Codex

Install:

codex plugin marketplace add Modellix/modellix-plugin
# then install modellix from /plugins

Update: re-open /plugins and update, or re-add the marketplace and reinstall.

Cursor

Official Marketplace (after approval):

/add-plugin modellix

GitHub or local checkout: open Customize → Plugins → + Add, choose this repository, then install Modellix from the modellix marketplace declared in .cursor-plugin/marketplace.json.

For symlink-based development:

git clone https://github.com/Modellix/modellix-plugin.git
ln -sfn "$PWD/modellix-plugin" ~/.cursor/plugins/local/modellix
# Developer: Reload Window — confirm under Customize

Update:

git -C ~/.cursor/plugins/local/modellix pull   # when the symlink points at a clone
# Developer: Reload Window

OpenClaw (bundle plugin)

ClawHub package @modellix/modellix-plugin — plugin content/skill bundle (not a TypeScript runtime plugin).

Install:

openclaw plugins install npm:@modellix/modellix-plugin

# or from ClawHub
openclaw plugins install clawhub:@modellix/modellix-plugin

# local / git
openclaw plugins install .
openclaw plugins install git:github.com/Modellix/modellix-plugin

Update npm installs with openclaw plugins update npm:@modellix/modellix-plugin. Reinstall from the same ClawHub/git/path source for other installs (or git pull if you linked a local checkout).

Pi (package)

Pi loads this repo as a Pi package (skills only — not an Agent Plugins marketplace client). package.json declares pi-package and pi.skills; the repo also exposes matching .pi/skills/* symlinks for both skills.

Install:

pi install npm:@modellix/modellix-plugin
# or
pi install git:github.com/Modellix/modellix-plugin
# or
pi install https://github.com/Modellix/modellix-plugin
# local checkout
pi install /path/to/modellix-plugin

Update:

pi update --extensions
# or update only the npm package:
pi update npm:@modellix/modellix-plugin
# or pin/move ref:
pi install git:github.com/Modellix/modellix-plugin

2) Skill

Install either Agent Skill independently. modellix-design executes image, video, and audio workflows. modellix-image-prompt-engineering prepares image prompts and hands generation back to modellix-design. Useful for skills.sh, ClawHub skills, OpenCode, Pi, Hermes, Smithery, or Cursor skill-only installs.

Agent Skills (skills.sh) — any host

Install:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-design
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-image-prompt-engineering
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-design --agent cursor   # one agent

Update:

npx skills update

ClawHub / OpenClaw (skill)

Only modellix-design is currently published as a standalone ClawHub skill (skill registry; separate from the @modellix/modellix-plugin package above). Install the prompt skill from the GitHub repository or as part of the complete plugin.

Install:

clawhub install modellix-design
# or
openclaw skills install modellix-design

Update:

clawhub update modellix-design
# or
clawhub update --all

OpenCode

OpenCode’s plugins are JS/TS event hooks — Modellix does not use that path. Use Agent Skills instead. This repo exposes .opencode/skills/modellix-design and .opencode/skills/modellix-image-prompt-engineering as symlinks to the canonical skill trees.

Install:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-design
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-image-prompt-engineering

# Global
mkdir -p ~/.config/opencode/skills
ln -sfn /path/to/modellix-plugin/skills/modellix-design ~/.config/opencode/skills/modellix-design
ln -sfn /path/to/modellix-plugin/skills/modellix-image-prompt-engineering ~/.config/opencode/skills/modellix-image-prompt-engineering

# Project-local
mkdir -p .opencode/skills
ln -sfn /path/to/modellix-plugin/skills/modellix-design .opencode/skills/modellix-design
ln -sfn /path/to/modellix-plugin/skills/modellix-image-prompt-engineering .opencode/skills/modellix-image-prompt-engineering

Update:

npx skills update
# or, for a symlink install:
git -C /path/to/modellix-plugin pull

In OpenCode, load with skill({ name: "modellix-design" }) or skill({ name: "modellix-image-prompt-engineering" }).

Cursor (skill-only)

When you want the skill without installing the full Cursor plugin:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-design --agent cursor
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-image-prompt-engineering --agent cursor
npx skills update

Smithery

Install:

npx @smithery/cli@latest skill add modellix/modellix-skill
npx @smithery/cli@latest skill add modellix/modellix-skill --agent cursor

Update: re-run the same skill add command (or your Smithery client’s update flow).

Pi (skill-only)

Prefer the Pi package install above. Skill-only alternatives:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-design
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix-image-prompt-engineering
# Pi also scans ~/.agents/skills/

# or symlink the skill tree
mkdir -p ~/.pi/agent/skills
ln -sfn /path/to/modellix-plugin/skills/modellix-design ~/.pi/agent/skills/modellix-design
ln -sfn /path/to/modellix-plugin/skills/modellix-image-prompt-engineering ~/.pi/agent/skills/modellix-image-prompt-engineering

Hermes Agent

Hermes consumes the Agent Skill (SKILL.md) rather than the full plugin package. Short listing blurb: Unified API for AI image, video, and audio workflows.

Install:

hermes skills install Modellix/modellix-plugin/skills/modellix-design
hermes skills install Modellix/modellix-plugin/skills/modellix-image-prompt-engineering
# or from skills.sh (when listed):
# hermes skills install skills-sh/Modellix/modellix-plugin/modellix-design

# copy / symlink into the Hermes skills tree
mkdir -p ~/.hermes/skills
ln -sfn /path/to/modellix-plugin/skills/modellix-design ~/.hermes/skills/modellix-design
ln -sfn /path/to/modellix-plugin/skills/modellix-image-prompt-engineering ~/.hermes/skills/modellix-image-prompt-engineering

To reuse a shared Agent Skills directory, add under skills in ~/.hermes/config.yaml:

skills:
  external_dirs:
    - ~/.agents/skills

Update: re-run hermes skills install ..., or git pull on a symlink checkout. After install, start a new session and invoke /modellix (or load the skill via Hermes skill tools). Set MODELLIX_API_KEY in the environment or ~/.hermes/.env.

Setup

Item	Value
Primary credential / env	`MODELLIX_API_KEY`
Console	https://modellix.ai/console/api-key

export MODELLIX_API_KEY="your_api_key"

REST requires MODELLIX_API_KEY.
CLI may use the env var or a saved profile (modellix-cli auth login / init).
In Cursor, the key can also be set as the MODELLIX_API_KEY plugin variable.
In Hermes, prefer ~/.hermes/.env or a session environment variable.
Prefer session-only keys; persist only when you explicitly ask for it.
Never commit API keys or print them in logs.

Key resolution order in the CLI: --api-key → MODELLIX_API_KEY → selected saved profile.

Image prompt workflow

For a vague image request, first use skills/modellix-image-prompt-engineering/. It turns the idea into a T2I or I2I brief with a final prompt, on-image text language, aspect/size, and reference-image roles. It does not authenticate or submit work.

If the user asked only for a prompt, stop there. If they asked for a generated or edited image, pass the brief to skills/modellix-design/, which owns model schema checks, credentials, paid-submit safety, waiting, and download. A complete prompt that the user explicitly marked final can go directly to modellix-design.

Quick start (CLI)

modellix-cli doctor --json

modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json

modellix-cli task download <task_id> --output-dir ./outputs --json

If task download fails with a private/reserved network error (common behind local proxies that map CDN hosts into 198.18.0.0/15), retry with --allow-private-network for trusted Modellix CDN hosts, or download the resource URL with curl.

model invoke remains a compatibility alias of model run. Prefer model run in new scripts.

Default models

Used when the user does not name a model:

Task type	Default model slug
Text-to-image (T2I)	`google/nano-banana-2-lite`
Text-to-video (T2V)	`bytedance/seedance-2.0-mini-t2v`
Image editing / I2I	`google/nano-banana-2-lite-edit`
Image-to-video / I2V	`bytedance/seedance-2.0-fast-i2v`
Video-to-video (V2V)	`bytedance/seedance-2.0-fast-v2v`
Text-to-speech (TTS)	`alibaba/qwen-audio-3.0-tts-flash`
Speech-to-text (STT)	`openai/whisper-1`
Speech-to-speech (STS)	`alibaba/cosyvoice-clone`

To discover or inspect other models:

modellix-cli model list --type text-to-image --output slugs
modellix-cli model describe <provider/model> --json
modellix-cli model get-schema <provider/model>

Request-body schemas come from modellix-cli model get-schema <slug> (JSON default; public, no API key). If CLI is unavailable, prefer the plugin Docs MCP when connected; otherwise docs_url from model describe, or links in llms.txt.

Execution guidance

Run skills/modellix-design/scripts/preflight.py --json before the first CLI command in a workflow; it refreshes to a newer npm latest release before any paid submit. Prefer the resolved CLI, otherwise use REST (API guide).
Do not hand-roll task get polling loops when model run --wait or task wait is available.
Do not blindly retry a paid model run after an unknown submission outcome — check modellix-cli task history first.
preflight.py owns the automatic update check; invoke_and_poll.py pins the resolved executable for the complete submit/wait/download workflow. Update failure retains an existing CLI and never triggers a paid retry.
CLI behavior source of truth: npm modellix-cli and modellix-cli --help (not the website CLI guide page, which may lag).

Security and data handling

Prompts and public media inputs are sent to https://api.modellix.ai only when a documented generation, editing, transcription, or speech task is invoked. The Docs MCP is read-only and connects only to https://docs.modellix.ai/mcp; it does not receive the API key or submit tasks. Spend-safety hook state contains hashes, model slugs, task ids, and timestamps, never prompts, request bodies, complete commands, or keys. See SECURITY.md and the Modellix Privacy Policy.

Hooks (spend and result safety)

Hosts that support the packaged hook adapters load three lightweight guards. Hooks are outside the Agent Plugins 1.0.0 core; they only react to modellix-cli commands and never change the CLI workflow itself:

Hook	Trigger	Behavior
Run guard	Before a `model run` / `model invoke` / `model batch` shell command	Asks for confirmation when the same paid submit repeats in a session or when `model batch` has no `--max-tasks`; suggests `doctor` when no credential is discoverable
Task watch	After a `modellix-cli` command	Records task ids from the output and clears them once `task download` succeeds
Stop reminder	When the agent tries to finish	Sends one follow-up if tasks were generated but never downloaded (resource URLs expire in about 7 days)

Config lives in hooks/hooks.json (legacy Open Plugins / Claude Code event names) and hooks/cursor-hooks.json (Cursor event names); each host manifest points at exactly one of them, so a host never runs both. Hook logic is Python 3 stdlib only, while scripts/run_python_hook.mjs selects the available Python 3 command across platforms. Per-session state stores command fingerprints, model slugs, and task ids—never prompts or keys—and every hook fails open. Hosts without hook support (Pi, Hermes, OpenCode, Codex) ignore this directory.

Plugin-level scripts/ holds these hook scripts; the CLI/REST helpers used by the skill live in skills/modellix-design/scripts/.

Slash commands

Hosts that support the packaged command adapters expose eight shortcuts. Commands are outside the Agent Plugins 1.0.0 core; each routes to one of the packaged skills and adds no separate runtime:

Command	Use it for
`/modellix:prompt [image idea or existing prompt]`	Prepare an image prompt and brief without submitting
`/modellix:image [prompt] [image url]`	Text-to-image, or image editing when input images are given
`/modellix:video [prompt] [image or video url]`	Text-to-video, image-to-video, or video-to-video
`/modellix:audio [tts\|stt\|sts] [text or audio url]`	Text-to-speech, speech-to-text, or speech-to-speech
`/modellix:doctor [profile]`	CLI install, credential resolution, connectivity, balance
`/modellix:models [term or slug]`	Find a model and its request-body schema
`/modellix:tasks [task id]`	Task status, plus recovery after a timeout or unknown submission
`/modellix:download [task id] [dir]`	Fetch results into `./outputs` before the ~7-day expiry

The three paid commands (image, video, audio) and the user-facing prompt command set disable-model-invocation: true. Hosts without command support (Pi, Hermes, OpenCode, the ClawHub skill bundle) ignore commands/ and keep using the skills.

Supported task types

Type	Description
`text-to-image`	Generate images from text prompts
`image-to-image`	Edit or transform images with text instructions
`text-to-video`	Create videos from text descriptions
`image-to-video`	Convert static images into video sequences
`video-to-video`	Transform existing videos
`text-to-speech`	Synthesize speech from text
`speech-to-text`	Transcribe public audio resources
`speech-to-speech`	Clone or transform a voice from reference audio

Repository structure

.
├── README.md                       # This file (humans)
├── SECURITY.md                     # Credential, network, local-state, and disclosure policy
├── AGENTS.md                       # Maintainer / coding-agent instructions
├── CHANGELOG.md
├── package.json                    # npm + ClawHub OpenClaw + Pi package (@modellix/modellix-plugin)
├── openclaw.plugin.json            # OpenClaw package manifest (skills bundle)
├── plugin.json                     # Agent Plugins 1.0.0 portable manifest
├── mcp.json                        # Agent Plugins 1.0.0 Docs MCP (streamable-http)
├── .mcp.json                       # Cursor/legacy host Docs MCP adapter
├── commands/                       # Slash commands (:prompt, :image, :video, :audio, :doctor, :models, :tasks, :download)
├── rules/                          # Host-extension always-on guardrails (.mdc)
├── hooks/                          # Host adapters: hooks.json (legacy/Claude), cursor-hooks.json (Cursor)
├── scripts/                        # Hook logic (Python stdlib) + cross-platform Node launcher
├── .opencode/skills/modellix-design       # Symlink → skills/modellix-design (OpenCode skill discovery)
├── .opencode/skills/modellix-image-prompt-engineering # Symlink → matching skill tree
├── .pi/skills/modellix-design             # Symlink → skills/modellix-design (Pi local skill discovery)
├── .pi/skills/modellix-image-prompt-engineering       # Symlink → matching skill tree
├── .plugin/plugin.json             # Legacy Open Plugins host adapter
├── .cursor-plugin/
│   ├── plugin.json                 # Cursor manifest (+ optional MODELLIX_API_KEY variable)
│   └── marketplace.json            # Single-repository Cursor marketplace entry
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json            # Claude Code marketplace entry
├── .codex-plugin/plugin.json
├── .agents/plugins/marketplace.json # Codex / vendor-neutral marketplace entry
├── assets/logo.svg
├── tests/                           # Repository and paid-safety regression tests (not packaged)
├── skills/
│   ├── modellix-design/            # Execution skill (CLI/REST, scripts, references, evals)
│   └── modellix-image-prompt-engineering/ # Prompt-only image planning skill
└── .github/workflows/              # Publish sync (Smithery / skills add / ClawHub)

Both immediate skill directories are discovered from the fixed Agent Plugins skills/ location without manifest path fields. Pi uses package.json#pi.skills; Hermes installs skill trees directly (no Hermes-specific plugin manifest).

Maintaining this plugin

See AGENTS.md for sources of truth, update checklists, smoke tests, versioning, and PR conventions.

Current plugin version: see plugin.json (kept in sync with host manifests and skills/modellix-design/skill.json). The prompt-only skill has its own version in skills/modellix-image-prompt-engineering/skill.json.

Navigation Menu

Repository files navigation

Modellix Plugin

What this plugin provides

Requirements

Install and update

1) Plugin

npm / npx

Claude Code

Codex

Cursor

OpenClaw (bundle plugin)

Pi (package)

2) Skill

Agent Skills (skills.sh) — any host

ClawHub / OpenClaw (skill)

OpenCode

Cursor (skill-only)

Smithery

Pi (skill-only)

Hermes Agent

Setup

Image prompt workflow

Quick start (CLI)

Default models

Execution guidance

Security and data handling

Hooks (spend and result safety)

Slash commands

Supported task types

Repository structure

Maintaining this plugin

Links

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.cursor-plugin		.cursor-plugin
.github/workflows		.github/workflows
.opencode/skills		.opencode/skills
.pi/skills		.pi/skills
.plugin		.plugin
assets		assets
commands		commands
hooks		hooks
rules		rules
scripts		scripts
skills		skills
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
mcp.json		mcp.json
openclaw.plugin.json		openclaw.plugin.json
package.json		package.json
plugin.json		plugin.json

Latest commit

History

Folders and files

Repository files navigation

Modellix Plugin

What this plugin provides

Requirements

Install and update

1) Plugin

npm / npx

Claude Code

Codex

Cursor

OpenClaw (bundle plugin)

Pi (package)

2) Skill

Agent Skills (skills.sh) — any host

ClawHub / OpenClaw (skill)

OpenCode

Cursor (skill-only)

Smithery

Pi (skill-only)

Hermes Agent

Setup

Image prompt workflow

Quick start (CLI)

Default models

Execution guidance

Security and data handling

Hooks (spend and result safety)

Slash commands

Supported task types

Repository structure

Maintaining this plugin

Links

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages