Contributing

Contributions are welcome! This page covers everything you need to get started.

Prerequisites

• Rust (stable) -- install via rustup
• mise (optional, recommended) -- task runner that wraps cargo commands
• Git

Getting started

git clone https://github.com/arimxyer/models
cd models
cargo build
cargo run

If you have mise installed:

mise run build
mise run run

Running checks

Run these before every PR:

# With mise (recommended)
mise run fmt && mise run clippy && mise run test

# Without mise
cargo fmt && cargo clippy -- -D warnings && cargo test

All three must pass. CI enforces the same checks on pull requests.

Code conventions

• Clippy runs with -D warnings -- all warnings are errors
• No eprintln! in TUI code -- stderr output corrupts ratatui's alternate screen buffer. Use Message variants or status bar updates instead. eprintln! is fine in CLI-only code paths.
• Enum-based message passing -- the TUI uses an Elm-architecture pattern with a Message enum. No callbacks.
• New BenchmarkEntry fields must use #[serde(default)]
• Commit Cargo.lock alongside Cargo.toml when changing dependencies or the version

Adding a new agent

The easiest way to contribute is by adding a new AI coding agent to the catalog. This requires no Rust knowledge or build tools.

Edit data/agents.json and add an entry following this format:

{
  "my-agent": {
    "name": "My Agent",
    "repo": "owner/repo",
    "categories": ["cli"],
    "installation_method": "cli",
    "pricing": {
      "model": "usage",
      "free_tier": false,
      "usage_notes": "Pay per token"
    },
    "supported_providers": ["openai"],
    "platform_support": ["macos", "linux", "windows"],
    "open_source": true,
    "cli_binary": "my-agent",
    "version_command": ["--version"],
    "version_regex": "([0-9]+\\.[0-9]+\\.[0-9]+)",
    "config_files": [],
    "homepage": "https://example.com",
    "docs": "https://docs.example.com"
  }
}

Key fields:

Field	Description
name	Display name
repo	GitHub repo in owner/repo format
categories	["cli"], ["ide"], or both
cli_binary	Binary name for version detection
version_command	Args to get version (e.g., ["--version"])
version_regex	Regex to extract version from command output
open_source	Whether the source code is publicly available

Data directory

• data/agents.json -- curated agent catalog. Contributions welcome!
• data/benchmarks.json -- auto-generated from the Artificial Analysis API every 30 minutes. Do not edit manually.

Pull requests

• Branch from main and keep changes focused
• Reference related issues in your PR description
• CI runs format checking, clippy, and tests on every PR (doc-only changes are skipped)

Reporting issues

When opening an issue, please include:

• Steps to reproduce the problem
• Expected vs actual behavior
• Your environment (OS, terminal, Rust version)

Architecture reference

For detailed architecture documentation, key file locations, async patterns, and module structure, see the Architecture page.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.