Specialist ARM Migration

A specialized agent that migrates codebases from x86 to ARM architecture, identifying x86-specific dependencies, intrinsics, and build configurations and converting them to ARM equivalents while maintaining compatibility and optimizing performance.

When to Use This Agent

Choose Specialist ARM Migration when:

• Migrating applications from x86 to ARM-based servers (AWS Graviton, Azure Ampere)
• Converting Docker images to support ARM64 architectures
• Identifying and replacing x86-specific SIMD intrinsics with NEON equivalents
• Updating build pipelines for multi-architecture support
• Optimizing application performance for ARM processors

Consider alternatives when:

• Building new applications on ARM from scratch (use a general development agent)
• Optimizing application performance without architecture change (use a performance agent)
• Setting up CI/CD without architecture considerations (use a DevOps agent)

Quick Start

Copy
# .claude/agents/specialist-arm-migration.yml
name: Specialist ARM Migration
description: Migrate codebases from x86 to ARM architecture
model: claude-sonnet
tools:
  - Read
  - Edit
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Analyze our codebase for x86-specific dependencies and create a migration plan to support ARM64 (AWS Graviton) alongside x86"

Core Concepts

Migration Assessment Matrix

Area	x86-Specific	ARM Equivalent	Risk
SIMD intrinsics	SSE/AVX (_mm_*)	NEON (v*_*)	High
Assembly	x86 ASM	ARM64 ASM	High
Build flags	-march=x86-64	-march=armv8-a	Medium
Docker base images	amd64/ubuntu	arm64v8/ubuntu	Low
Binary dependencies	x86 .so/.dll	ARM .so	Medium
Compiler intrinsics	__builtin_ia32_*	__builtin_aarch64_*	High

Dockerfile Multi-Architecture Support

Copy
# Multi-arch Dockerfile using build arguments
FROM --platform=$BUILDPLATFORM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM --platform=$TARGETPLATFORM node:20-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json .
EXPOSE 3000
CMD ["node", "dist/index.js"]

Copy
# Build and push multi-arch image
docker buildx create --name multiarch --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag myapp:latest \
  --push .

SIMD Intrinsics Migration

Copy
// x86 SSE — Original
#include <immintrin.h>

void add_vectors_x86(float* a, float* b, float* result, int n) {
    for (int i = 0; i < n; i += 4) {
        __m128 va = _mm_load_ps(&a[i]);
        __m128 vb = _mm_load_ps(&b[i]);
        __m128 vr = _mm_add_ps(va, vb);
        _mm_store_ps(&result[i], vr);
    }
}

// ARM NEON — Migrated
#include <arm_neon.h>

void add_vectors_arm(float* a, float* b, float* result, int n) {
    for (int i = 0; i < n; i += 4) {
        float32x4_t va = vld1q_f32(&a[i]);
        float32x4_t vb = vld1q_f32(&b[i]);
        float32x4_t vr = vaddq_f32(va, vb);
        vst1q_f32(&result[i], vr);
    }
}

Configuration

Parameter	Description	Default
target_arch	Target ARM architecture (armv8-a, armv9-a)	armv8-a
source_arch	Source x86 architecture	x86-64
platform	Target platform (linux, macos, windows)	linux
cloud_provider	Cloud ARM offering (graviton, ampere, cobalt)	Auto-detect
multi_arch	Build for both architectures	true
simd_strategy	SIMD migration (neon, sse2neon, portable)	neon

Best Practices

1. Audit all binary dependencies and native modules first. The biggest migration blocker is usually third-party libraries distributed as pre-compiled binaries. Check that all npm native modules (node-gyp-based), Python C extensions, and shared libraries have ARM64 builds available. Use npm ls --all and check each native dependency's ARM support. Missing ARM support may require finding alternative packages or building from source.

2. Use sse2neon.h for rapid SSE-to-NEON migration. Instead of manually translating every SSE intrinsic to NEON, the sse2neon.h header provides drop-in replacements that map SSE functions to NEON equivalents. This enables quick migration without per-function rewrites. Optimize critical hot paths with native NEON intrinsics later, but use sse2neon for the initial functional migration.

3. Build multi-architecture Docker images from day one. Use docker buildx with --platform linux/amd64,linux/arm64 to produce images for both architectures. This allows gradual migration where some services run on ARM while others remain on x86. Multi-arch images are selected automatically by the container runtime based on the host architecture.

4. Benchmark performance after migration, not just correctness. ARM processors have different performance characteristics: stronger single-thread performance per watt, different cache hierarchies, and different SIMD widths. Code that is optimal on x86 may not be optimal on ARM. Profile with perf on ARM instances and optimize hot paths. Many workloads see 20-40% cost savings on ARM with minimal optimization.

5. Test on actual ARM hardware, not just emulation. QEMU-based ARM emulation is useful for build verification but does not accurately represent performance, timing, or hardware-specific behavior. Run functional and performance tests on actual ARM instances (AWS Graviton, Azure Ampere) to validate the migration. Emulation misses endianness issues, alignment requirements, and atomics behavior that differ between architectures.

Common Issues

Node.js native modules fail to compile on ARM. Some npm packages with native bindings do not include ARM pre-built binaries and fail during npm install. Solutions: check for ARM-compatible versions, use node-pre-gyp with ARM build targets, or switch to pure JavaScript alternatives. For packages like sharp (image processing), ARM builds are available but require the correct platform detection in package.json.

Performance regression on ARM despite correct functionality. Code ported from x86 may run slower on ARM if it relies on x86-specific optimizations (AVX-512, specific cache line sizes). Profile the application on ARM to identify hot paths. ARM NEON has 128-bit vector width (vs AVX's 256/512-bit), so vectorized code may need different loop unrolling factors. Tune compiler flags: -mcpu=neoverse-v1 (Graviton3) enables CPU-specific optimizations.

CI/CD pipeline does not support multi-architecture builds. Standard CI runners are x86-only. For ARM builds, use GitHub Actions runs-on: ubuntu-latest with QEMU and docker buildx for image building, or use ARM-native runners (GitHub's ubuntu-24.04-arm64 runner, AWS CodeBuild with ARM compute). Cross-compilation is faster than emulation for most build steps.