# Mojo

Recommend AXM extensions from a Mojo package and target Mojo packages from an extension.

The [two-way linking](/docs/package-ecosystems/overview) model applies to Mojo
packages just as it does to other ecosystems. A package recommends through
package-author metadata it ships, and an extension targets the package through a
Mojo [purl](https://github.com/package-url/purl-spec).

Mojo packages are managed through the Modular ecosystem, where dependencies are
declared in `pixi.toml` (preferred) or `mojoproject.toml` (deprecated fallback).
Following the pattern sidecar-based ecosystems use (see
[Go modules](/docs/package-ecosystems/go-modules)), AXM reads an
`agent-extensions.json` sidecar shipped at the package root. After resolution,
it reads the sidecar from the pixi environment cache
(`.pixi/envs/<env>/conda-meta/<package>/agent-extensions.json`).

## Recommend extensions from a package

Add an `agent-extensions.json` file at the package root with an
`agentExtensions` array. Each entry is an extension reference
(`@owner/<type>/<name>`):

```jsonc
// agent-extensions.json
{
  "$schema": "https://axm.sh/schemas/agent-extensions.schema.json",
  "agentExtensions": [{ "ref": "@acme/packs/widget-kit" }],
}
```

Keep recommendations **identity-only** — omit `versionRange`. AXM resolves the
reference to the newest matching extension version and pins it in the user's
`axm.lock`. Prefer recommending a single **pack** so you keep one stable
reference while its contents evolve. Add a semver `versionRange` only when your
package genuinely pairs with a bounded major line of the extension.

## Target Mojo packages from an extension

On the extension manifest (`skill.json`, `pack.json`, `subagent.json`, …), add a
`packages` array with a Mojo [purl](https://github.com/package-url/purl-spec):

```jsonc
// pack.json
{
  "packages": [{ "purl": "pkg:mojo/widget-kit" }],
}
```

Use the package name as published as the purl name.

### Version ranges

Default to identity-only. Add a [VERS](https://github.com/package-url/vers-spec)
`versionRange` with the `mojo` scheme only when the extension depends on package
APIs introduced or removed in a known range:

```jsonc
{
  "packages": [
    {
      "purl": "pkg:mojo/widget-kit",
      "versionRange": "vers:mojo/>=1.0.0|<2.0.0",
    },
  ],
}
```

## Official status

When the Mojo package recommends an extension through the AgentXM Registry
**and** that extension names the package as a companion via its purl, AXM
derives **official** status for the pair — no extra flag. See
[Official extensions](/docs/package-ecosystems/overview#official-extensions).

> The Mojo package-author metadata convention is still being finalized. The
> sidecar location above mirrors the documented sidecar ecosystems; the
> `pkg:mojo` purl is the stable identity an extension uses to target a package.
> Confirm the current shape against the
> [`polyglot-examples`](https://github.com/agentxm/polyglot-examples) fixtures
> before relying on it.