Claude Code for Zig: Systems Programming Without Hidden Control Flow

Zig is a systems language designed for clarity: no hidden control flow, no implicit allocations, explicit error handling. Every function call that can fail returns an error union. Allocators are passed explicitly so memory ownership is always clear. comptime enables compile-time code execution for generics, type reflection, and constant folding — no macro language needed. Zig calls C directly with @cImport without runtime overhead. Claude Code generates Zig functions, data structures, build.zig configurations, comptime generics, and the C interop bindings for systems and WebAssembly targets.

CLAUDE.md for Zig Projects

## Zig Stack
- Version: Zig 0.14+ (stable)
- Build: build.zig with addExecutable, addStaticLibrary for cross-compilation
- Allocators: GeneralPurposeAllocator (debug), arena for request scoping, fixed_buffer for embedded
- Error handling: error unions (T!Error) — always handle all cases
- Logging: std.log with scopes (no fmt.print in production code)
- Testing: test "name" { ... } blocks in source files, run with zig build test
- Targets: x86_64-linux-musl, aarch64-linux-musl, wasm32-wasi
- C interop: @cImport for existing C libraries, extern fn for FFI

Basic Zig Patterns

// src/main.zig — basic Zig programs
const std = @import("std");
const Allocator = std.mem.Allocator;
const log = std.log.scoped(.main);

// Error union: this function returns u64 OR an error
fn parsePort(s: []const u8) error{InvalidPort}!u16 {
    const n = std.fmt.parseInt(u16, s, 10) catch return error.InvalidPort;
    if (n == 0) return error.InvalidPort;
    return n;
}

// Optional type: ?T (can be null, must be checked)
fn findUser(users: []const User, id: u32) ?*const User {
    for (users) |*user| {
        if (user.id == id) return user;
    }
    return null;
}

pub fn main() !void {
    // Allocator: explicit, no hidden heap allocations
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Error handling: try propagates errors up the call stack
    const port = try parsePort("8080");
    log.info("Listening on port {d}", .{port});

    // ArrayList: heap-allocated, allocator-aware
    var numbers = std.ArrayList(u32).init(allocator);
    defer numbers.deinit();  // defer guarantees cleanup even on error

    try numbers.append(1);
    try numbers.append(2);
    try numbers.append(3);

    for (numbers.items) |n| {
        log.debug("n={d}", .{n});
    }
}

// Struct with methods
const User = struct {
    id: u32,
    name: []const u8,
    email: []const u8,
    age: u8,

    // Methods are regular functions in the struct namespace
    pub fn isAdult(self: User) bool {
        return self.age >= 18;
    }

    pub fn format(
        self: User,
        comptime fmt: []const u8,
        options: std.fmt.FormatOptions,
        writer: anytype,
    ) !void {
        _ = fmt;
        _ = options;
        try writer.print("User{{ id={d}, name={s} }}", .{ self.id, self.name });
    }
};

test "User.isAdult" {
    const user = User{ .id = 1, .name = "Alice", .email = "[email protected]", .age = 25 };
    try std.testing.expect(user.isAdult());

    const minor = User{ .id = 2, .name = "Bob", .email = "[email protected]", .age = 16 };
    try std.testing.expect(!minor.isAdult());
}

Comptime Generics

// Generic stack implemented with comptime
fn Stack(comptime T: type) type {
    return struct {
        items: []T,
        len: usize,
        allocator: Allocator,

        const Self = @This();

        pub fn init(allocator: Allocator) Self {
            return Self{
                .items = &.{},
                .len = 0,
                .allocator = allocator,
            };
        }

        pub fn deinit(self: *Self) void {
            self.allocator.free(self.items);
        }

        pub fn push(self: *Self, item: T) !void {
            if (self.len == self.items.len) {
                const new_len = if (self.items.len == 0) 8 else self.items.len * 2;
                self.items = try self.allocator.realloc(self.items, new_len);
            }
            self.items[self.len] = item;
            self.len += 1;
        }

        pub fn pop(self: *Self) ?T {
            if (self.len == 0) return null;
            self.len -= 1;
            return self.items[self.len];
        }

        pub fn peek(self: *const Self) ?T {
            if (self.len == 0) return null;
            return self.items[self.len - 1];
        }
    };
}

test "Stack" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    var stack = Stack(i32).init(gpa.allocator());
    defer stack.deinit();

    try stack.push(1);
    try stack.push(2);
    try stack.push(3);

    try std.testing.expectEqual(@as(?i32, 3), stack.pop());
    try std.testing.expectEqual(@as(?i32, 2), stack.pop());
    try std.testing.expectEqual(@as(usize, 1), stack.len);
}

// Comptime type inspection for serialization
fn serialize(comptime T: type, value: T, writer: anytype) !void {
    const info = @typeInfo(T);

    switch (info) {
        .Int => try writer.print("{d}", .{value}),
        .Float => try writer.print("{d}", .{value}),
        .Bool => try writer.print("{}", .{value}),
        .Optional => {
            if (value) |v| {
                try serialize(info.Optional.child, v, writer);
            } else {
                try writer.writeAll("null");
            }
        },
        .Struct => |s| {
            try writer.writeAll("{");
            inline for (s.fields, 0..) |field, i| {
                if (i != 0) try writer.writeAll(",");
                try writer.print("\"{s}\":", .{field.name});
                try serialize(field.type, @field(value, field.name), writer);
            }
            try writer.writeAll("}");
        },
        else => @compileError("Unsupported type: " ++ @typeName(T)),
    }
}

