The agent-safe way to discover, filter, and call every AI model — without parsing help text.
AI model registry client for models.dev — query every model your code can call, with a CLI built for agents and a polyglot library API.
Module: hop.top/aim · Go 1.26+ · MIT.
| You want to… | Go to |
|---|---|
| Install and run the CLI | Get started |
| Drive aim from an agent / orchestrator | Drive aim from an agent |
| Embed aim in your own code | Embed aim as a library |
| Look up a command or flag | Commands reference |
| Filter models with the query DSL | Query syntax |
| Debug a failure | Troubleshooting |
go install hop.top/aim/cmd/aim@latest
aim refresh
aim list --provider openai --tool-callA read-mostly client for the models.dev catalog with three surfaces:
- CLI —
aim list,aim show,aim query,aim refresh,aim status. Cached, deterministic, scriptable. - Capability surface —
aim spec --format jsonreturns a machine-readable manifest of every command, its inputs, outputs, side effects, and idempotency. Agents drive aim from this, not from--help. - Library —
import "hop.top/aim"and use the same cache, source, and query semantics from your own program. Polyglot: Go (canonical), Python, TypeScript, Rust, PHP.
aim is a 12-Factor AI-CLI end-to-end: all 12 factors pass. That means:
- Every command exposes a stable JSON schema.
- Every error returns a structured envelope with a stable code, a runnable suggested fix, and runnable alternatives.
- Every read carries provenance (
source,fetched_at,method). - Writes preview via
--dry-run; queries parse via--explain. - Schema versions are negotiated via
--api-version.
Executable proof: docs/12-factor-conformance.md
(auto-regenerated by make conformance).
The same catalog and query DSL in five languages. Library-only — the agent-safe CLI surface lives in the Go binary.
| Language | Path | Distribution | Status |
|---|---|---|---|
| Go (canonical) | . |
go get hop.top/aim |
0.1.0-alpha.0 |
| Python | py/ |
pip install hop-aim (planned) |
0.1.0-alpha.0 |
| TypeScript | ts/ |
npm install @hop-top/aim (planned) |
0.1.0-alpha.0 |
| Rust | rs/ |
cargo add hop-aim (planned) |
0.1.0-alpha.0 |
| PHP | php/ |
composer require hop-top/aim (planned) |
0.1.0-alpha.0 |
Parity matrix and cross-SDK conformance: docs/sdk-parity.md.
docs/manual/— user-facing docs (install, commands, agents, library, configuration, troubleshooting, upgrade).docs/ARCHITECTURE.md— internal layering and design decisions.docs/12-factor-conformance.md— auto-generated conformance report.docs/schema-changelog.md— supported--api-versionvalues and deprecation policy.CONTRIBUTING.md— local development.RELEASING.md— version cuts via release-please.
make test # go tests (fast, default)
make test-all # all 5 SDK test suites
make lint-all # all language linters + doc linters
make parity # cross-SDK conformance check
make conformance # 12-factor conformance report
make check-all # full pre-merge gateMulti-language work: make dev-up boots a devcontainer with every
toolchain (Go, Python uv, Node, Rust, PHP). Requires Docker. Full
guide in CONTRIBUTING.md.
aim is open-source and built in the open. If your organization depends on aim, consider sponsoring development via GitHub Sponsors.