# Contributing

Use this skill when the user wants to contribute to MLX-VLM, opening a PR, where model...

- Repository: https://github.com/Blaizzy/mlx-vlm (5707 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Blaizzy/mlx-vlm --skill contributing -g -a claude-code -y`
Codex: `npx skills add Blaizzy/mlx-vlm --skill contributing -g -a codex -y`
Cursor: `npx skills add Blaizzy/mlx-vlm --skill contributing -g -a cursor -y`
Gemini CLI: `npx skills add Blaizzy/mlx-vlm --skill contributing -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Blaizzy/mlx-vlm`

## Description

Use this skill when the user wants to contribute to MLX-VLM, opening a PR, where model code/config/tests go, backward-compatible config args, running the test suite, code formatting and the pre-commit hooks (black, clang-format), and PR expectations (tests, review, perf evidence). Use it to set up a change so it passes review.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Contributing to MLX-VLM

Use this workflow to shape a contribution so it lands cleanly. It reflects the current `mlx_vlm/` layout (note: `CONTRIBUTING.md` still points at an older `src/` layout, the real paths are below).

## Setup

```bash
git clone https://github.com/<you>/mlx-vlm && cd mlx-vlm
uv pip install -e .            # editable install (or: pip install -e .)
```

## Where things go

- **Model code:** `mlx_vlm/models/<model_type>/`, and the file name matches the `config.json` `model_type` (e.g. `llava`). A new kernel or helper goes in **its own file in that model directory**, not bolted into `language.py`. To add a whole new model, use `Skill("mlx-vlm-skills:add-new-model")`.
- **Config args:** add to the model's `ModelConfig` (in `<model>/config.py`) with an inline `# comment`, and keep them **backward-compatible**, a default of `None`/`0`/`False` must reproduce the original behavior so existing checkpoints and configs are unaffected. Gate new features so they are opt-in.
- **Tests:** add to `mlx_vlm/tests/test_models.py` as a **class per feature** (e.g. `TestMyFeature`). Do not create a standalone `test_<feature>.py`, repo convention keeps model tests in `test_models.py`. Prefer cheap synthetic/random-weight tests (tiny configs) and check exactness against the original path in the degenerate limit (feature disabled == baseline).

## Run the tests

```bash
cd mlx_vlm && uv run --with pytest python -m pytest tests/test_models.py -q -k "<ClassName>"
```

## Formatting, install and run pre-commit

**Before opening a PR, install the pre-commit hooks once and run them.** The repo uses `pre-commit` (black for Python, clang-format for C++); PRs are expected to be hook-clean.

```bash
pip install pre-commit
pre-commit install                 # install the git hooks (run once per clone)

# run on the files you changed
pre-commit run --files <file1.py> <file2.py>
# or check everything
pre-commit run --all-files
```

The rest: https://github.com/Blaizzy/mlx-vlm/blob/HEAD/skills/skills/contributing/SKILL.md