Plugins and marketplaces

A plugin is a folder that bundles things o4 can use: slash commands, skills, subagent definitions, workflows, and, in some formats, MCP servers. Install a plugin to share a team’s commands and skills, or to use a set someone else has published. A marketplace is a catalog of plugins that you can install by name.

Install a plugin

Install from a local folder, a GitHub repository, or any git URL:

o4 plugin install ./team-tools
o4 plugin install acme/o4-team-tools
o4 plugin install https://git.example.com/acme/o4-team-tools.git

owner/repo is short for https://github.com/owner/repo.git. o4 clones the repository or copies the folder into its plugins folder:

$ o4 plugin install ./team-tools
Installed plugin 'team-tools' v1.0.0 (1 commands, 1 agents, 1 skills)

The plugin’s commands show up as slash commands, and its skills and agents become available to the model. A plugin you install with o4 plugin install loads in your next session. A plugin you install from /plugins in a session is available in that session right away. o4 then restarts your MCP servers, so the plugin’s MCP servers start too.

A plugin can give the model new instructions and can start programs on your machine. Install plugins only from sources you trust.

Global and project plugins

By default a plugin is installed globally, in ~/.o4/plugins, and is available in every workspace. Use --project to install it into the current project’s .o4/plugins instead:

o4 plugin install --project ./team-tools

Project plugins only load in a trusted workspace, and --project refuses to install into an untrusted one. Run o4 trust in the project first. See Workspace trust. You can have the same plugin in both places. They’re listed separately.

List and remove plugins

$ o4 plugin list
team-tools v1.0.0 [global] — Shared commands and skills for our team
team-tools v1.0.0 [project] — Shared commands and skills for our team

o4 plugin list also warns when the current project has plugins that aren’t loaded because the workspace isn’t trusted.

o4 plugin remove team-tools

o4 plugin remove removes the project copy if there is one, and otherwise the global one. It also removes any permissions you granted the plugin.

Marketplaces

A marketplace is a git repository or folder with a marketplace.json catalog. Register one, and you can install its plugins by name:

o4 plugin marketplace add acme/o4-marketplace
o4 plugin install hello

If two marketplaces list a plugin with the same name, pick one with name@marketplace:

o4 plugin install hello@acme

Command	What it does
`o4 plugin marketplace add <source>`	Register a marketplace from `owner/repo`, a git URL, or a local folder
`o4 plugin marketplace list`	List registered marketplaces and how many plugins each has
`o4 plugin marketplace refresh [name]`	Fetch the latest catalog for one marketplace, or all of them
`o4 plugin marketplace remove <name>`	Unregister a marketplace

o4 keeps marketplace data in ~/.o4/marketplaces. On the first interactive launch, if you haven’t registered any marketplaces, o4 tries once to register an official marketplace. If that fails, for example because you’re offline, o4 doesn’t try again, and you can add marketplaces yourself.

Create a marketplace

Put a marketplace.json at the root of a repository or folder, or in .o4-plugin/marketplace.json:

{
  "name": "acme",
  "description": "Acme's internal plugins",
  "owner": { "name": "Acme" },
  "plugins": [
    {
      "name": "hello",
      "source": "./plugins/hello",
      "description": "A /hello command",
      "version": "1.0.0",
      "category": "examples",
      "tags": ["starter"]
    }
  ]
}

Each plugin’s source is one of:

A path inside the marketplace that starts with ./, for a plugin kept in the same repository. The path can’t lead outside the marketplace.
owner/repo, for a plugin in its own GitHub repository.
A full git URL.
A path to a folder elsewhere on your machine, only in a marketplace you added from a local folder.

The marketplace needs a name, and each plugin entry needs a name and a source. The Discover tab of /plugins shows each plugin’s description and category, and its filter searches them along with the plugin and marketplace names. owner, if present, needs a name and can have a url, but o4 doesn’t show it. A plugin entry’s version and tags are accepted but not used.

Manage plugins in a session

/plugins opens the plugin browser. It has four tabs:

Discover: plugins from your marketplaces. Select one to install it.
Installed: your plugins. Select one to update it (pull the latest changes from its source), validate its files, remove it, or revoke a saved capability grant (the granted: rows). Parts of the plugin that were skipped are listed as disabled component rows. The first row, Install plugin, installs from a git URL, owner/repo, or path, globally or for the project.
Marketplaces: your marketplaces. Add, refresh, or remove them here.
Errors: plugins or plugin files that failed to load, with the reason.

You can also go straight to an action with a subcommand:

