> ## Documentation Index
> Fetch the complete documentation index at: https://moxn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish & Install

> Connect a GitHub repo, publish your plugins to it, and install them in Claude Code

Publishing takes your marketplace's **committed** content and writes it into a GitHub repository, one-way. That repo *is* the installable marketplace — you and your users add it in Claude Code and install plugins from it. Publishing is a deliberate release step, distinct from [the dev loop](/guides/marketplaces/dev-loop), which never touches GitHub.

## Step 1: Connect a GitHub repository

A marketplace publishes to exactly one GitHub repo. Connecting is a **link** — it points your marketplace at the repo as a publish target. It does **not** import the repo's existing contents, so a fresh empty repo is the cleanest choice.

In the Moxn web app, open your marketplace and choose **Connect GitHub Repository**:

<Steps>
  <Step title="Authorize the Moxn GitHub App">
    A one-time authorization grants Moxn permission to write to repositories you select. You control exactly which repos it can access.
  </Step>

  <Step title="Pick the account and repository">
    Choose the installation (personal or org) and the target repo.
  </Step>
</Steps>

Once connected, the marketplace is linked as a publish target — nothing is written yet.

<Note>
  Agents can connect via `marketplaces { action: "connect", marketplaceId, installationId, owner, repo }` after the one-time App install. `marketplaces { action: "installations" }` lists what is reachable.
</Note>

## Step 2: Commit — which is publishing

There is no separate publish step. **Committing writes to GitHub**:

```
marketplaces { action: "commit", marketplaceId: "<uuid>", ref: "main", message: "Ship the greet skill" }
```

With no `writes`, this publishes whatever is currently drafted — which is what you want after an `edit`. Drafts live only in Moxn until this point, so a half-finished change cannot leak to your users.

That "whatever" is branch-wide: it includes drafts other sessions left behind. Read `draftPaths` from `tree` on the same ref before committing without `writes`, or name the files explicitly — see [Create & Author](/guides/marketplaces/authoring#6-commit--which-is-publishing).

Each commit also:

* flattens pending suggestions to their accepted text and **strips every comment marker**, so published files never contain review markup;
* regenerates the Codex and Cursor manifests from your Claude-layout content, so the repo stays installable on all three;
* is compare-and-swapped against the branch head. If someone else pushed in the meantime, you get a conflict decision list (`keep_mine` / `take_theirs` / `supply_merged` / `commit_to_new_branch`) rather than an error — resubmit with a decision.

<Warning>
  Committing to the **default branch is publishing to everyone** who has the plugin installed. To get review first, commit to a branch and open a pull request — see [Create & author](/guides/marketplaces/authoring#working-on-a-branch).
</Warning>

### Knowing where things stand

* `marketplaces { action: "status", branch }` — how far a branch is ahead of / behind the default branch.
* `marketplaces { action: "history", ref, paths }` — published commits, newest first, for a branch or a single file. Read live from GitHub, so a commit someone pushed from their laptop is in it. This is the only history there is: an uncommitted draft has never been a commit and never appears.
* `marketplaces { action: "pre_merge_report", branch }` — advisory findings before a merge.

## Step 3: Install in Claude Code

Your published repo is a standard Claude Code plugin marketplace. Add it, then install a plugin from it:

```
/plugin marketplace add <owner>/<repo>
/plugin install <plugin>@<marketplace>
```

For example, for the `localization` plugin in a marketplace published to `acme/plugins`:

```
/plugin marketplace add acme/plugins
/plugin install localization@acme-plugins
```

The plugin's skills, commands, and agents are now available in the session (run `/reload-plugins` or restart if they don't appear immediately). This is the same repo anyone you share it with can install from.

## Installing in Codex

The same published repo installs in [Codex](https://developers.openai.com/codex/) — Moxn generates the Codex manifests (`.agents/plugins/marketplace.json` and per-plugin `.codex-plugin/plugin.json`) alongside the Claude Code ones on every publish:

```bash theme={null}
codex plugin marketplace add <owner>/<repo>
codex plugin add <plugin>@<marketplace>
```

Your plugin's **skills** load in Codex sessions just like any official plugin — the `SKILL.md` contract (name + description) is shared across both harnesses. Commands and agents are Claude Code concepts today; Codex ignores them.

### Plugin version and description

`codex plugin list` shows each plugin's **version**, read from its `.codex-plugin/plugin.json`. Set your plugin's version and description in Moxn — they're plugin-level metadata, distinct from any component's frontmatter:

The plugin manifest is a file like any other, so you edit it the way you edit a skill:

```
marketplaces {
  action: "edit",
  marketplaceId: "<uuid>",
  writes: [{
    path: "plugins/localization/.claude-plugin/plugin.json",
    contents: "{\n  \"name\": \"localization\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Translation and localization tools\"\n}\n"
  }]
}
```

Edit the **Claude** manifest only. `.codex-plugin/plugin.json` is regenerated from it on every commit — hand-edit it and your next commit overwrites you.

<Note>
  Codex decides staleness from the **version string alone**, so a content change without a bump would be invisible to Codex users forever. Moxn defends against that by stamping a content-derived cachebuster into the generated Codex manifest — `0.1.0+codex.<sha7>` — which changes whenever your content does, whether or not you bump.
</Note>

To ship an update to Codex users: publish, then they run `codex plugin marketplace upgrade <marketplace>`.

## Installing in Cursor

The same repo also installs in [Cursor](https://cursor.com) (2.5+), which has its own plugin marketplace system — Moxn generates the Cursor manifests (root `.cursor-plugin/marketplace.json` and per-plugin `.cursor-plugin/plugin.json`) on every publish:

1. **Add the marketplace**: in the Cursor app, use `/add-plugin` (or **Settings → Customize → Plugins**) with your repo URL — or from the Cursor CLI: `cursor-agent plugin marketplace add https://github.com/<owner>/<repo>`.
2. **Install the plugin**: pick it from the marketplace listing (in-app, or `cursor-agent` → `/plugin` → Marketplace tab). Cursor has no non-interactive install command yet, so this step is interactive.

Your **skills** load and fire in Cursor sessions — the same shared `SKILL.md` contract. Your **agents** use Cursor's subagent format (markdown + `name`/`description` frontmatter), and the plugin's [version and description](#plugin-version-and-description) appear in Cursor's listing the same way they do in Codex.

## Updating a published plugin

Consumers install a **pinned** version — they don't drift as you keep working. To ship an update:

<Steps>
  <Step title="Edit and commit in Moxn">
    Make your changes and commit them. The commit *is* the publish.
  </Step>

  <Step title="Consumers update — BOTH steps">
    ```bash theme={null}
    claude plugin marketplace update <marketplace>
    claude plugin update <plugin>@<marketplace>
    ```

    Then `/reload-plugins` in an open session, or start a new one.

    <Warning>
      The first command alone is not enough, and it looks like it worked. It advances the marketplace clone and writes the new commit's files to disk, printing success — but the **install pointer** still names the previous commit, so sessions keep loading the old skill body while the files on disk show the new one.

      `context marketplaces refresh --marketplace <name> --plugin <name>` runs both.
    </Warning>
  </Step>
</Steps>

<Note>
  Iterating on the plugin *yourself*? Don't publish for every change — use [the dev loop](/guides/marketplaces/dev-loop) to test against your live Moxn branch, and publish only when you're ready to release.
</Note>