Getting started

Install the CLI — this provides both shelf and the pixi shelf extension:

pixi global install --channel https://mojoshelf.org/channel mojoshelf

(No pixi? cargo install --locked --git https://github.com/mojoshelf/mojoshelf mojoshelf works too. The conda package is currently built for osx-arm64.)

Tins install in one of two modes.

Pixi mode: git source dependencies

Tins become registry-pinned git dependencies in your pixi.toml, built by the pixi-build-mojo backend — no submodules, no -I flags. Enable pixi's preview feature in your workspace, with channels for the Mojo toolchain and the modular-community packages tins may depend on:

[workspace]
preview = ["pixi-build"]
channels = [
    "conda-forge",
    "https://conda.modular.com/max-nightly",
    "https://repo.prefix.dev/modular-community",
]

Then, from anywhere in the workspace:

pixi shelf add <name>      # or: shelf add --pixi <name>

The tin and its dependencies are added flat, each pinned to its published commit via pixi add --git … --rev …. Note: pixi-build is a pixi preview feature, and the tin must be a pixi package (a [package] section with the pixi-build-mojo backend) — nearly every tin on the shelf supports it.

See mojoshelf/example for a complete working project consuming the csv tin this way — clone it and pixi run run.

The shelf also mirrors the modular-community channel: its binary packages appear in the tin list badged channel, and pixi shelf add installs them the same way.

Submodule mode

From your project's repo root:

shelf add <name>

The tin and its dependencies land as flat submodules under shelf/, pinned to their published commits. Point the Mojo compiler at them with -I, wrapped as a pixi task:

[tasks]
run = "mojo run -I shelf/csv/src src/main.mojo"

Useful commands

Every command works in both modes; prefix with pixi (or pass --pixi) for pixi mode.

Agent skills

Working with a coding agent? Two Agent Skills ship with the mojoshelf repo — one teaches your agent to consume tins, the other to publish them:

npx skills add mojoshelf/mojoshelf                                  # pick interactively
npx skills add mojoshelf/mojoshelf --skill mojoshelf-consume --yes  # or one directly
npx skills add mojoshelf/mojoshelf --skill mojoshelf-publish --yes

Connect your agent (MCP)

The registry runs a Model Context Protocol server at https://mojoshelf.org/mcp — anonymous, read-only, no API key. Connect it once and your agent gets three tools in every session: search_tins (find libraries by topic), tin_info (a tin's full card: Mojo import name, install commands, API surface, build health), and usage_example (install commands plus a copy-pasteable snippet). With Claude Code:

claude mcp add --transport http mojoshelf https://mojoshelf.org/mcp

Any other MCP-capable host (claude.ai, Cursor, VS Code, …) connects with the same URL. Agents without MCP can fetch /llms.txt (index) or /llms-full.txt (every tin's card), or use the JSON API (/api/tins?q=…).

Want to publish your own tin? See the Authors page.