plugin.json is the portable manifest, skills/ is the skill location, and root mcp.json declares the MCP servers. Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, and Hermes use host adapters on that core.
For a visual Excalidraw workspace with image prepare/confirm, HTML drafts, and presentations, see Agent Canvas.
Plugin or Skill
Skill-only install steps are on the Skill page.
npx skills add can install modellix-design or modellix-image-prompt-engineering on its own. The other skills ship with the plugin and with a checkout of this repository.Skills
Planning skills write prompts and stop there. They hand generation tomodellix-design. They do not choose a model, authenticate, or submit a task.
modellix-ffmpeg and modellix-moviepy do not call Modellix and do not read MODELLIX_API_KEY. Each skill has a check script that reports whether the local tool is usable and prints an install command. The script does not install FFmpeg, moviepy, or Pillow.
ffmpeg command or moviepy import. When ok is false, the agent shows install_command and waits for you to confirm.
Requirements
- Prompt preparation needs no credential. Generation needs a Modellix API key from the Modellix Console, or a saved CLI profile.
modellix-cli0.0.11 or later on Node.js 18.17 or later. Preflight installs or refreshes it from the public npmlatesttag before the first paid CLI command.- Python 3.10 or later for preflight and optional hooks. Direct CLI and REST calls still work when Python is unavailable.
- FFmpeg (
ffmpegandffprobe, withlibx264andaac) only formodellix-ffmpeg. - moviepy 2.x and Pillow only for
modellix-moviepy.
latest, upgrades only to a newer exact version, then runs doctor. A registry or install failure keeps a working CLI. If no CLI is usable and MODELLIX_API_KEY is set, it recommends REST. Set MODELLIX_CLI_AUTO_UPDATE=0 when an environment must keep its current CLI version.
Install as a Plugin
- npm
- Claude Code
- Codex
- Cursor
- OpenClaw
- Pi
The public npm package Update an npm-installed local plugin. The previous directory is kept as a backup:For another host, materialize a versioned bundle and point that host’s local plugin flow at the directory:Plain
@modellix/modellix-plugin contains the portable plugin. For Cursor, the installer copies it into the local plugin directory:npm install @modellix/modellix-plugin only downloads the package into node_modules. It does not register the plugin with a host. Pi and OpenClaw can install the npm package through their own installers, shown in the tabs below.Install as a Skill
When you want one skill without the rest of the plugin, install it from skills.sh:modellix-design runs generation. modellix-image-prompt-engineering only prepares image prompts and hands generation back to modellix-design. Installing modellix-design alone does not include the other skills. The Skill guide covers Cursor, OpenCode, Pi, and Hermes installs.
Configure Your API Key
Generation and authenticated CLI or REST calls read the same credential. Prompt-only skills do not.--api-key, then MODELLIX_API_KEY, then the selected saved profile.
- REST calls require
MODELLIX_API_KEY. - The CLI can use the environment variable or a saved profile created by
modellix-cli auth loginormodellix-cli init. - In Cursor, you can set the key as the
MODELLIX_API_KEYplugin variable for CLI and REST calls. - In Hermes, prefer
~/.hermes/.envor the session environment.
The Cursor
MODELLIX_API_KEY variable does not automatically become the Bearer header for Media Generation or Web Tools. See Media Generation, Docs Search, and Web Tools.
Verify the Install
Confirm the environment first, then generate one asset end to end. Name theprovider/model slug yourself. The plugin does not substitute one.
1
Check the CLI and Credentials
doctor reports the Node.js version, the API-key source, API connectivity, and your team balance without printing the key.2
Ask Your Agent to Generate Something
3
Confirm the Output
The agent downloads results into your working directory. To reproduce the CLI flow manually:
Supported Task Types
Model Selection
You name theprovider/model slug. If you leave it out, the agent asks which model to run and waits. It does not pick a slug from a built-in list.
modellix-cli model get-schema (JSON is the default; the endpoint is public and does not need an API key). On the Media Generation path the agent calls modellix_get_schema with the same slug. See the CLI schema command.
If neither the CLI nor Media Generation is available, the plugin uses Docs Search when connected, then docs_url from model describe, or the model page in llms.txt. The Skill guide covers when the agent fetches the schema.
How the Plugin Runs Tasks
- When Media Generation tools are available and the input is not a local file, it submits once with
modellix_submit_task. - Otherwise it runs
skills/modellix-design/scripts/preflight.pybefore the first CLI command, thenmodellix-cli model run --waitandtask download. - It uses the REST API only when Media Generation and the CLI are both unavailable.
- It reads the request schema before a non-trivial submit, and skips that call when you already supplied a complete body.
- It uses
modellix_wait_task,model run --wait, ortask waitinstead of a hand-written polling loop. - It does not retry a paid submit after an unknown outcome, and it does not start a second path for the same request. It checks
modellix_get_taskormodellix-cli task historyfirst. - It may use the helpers in
skills/modellix-design/scripts/. If a helper fails, it falls back to plain CLI commands. - It treats
modellix-cli --helpand the npm package as the source of truth for CLI flags.
Slash Commands
Hosts that load the packaged commands expose sixteen shortcuts. Each command routes to a skill and adds no separate runtime. Pi, Hermes, and OpenCode ignorecommands/.
The planning commands and the paid commands
image, video, and audio set disable-model-invocation: true, so only you can trigger them. doctor, models, tasks, and download stay available to the agent.
Hooks
Hosts that load the packaged hook adapters run lightweight guards. Hooks never submit, poll, or download on their own. Pi, Hermes, OpenCode, and Codex ignorehooks/.
Hook logic fails open. Session state stores command fingerprints, model slugs, and task IDs. It does not store prompts, request bodies, or API keys.
Troubleshooting
Next Steps
Skill
Install
modellix-design or the image prompt skill on its own.CLI
Learn the
modellix-cli commands the plugin runs.REST API
Call Modellix directly without the CLI.
Media Generation
Submit image, video, and speech tasks when the plugin’s Media Generation tools are available.
Docs Search
Search these docs from the plugin’s Docs Search server.
Web Tools
Search the public web and fetch public URLs.
Pricing
Review model pricing before running paid tasks.