Memory Management with Allocators

// Arena allocator for request-scoped memory
fn handleRequest(allocator: Allocator, body: []const u8) ![]const u8 {
    // Arena: allocate many things, free all at once
    var arena = std.heap.ArenaAllocator.init(allocator);
    defer arena.deinit();  // Frees everything allocated in this request

    const a = arena.allocator();

    // All string operations allocate in the arena
    const parsed = try parseJSON(a, body);
    const processed = try transform(a, parsed);
    const result = try formatResponse(a, processed);

    // Copy result out before arena is freed
    return allocator.dupe(u8, result);
}

// Fixed buffer allocator for embedded/no-heap scenarios
fn processFixed(input: []const u8) !void {
    var buffer: [4096]u8 = undefined;
    var fba = std.heap.FixedBufferAllocator.init(&buffer);
    const allocator = fba.allocator();

    var list = std.ArrayList(u8).init(allocator);
    defer list.deinit();

    // Fails with OutOfMemory if buffer exhausted — no heap fallback
    for (input) |byte| {
        try list.append(byte);
    }
}

C Interop

// src/lib.zig — calling C from Zig
const c = @cImport({
    @cInclude("openssl/sha.h");
    @cInclude("openssl/evp.h");
});

pub fn sha256(data: []const u8) [32]u8 {
    var digest: [32]u8 = undefined;
    var ctx: c.EVP_MD_CTX = undefined;

    _ = c.EVP_DigestInit_ex(&ctx, c.EVP_sha256(), null);
    _ = c.EVP_DigestUpdate(&ctx, data.ptr, data.len);

    var len: c_uint = 32;
    _ = c.EVP_DigestFinal_ex(&ctx, &digest, &len);

    return digest;
}

// Exporting Zig functions for use from C or other languages
export fn zig_add(a: i32, b: i32) i32 {
    return a + b;
}

// Callback from C: extern fn matches C calling convention
extern fn qsort(
    base: [*]u8,
    nmemb: usize,
    size: usize,
    compar: *const fn ([*]const u8, [*]const u8) callconv(.C) c_int,
) void;

HTTP Server (with std.net)

// src/http_server.zig — simple HTTP server
const std = @import("std");
const net = std.net;

pub fn run(port: u16, allocator: std.mem.Allocator) !void {
    const address = try net.Address.parseIp4("0.0.0.0", port);
    var server = try address.listen(.{ .reuse_address = true });
    defer server.deinit();

    std.log.info("Listening on :{d}", .{port});

    while (true) {
        const conn = try server.accept();
        const thread = try std.Thread.spawn(.{}, handleConnection, .{ conn, allocator });
        thread.detach();
    }
}

fn handleConnection(conn: net.Server.Connection, allocator: std.mem.Allocator) void {
    defer conn.stream.close();

    var arena = std.heap.ArenaAllocator.init(allocator);
    defer arena.deinit();
    const a = arena.allocator();

    handleRequest(conn.stream, a) catch |err| {
        std.log.err("Request error: {}", .{err});
    };
}

fn handleRequest(stream: net.Stream, allocator: std.mem.Allocator) !void {
    var buf: [8192]u8 = undefined;
    const n = try stream.read(&buf);
    const request = buf[0..n];

    // Parse first line
    const first_line_end = std.mem.indexOf(u8, request, "\r\n") orelse return error.BadRequest;
    const first_line = request[0..first_line_end];

    var parts = std.mem.splitScalar(u8, first_line, ' ');
    const method = parts.next() orelse return error.BadRequest;
    const path = parts.next() orelse return error.BadRequest;

    _ = allocator;

    const body = if (std.mem.eql(u8, path, "/health"))
        "{\"status\":\"ok\"}"
    else
        null;

    if (body) |b| {
        try stream.writeAll("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n");
        try stream.writeAll(b);
    } else {
        try stream.writeAll("HTTP/1.1 404 Not Found\r\n\r\n");
    }

    _ = method;
}

build.zig

// build.zig — configure build targets
const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Main executable
    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Link system C library if needed
    exe.linkSystemLibrary("ssl");
    exe.linkSystemLibrary("crypto");
    exe.linkLibC();

    b.installArtifact(exe);

    // Run step: zig build run
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| run_cmd.addArgs(args);
    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);

    // Test step: zig build test
    const tests = b.addTest(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    const run_tests = b.addRunArtifact(tests);
    const test_step = b.step("test", "Run tests");
    test_step.dependOn(&run_tests.step);

    // WASM target: zig build -Dtarget=wasm32-wasi
    const wasm = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/wasm.zig"),
        .target = b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .wasi }),
        .optimize = .ReleaseSmall,
    });
    b.installArtifact(wasm);
}

For the Rust systems programming alternative with a larger ecosystem and async/await for network services, see the Rust guide and Rust async guide for comparison. For compiling Zig/Rust to WebAssembly for browser integration, the WebAssembly guide covers the JS interop patterns. The Claude Skills 360 bundle includes Zig skill sets covering comptime generics, allocator patterns, and C interop. Start with the free tier to try Zig program generation.