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
• 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, 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: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

• A Modellix API key from the Console
• 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/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 the Agent Skill (skills/modellix), or when the host has no plugin marketplace.

1) Plugin

Installs the repository root as a plugin (manifests + skills/modellix/).

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 .pi/skills/modellix → skills/modellix for local discovery.

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

Installs only skills/modellix (Agent Skill). 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
npx skills add https://github.com/Modellix/modellix-plugin --skill modellix --agent cursor   # one agent

Update:

npx skills update

ClawHub / OpenClaw (skill)

Slug modellix (skill registry; separate from the @modellix/modellix-plugin package above).

Install:

clawhub install modellix
# or
openclaw skills install modellix

Update:

clawhub update modellix
# 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 → skills/modellix.

Install:

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix

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

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

Update:

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

In OpenCode, load with skill({ name: "modellix" }).

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 --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
# Pi also scans ~/.agents/skills/

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

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
# or from skills.sh (when listed):
# hermes skills install skills-sh/Modellix/modellix-plugin/modellix

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

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

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.

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:

To discover or inspect other models:

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

Request-body schemas come from each model’s docs (prefer the plugin Docs MCP when connected; otherwise docs_url from model describe, or links in llms.txt).

Execution guidance

1. Run skills/modellix/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).
2. Do not hand-roll task get polling loops when model run --wait or task wait is available.
3. Do not blindly retry a paid model run after an unknown submission outcome — check modellix-cli task history first.
4. 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.
5. 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:

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/scripts/.

Slash commands

Hosts that support the packaged command adapters expose seven shortcuts. Commands are outside the Agent Plugins 1.0.0 core; each routes to the same modellix-cli workflow the skill teaches and adds no separate runtime:

The three paid commands (image, video, audio) set disable-model-invocation: true, so only a human can trigger them; the read-only four can also be called by the agent. Hosts without command support (Pi, Hermes, OpenCode, the ClawHub skill bundle) ignore commands/ and keep using the skill.

Supported task types

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 (: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       # Symlink → skills/modellix (OpenCode skill discovery)
├── .pi/skills/modellix             # Symlink → skills/modellix (Pi local skill discovery)
├── .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/                   # Skill package (SKILL.md, scripts, references, assets, evals)
└── .github/workflows/              # Publish sync (Smithery / skills add / ClawHub)

skills/modellix/ is discovered from the fixed Agent Plugins skills/ location without a manifest path field. Pi uses package.json#pi.skills; Hermes installs the skill tree only (no Hermes-specific plugin manifest).

Maintaining this plugin

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

Current version: see plugin.json (kept in sync with host manifests and skills/modellix/skill.json).

Links

• Product: modellix.ai
• Docs: docs.modellix.ai
• Models index: llms.txt
• Plugin guide: ways-to-use/plugin
• Agent skill guide: ways-to-use/skill
• Docs MCP: ways-to-use/mcp (endpoint)
• REST API: ways-to-use/api
• CLI package: npmjs.com/package/modellix-cli
• Plugin package: npmjs.com/package/@modellix/modellix-plugin
• Pricing: get-started/pricing
• Support: [email protected]
• Community: Discord