Tooling

The build, lint, codegen, and CI pieces a contributor will encounter.

Build

Tool	Used for
go	Building the main binary, running tests, vetting code.
CMake	Building the native shims under llama/llama.cpp/ on platforms where they are not statically linked into the Go binary (macOS Intel, Linux, Windows). The configuration files are CMakeLists.txt and CMakePresets.json.
make	Vendoring updates only; the project does not have a primary Makefile. The Makefile.sync (Makefile.sync) syncs and patches the vendored llama.cpp tree.

The standard build is go build . on Apple Silicon (where Metal is built into the binary) and cmake -B build && cmake --build build && go build . everywhere else.

Lint

Configuration: .golangci.yaml. Run with:

golangci-lint run

CI invokes the same config from .github/workflows/test.yaml.

Code generation

• TypeScript types for the Go API client are generated by the test in api/types_typescript_test.go using tkrajina/typescriptify-golang-structs. The generated TypeScript file is checked in alongside the Go types.
• Protobuf for the sentencepiece tokenizer (convert/sentencepiece_model.proto) is hand-rolled into Go in convert/sentencepiece_model.pb.go (regenerate with the standard protoc workflow when changing the schema).
• Build info for the vendored llama.cpp lives at llama/build-info.cpp, generated from build-info.cpp.in during the CMake build.

Vendored llama.cpp

The full llama.cpp tree under llama/llama.cpp/ is updated through Makefile.sync. The make targets:

• make -f Makefile.sync sync — pull a specific upstream ref into llama/llama.cpp/ and reapply the patches in llama/patches/.
• make -f Makefile.sync apply-patches — reapply patches without re-fetching.
• make -f Makefile.sync format-patches — regenerate the patch series after upstream changes.

The patches are kept as a series so the divergence from upstream stays auditable. Pin file: MLX_VERSION tracks the MLX upstream version used by the imagegen and mlxrunner backends; MLX_C_VERSION the matching C bindings.

CI

Workflows under .github/workflows/:

Workflow	When it runs	What it does
test.yaml	On every PR push	Lint, vet, go test.
test-install.yaml	On PR + release	Smoke-test the installer scripts.
release.yaml	On a vX.Y.Z tag	Cross-compile binaries, build installers, attach artifacts to the GitHub release, push the Docker image.
latest.yaml	Manually triggered	Promote a finished release to latest channel for installers.

Editor / dev container

The project has no committed .devcontainer/ or .vscode/ directory; contributors rely on their own setups. The Dockerfile (Dockerfile) builds a release image and is occasionally useful as a clean-room build environment for reproducing CI failures locally.

Scripts

scripts/ holds release helpers:

• Installer scripts (install.sh, install.ps1).
• Tag and changelog helpers.
• Utility scripts referenced from the workflows above.

These are run from CI; they're rarely invoked by contributors directly.