# Hex

Recommend AXM extensions from a Hex (Elixir, Erlang) package and target Hex packages from an extension.

AXM reads Hex extension metadata from an `agent-extensions.json` sidecar shipped
at the package root. This is the
[two-way linking](/docs/package-ecosystems/overview) model applied to the Hex
ecosystem.

## 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": "@examples/packs/elixir-hex-tinyflags" }],
}
```

Include the sidecar in the published tarball by listing it in the `files` key of
your `mix.exs` package config, so consumers see it at
`deps/<package>/agent-extensions.json` after `mix deps.get`:

```elixir
# mix.exs
defp package do
  [
    files: ~w(lib mix.exs README.md agent-extensions.json)
  ]
end
```

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:

```jsonc
{
  "agentExtensions": [
    {
      "ref": "@examples/packs/elixir-hex-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}
```

## Target Hex packages from an extension

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

```jsonc
// pack.json
{
  "packages": [{ "purl": "pkg:hex/agentxm_example_tinyflags" }],
}
```

### Version ranges

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

```jsonc
{
  "packages": [
    {
      "purl": "pkg:hex/agentxm_example_tinyflags",
      "versionRange": "vers:hex/>=0.1.0|<1.0.0",
    },
  ],
}
```

## Official status

When the Hex 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).

## Reference fixture

The
[`elixir-hex-lib`](https://github.com/agentxm/polyglot-examples/tree/main/elixir-hex-lib)
and
[`elixir-hex-app`](https://github.com/agentxm/polyglot-examples/tree/main/elixir-hex-app)
directories in `polyglot-examples` are the working fixtures for everything
above. The package publishes a TinyFlags companion pack and recommends it from
the `agent-extensions.json` sidecar (shipped via the `files` key in `mix.exs`);
the pack and each skill declare the package's `pkg:hex` purl as an identity-only
companion package.

AXM reads `deps/<package>/agent-extensions.json` as the primary source and falls
back to parsing the recommendation out of `hex_metadata.config` when the sidecar
is absent, so shipping `agent-extensions.json` via the `files` key remains the
recommended path.