Command	What it does
`/plugins` or `/plugins list`	Open the plugin browser
`/plugins install`	Open the Install plugin form
`/plugins install <source> [--project]`	Install a plugin by marketplace name, `owner/repo`, git URL or path
`/plugins update <name>`	Pull the latest version of a plugin installed from git
`/plugins remove <name>`	Remove a plugin
`/plugins validate [name]`	Check one plugin’s files, or all plugins’, for errors
`/plugins new <name>`	Create a plugin skeleton in the project’s `.o4/plugins`
`/plugins marketplace` or `/plugins marketplace list`	List your marketplaces
`/plugins marketplace add <source>`	Register a marketplace
`/plugins marketplace refresh [name]`	Refresh marketplace catalogs
`/plugins marketplace remove <name>`	Unregister a marketplace

A plugin copied from a local folder can’t be updated. Install it again to pick up changes. While the model is working, you can still open the browser, validate plugins and revoke grants, but installing, updating or removing a plugin and refreshing or removing a marketplace are refused: o4 closes the browser and shows Wait for the current turn to finish before making this change. Typed commands that change plugins, such as /plugins install <source> and /plugins remove <name>, wait for the turn to finish instead. The Plugins tab in /config (run /config plugins to go straight to it) has one row, Open plugin browser. It opens the same plugin browser as /plugins. The browser starts on Discover, or on Installed when you have plugins, and returns to the tab you last used in the session.

What a plugin can contain

Folder	What it adds
`commands/`	Slash commands, one Markdown file each
`skills/`	Skills, one folder with a `SKILL.md` each. See Skills.
`agents/`	Subagent definitions, one Markdown file each. See Subagents.
`workflows/`	Workflows that run several commands in stages, as `.yaml` or `.yml` files
`tools/`	Tools the model can call, defined in Markdown files

A plugin’s skills can include hooks in their front matter; those run while the skill is active (see Hooks in skills). Plugins in the portable, Codex, Claude Code, and Cursor formats can also declare MCP servers. See Plugin formats. o4 reads at most 256 files from each component folder, and 256 plugins from each plugins folder. A file that fails to load is listed on the Errors tab of /plugins; the rest of the plugin still loads. Print mode (o4 -p) doesn’t load plugin commands, skills, subagents or tools. It does start the MCP servers that plugins declare.

Commands

A command is a Markdown file in commands/. The file name is the command name, unless the front matter sets name:

---
description: Draft a changelog entry for the current branch
argument-hint: "[version]"
---
Draft a changelog entry for version $ARGUMENTS from the commits on this branch.

When you run /changelog 2.4.0, o4 sends the body to the model, with these replaced:

Placeholder	Replaced with
`$ARGUMENTS`	The text after the command
`$CWD`	The current working directory
`$O4_PLUGIN_ROOT`	The plugin’s folder

Built-in slash commands and your own skills take precedence over a plugin’s commands with the same name.

Workflows

A workflow runs a plugin’s commands one after another as stages. Define it in workflows/<name>.yaml:

schema: 1
name: release
description: Prepare and check a release
entry: plan
stages:
  - plan
  - build
  - verify
commands:
  plan: release-plan
  build: release-build
  verify: release-verify
agents: {}
state:
  path: .o4/state/plugins/team-tools/release

commands maps each stage to one of the plugin’s commands. entry is the command for the first stage if commands doesn’t list one. agents can map a stage to one of the plugin’s agents, whose instructions are used for that stage. When state.path is set, o4 saves the workflow’s progress there, so a later run continues from the next stage. The path must be inside .o4/state/plugins/<plugin-name>/. Run workflows with /workflow:

/workflow list
/workflow run release 2.4.0
/workflow run release --stage verify

--stage starts from a given stage. Text after the workflow name (and the stage) is passed to each stage’s command as $ARGUMENTS.

Tools

A plugin tool is a Markdown file in tools/ whose YAML front matter defines a tool the model can call. The body of the file isn’t used.

---
name: count-lines
description: Count the lines in a file of this project
parameters:
  type: object
  properties:
    path:
      type: string
  required: [path]
binding:
  type: command
  argv-template: ["wc", "-l", "{path}"]
  timeout-ms: 10000
---

Field	Meaning
`name`	The tool’s name. Required, and unique within the plugin.
`description`	What the model sees about the tool.
`parameters`	A JSON Schema for the tool’s input, with `type: object`. Required.
`binding`	What happens when the model calls the tool. See below.
`required-grants`	Capabilities the tool needs: `exec`, `network`, `path:<path>` or `tool:<name>`.

A binding has one of two types:

command runs a program. argv-template is the program and its arguments; each {parameter} in them is replaced with the value the model passed. o4 runs the program directly, not through a shell, in o4’s sandbox, from the plugin’s folder, with a minimal environment. The program must be inside the plugin’s folder or in /usr/bin, /bin, /usr/sbin or /sbin. timeout-ms defaults to 30000. The tool returns the program’s standard output, or its standard error if it fails.
template returns text, with each {parameter} replaced, without running anything.

A tool with the same name as a built-in tool, or as a tool from another plugin, isn’t loaded.

Approving plugin tools

