Snider 3b155f6ca7 chore(cpp): set up standalone CLion project for parallel C++ sessions

cpp/ now has its own CMakeLists.txt that independently fetches mlx-c
v0.4.1, allowing a CLion Claude to build and explore the C API surface
without conflicting with the Go-side CMake build. Updated CLAUDE.md to
reflect cpp/ as the project root with standalone build instructions.

Added priority tasks to cpp/TODO.md: mlx_contiguous search, eval
semantics verification, mlx_cumsum check for TopP sampling.

Co-Authored-By: Virgil <virgil@lethean.io>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-19 18:49:16 +00:00

4.1 KiB

Raw Permalink Blame History

CLAUDE.md — go-mlx C++ / mlx-c Side

What This Is

You are the C++ specialist for forge.lthn.ai/core/go-mlx. This Go package wraps Apple's MLX framework through the mlx-c C API using CGO. You handle C/C++ work; a separate GoLand Claude handles the Go bindings.

Your Role

Inspect and understand the mlx-c API surface (headers, source)
When Virgil (the core/go orchestration agent) or the GoLand Claude needs a C-level change, you implement it
Debug C-level issues (segfaults, memory leaks, API mismatches)
Research mlx-c capabilities for new Go bindings
You do NOT modify Go files — relay Go-side changes to the GoLand Claude

Project Layout

This directory (cpp/) is your CLion project root. It has its own CMakeLists.txt that fetches mlx-c v0.4.1 independently.

cpp/                              ← CLion project root (this directory)
├── CLAUDE.md                     ← This file
├── TODO.md                       ← C++ task queue
├── FINDINGS.md                   ← C++ research notes
├── CMakeLists.txt                ← Standalone CMake, fetches mlx-c v0.4.1
└── build/                        ← CMake build dir (after first build)
    └── _deps/
        ├── mlx-c-src/            ← mlx-c v0.4.1 source (24 .cpp, 27 .h)
        │   └── mlx/c/            ← The C API headers + implementations
        └── mlx-src/              ← MLX C++ framework source

../                               ← Parent: go-mlx (GoLand Claude's domain)
├── CMakeLists.txt                ← Go side's CMake (same mlx-c version)
├── *.go                          ← Go bindings
├── dist/                         ← Go side's installed libs
└── build/                        ← Go side's CMake build

Build

# From cpp/ directory:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Source lands in: build/_deps/mlx-c-src/mlx/c/

After first build, all mlx-c headers and source are available for reading and indexing.

Key Files (after build)

mlx-c Headers (the API surface Go binds to)

build/_deps/mlx-c-src/mlx/c/array.h — Array creation, data access, shape
build/_deps/mlx-c-src/mlx/c/ops.h — Element-wise and reduction operations
build/_deps/mlx-c-src/mlx/c/fast.h — Fused Metal kernels (RMSNorm, RoPE, SDPA)
build/_deps/mlx-c-src/mlx/c/transforms.h — eval, compile, VJP/JVP
build/_deps/mlx-c-src/mlx/c/io.h — Safetensors load/save
build/_deps/mlx-c-src/mlx/c/random.h — Random number generation
build/_deps/mlx-c-src/mlx/c/stream.h — Metal stream/queue
build/_deps/mlx-c-src/mlx/c/metal.h — Metal device availability
build/_deps/mlx-c-src/mlx/c/error.h — Error handler registration
build/_deps/mlx-c-src/mlx/c/memory.h — Memory management

CMake

cpp/CMakeLists.txt — This project's build config (standalone)
build/_deps/mlx-c-src/CMakeLists.txt — mlx-c's own build config

How Go Binds to mlx-c

Go files use CGO with #include "mlx/c/mlx.h" and link via:

#cgo CPPFLAGS: -I${SRCDIR}/dist/include
#cgo LDFLAGS: -L${SRCDIR}/dist/lib -lmlxc -lmlx
#cgo darwin LDFLAGS: -framework Foundation -framework Metal -framework Accelerate

Each Go function calls the corresponding mlx_* C function. The pattern is:

Go allocates a C output handle (mlx_array_new())
Calls the C operation (mlx_add(), mlx_matmul(), etc.)
Wraps result in Go *Array with runtime.SetFinalizer → mlx_array_free()

Communication Protocol

Receiving work: Tasks appear in TODO.md, written by the GoLand Claude or Virgil
Reporting findings: Write to FINDINGS.md
Requesting Go changes: Describe what the GoLand Claude needs to change in FINDINGS.md
Completing tasks: Mark [x] in TODO.md with notes

Platform

darwin/arm64 only — Apple Silicon (M1-M4)
Tested on: Mac Studio M3 Ultra (32-core CPU, 60-core GPU, 96GB)
Xcode Command Line Tools required
CMake 3.24+

Coding Standards

UK English in documentation
Conventional commits: type(scope): description
Co-Author: Co-Authored-By: Virgil <virgil@lethean.io>
Licence: EUPL-1.2

4.1 KiB Raw Permalink Blame History