o4 asks for your approval each time the model calls a plugin tool. A tool also needs each capability it uses; a command tool always needs exec. The first time, o4 asks you to grant the capability to the plugin: allow it once (y), allow it always (a), or deny it (n). An “always” grant is saved in ~/.o4/settings.json and tied to the plugin’s current files, so o4 asks again after the plugin is updated or changed. To revoke a grant, open the plugin in /plugins; each saved grant is listed as a granted: row that you can select to revoke. See Permissions. The sandbox blocks the program’s network access unless the tool has the network grant, and exec alone doesn’t let it write files. In o4 0.2.74, a tool that requires a path: grant always fails with “plugin path capabilities are disabled”.

Create a plugin

/plugins new team-tools creates a starter plugin in .o4/plugins/team-tools with a manifest, a /main command, a main workflow, and a README. o4 lowercases the name and turns other characters into -. The plugin loads right away. Edit the files, then start a new session to load your changes. The workspace must be trusted, because project plugins only load there. To build one by hand, make a folder with a manifest and any of the component folders:

team-tools/
  .o4-plugin/
    plugin.json
  commands/
    changelog.md
  skills/
    deploy-check/
      SKILL.md
  agents/
    reviewer.md

The manifest, .o4-plugin/plugin.json:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Shared commands and skills for our team",
  "author": "Platform team"
}

name and version are required. The name can use letters, digits, ., _, and -, up to 128 characters. author can be a string or an object with a name. The manifest can also have capabilities and permissions:

{
  "name": "team-tools",
  "version": "1.0.0",
  "capabilities": { "commands": true, "skills": true },
  "permissions": {
    "tools": ["read", "grep", "bash"],
    "paths": [],
    "network": false
  }
}

capabilities lists what the plugin provides, as true or false for commands, agents, skills, workflows, state, ui and hooks. It’s descriptive only: it doesn’t turn anything on or off.
permissions limits what the plugin’s parts may use. A command whose allowed-tools, a subagent whose tools, or a skill whose allowed-tools names a tool outside permissions.tools isn’t loaded. A plugin tool whose required-grants asks for a tool outside permissions.tools, a path outside permissions.paths, or the network when network is false, isn’t loaded either. Each skipped part is listed on the Errors tab and as a disabled component row in the plugin’s details in /plugins, and o4 plugin list prints a warning for it. Tool names match without regard to case or punctuation.

Without permissions, none of these checks apply. o4 reads capabilities and permissions only from .o4-plugin/plugin.json. Install it from its folder to test it:

o4 plugin install ./team-tools

To share it, push the folder to a git repository and install it with o4 plugin install owner/repo, or list it in a marketplace.

Plugin formats

o4 looks for a manifest in this order and uses the first one it finds:

Manifest	Format
`.o4-plugin/plugin.json`	o4’s own format
`plugin.json` with a `$schema` from `agent-plugins.org`	The portable Agent Plugins format
`.codex-plugin/plugin.json`	Codex plugins
`.claude-plugin/plugin.json`	Claude Code plugins
`.cursor-plugin/plugin.json`	Cursor plugins

So you can often install a plugin written for another agent as is. The portable format is stricter than o4’s own:

$schema must be https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. o4 refuses other schema versions with unsupported Agent Plugins schema.
name can use lowercase letters, digits, . and -, up to 64 characters. It must start and end with a letter or digit, and can’t contain -- or ...
version is optional. o4 lists a plugin without one as unversioned.
author must be an object with only name, email and url.
version, description, author and homepage can’t be null.

The Codex, Claude Code, and Cursor manifests can point to skill folders with skills and to an MCP configuration with mcpServers. These paths must start with ./ and stay inside the plugin folder, or o4 refuses the plugin. mcpServers can also list the servers inline. MCP servers from plugins come from the portable format, which reads them from mcp.json in the plugin folder, and from the other agents’ formats, which read the manifest’s mcpServers, or .mcp.json in the plugin folder when the manifest has none. A plugin’s MCP servers start with your own servers. If a server in your .mcp.json has the same name, yours is used. See MCP servers.

Get started

Using o4

Planning and agents

Models

Safety

Customize

Extend

Help

Plugins and marketplaces

Install a plugin

Global and project plugins

List and remove plugins

Marketplaces

Create a marketplace

Manage plugins in a session

What a plugin can contain

Commands

Workflows

Tools

Approving plugin tools

Create a plugin

Plugin formats

​Install a plugin

​Global and project plugins

​List and remove plugins

​Marketplaces

​Create a marketplace

​Manage plugins in a session

​What a plugin can contain

​Commands

​Workflows

​Tools

​Approving plugin tools

​Create a plugin

​Plugin formats

Install a plugin

Global and project plugins

List and remove plugins

Marketplaces

Create a marketplace

Manage plugins in a session

What a plugin can contain

Commands

Workflows

Tools

Approving plugin tools

Create a plugin

Plugin formats