CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Mandatory Reference
6 
7Read `AGENTS.md` before any code change. It is the authoritative engineering protocol covering architecture, naming conventions, anti-patterns, change playbooks, and validation requirements.
8 
9## Build & Test Commands
10 
11```bash
12# Requires exactly Zig 0.16.0 (verify: zig version)
13zig build                           # dev build
14zig build -Doptimize=ReleaseSmall   # release build (target: <1 MB binary)
15zig build test --summary all        # run all 5,300+ tests (must pass with 0 leaks)
16zig fmt src/                        # format all source files
17zig fmt --check src/                # check formatting (used by pre-commit hook)
18```
19 
20Primary validation command is `zig build test --summary all` (project-wide). Individual files can still be run with `zig test <file>.zig` when needed.
21 
22### Build Flags
23 
24```bash
25zig build -Dchannels=telegram,cli   # compile only specific channels (default: all)
26zig build -Dengines=base,sqlite     # compile only specific memory engines (default: base,sqlite)
27zig build -Dtarget=x86_64-linux-musl  # cross-compile for target triple
28zig build -Dversion=2026.3.1        # override CalVer version string
29```
30 
31Channel tokens: `all`, `none`, or comma-separated names (`cli`, `telegram`, `discord`, `slack`, `signal`, `matrix`, `web`, `nostr`, `irc`, `email`, `imessage`, `whatsapp`, `mattermost`, `lark`, `dingtalk`, `line`, `onebot`, `qq`, `maixcam`).
32 
33Engine tokens: `base`/`minimal` (enables `none`, `markdown`, `memory`, `api`), `sqlite`, `lucid`, `redis`, `lancedb`, `postgres`, `all`.
34 
35## Git Hooks
36 
37Activate once per clone:
38 
39```bash
40git config core.hooksPath .githooks
41```
42 
43- **pre-commit**: blocks if `zig fmt --check src/` fails
44- **pre-push**: blocks if `zig build test --summary all` fails
45 
46## Project Overview
47 
48NullClaw is an autonomous AI assistant runtime written in Zig 0.16.0. Hard constraints: 678 KB binary, ~1 MB peak RSS, <2 ms startup. Every dependency and abstraction has a measurable size/memory cost. Only two external dependencies: vendored SQLite (with build-time SHA256 hash verification) and `websocket.zig` (pinned commit).
49 
50## Architecture
51 
52The entire codebase is **vtable-driven**. All major subsystems use `ptr: *anyopaque` + `vtable: *const VTable` for pluggable implementations. Extending NullClaw means implementing a vtable struct and registering it in the subsystem's factory (see `AGENTS.md` section 7 for playbooks).
53 
54**Critical ownership rule**: callers must OWN the implementing struct (local var or heap-alloc). Never return a vtable interface pointing to a temporary -- the pointer will dangle.
55 
56### Module Initialization Order
57 
58Defined in `src/root.zig`. Phases mirror deployment dependencies:
59 
601. **Core**: `bus`, `config`, `util`, `platform`, `version`, `state`, `json_util`, `http_util`
612. **Agent**: `agent`, `session`, `providers`, `memory`
623. **Networking**: `gateway`, `channels`
634. **Extensions**: `security`, `cron`, `health`, `tools`, `identity`, `cost`, `observability`, `heartbeat`, `runtime`, `mcp`, `subagent`, `auth`, `multimodal`, `agent_routing`
645. **Hardware/Integrations**: `hardware`, `peripherals`, `rag`, `skillforge`, `tunnel`, `voice`
65 
66### Key Entry Points
67 
68- `src/main.zig` - CLI command routing (`agent`, `gateway`, `onboard`, `doctor`, `status`, `service`, `cron`, `channel`, `memory`, `skills`, `hardware`, `migrate`, `workspace`, `capabilities`, `models`, `auth`, `update`, `history`)
69- `src/root.zig` - Module hierarchy and public API exports (also serves as library root)
70- `src/config.zig` - JSON config loading (~30 sub-config structs from `config_types.zig`, loads from `~/.nullclaw/config.json`)
71- `src/agent.zig` - Agent orchestration (delegates to `src/agent/root.zig`)
72- `src/gateway.zig` - HTTP gateway server (rate limiting, pairing, webhooks)
73- `src/daemon.zig` - Supervisor with exponential backoff for gateway mode
74 
75### Subsystem Directories
76 
77- `src/providers/` - AI model providers. 9 core implementations + 41+ OpenAI-compatible services via `compatible.zig`. Factory in `factory.zig`, single source of truth for provider URLs and auth styles.
78- `src/channels/` - Messaging channels. Each implements `Channel.VTable` (`start`, `stop`, `send`, `name`, `healthCheck`). Factory in `root.zig`.
79- `src/tools/` - Tool implementations. Each implements `Tool.VTable` (`execute`, `name`, `description`, `parameters_json`). Tools receive args as `JsonObjectMap` and return `ToolResult`. Factory in `root.zig`.
80- `src/memory/` - Layered architecture: **engines** (SQLite, Markdown, LRU, Redis, PostgreSQL, LanceDB, Lucid, ClickHouse, API, None) and **retrieval** (hybrid search, RRF, embeddings). Engines conditionally compiled via build flags.
81- `src/security/` - Policy enforcement (`policy.zig`), pairing (`pairing.zig`), encrypted secrets (`secrets.zig`), sandbox backends (`landlock.zig`, `firejail.zig`, `bubblewrap.zig`, `docker.zig`, `detect.zig`).
82- `src/agent/` - Agent loop internals: `dispatcher.zig` (tool call parsing), `compaction.zig` (history trimming), `prompt.zig` (system prompt builder), `memory_loader.zig` (context injection), `commands.zig` (agent-mode commands). Config defaults are `max_tool_iterations = 1000` and `max_history_messages = 100` (see `src/config_types.zig`).
83 
84### Provider Boundary Notes
85 
86- Keep canonical tool names in the runtime and prompt layer. Provider-specific quirks should be normalized at the provider boundary when possible.
87- `src/providers/ollama.zig` already normalizes common local-model tool-name drift such as `tool.shell` -> `shell`, `tools.file_read` -> `file_read`, and `scheduler_tool` / `schedule_tool` -> `schedule`.
88- If a local model invents another wrapper-style tool name, prefer extending the Ollama normalization helper and adding a regression test instead of teaching alternate names to the tool registry or prompt text.
89 
90### Dependency Direction
91 
92Concrete implementations depend inward on vtable interfaces, config, and util. Never import across subsystems (e.g., provider code must not import channel internals).
93 
94## Config System
95 
96Config loads from `~/.nullclaw/config.json`. Runtime behavior is then adjusted by `NULLCLAW_*` environment overrides (see `Config.applyEnvOverrides()` in `src/config.zig`). Types are defined in `src/config_types.zig` and re-exported from `src/config.zig`.
97 
98`Config.load()` heap-allocates an internal `ArenaAllocator`. Always call `defer cfg.deinit()` to free. In tests, wrap in a parent arena:
99 
100```zig
101var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
102defer arena.deinit();
103var cfg = try Config.load(arena.allocator());
104defer cfg.deinit();
105```
106 
107Key config sections: `models.providers` (API keys/endpoints), `agents` (named agent configs), `channels` (per-channel settings), `memory` (backend/search/lifecycle), `gateway` (port/host/pairing), `security` (sandbox/audit/autonomy), `autonomy` (level/limits/allowlists), `runtime` (native/docker/wasm).
108 
109## Zig 0.16.0 API Gotchas
110 
111- `std.io.getStdOut()` does NOT exist. Use `std.fs.File.stdout()`.
112- HTTP client: `std.http.Client.fetch()` with `std.Io.Writer.Allocating`.
113- Child processes: `std.process.Child.init(argv, allocator)`, `.Pipe` (capitalized).
114- `ArrayListUnmanaged`: init with `.empty`, pass allocator to every method.
115- `ChaCha20Poly1305.decrypt`: use stack buffer then `allocator.dupe()` (heap buffer segfaults on macOS).
116- `SQLITE_TRANSIENT` in auto-translated C code: use `SQLITE_STATIC` (null) instead.
117- When unsure about API, search `src/` for existing usage rather than guessing.
118 
119## Search Zig Source
120 
121Run `zig env` to locate Zig source directories. `.std_dir` points to the standard library, `.lib_dir` to the broader lib tree. Read the source directly to verify struct fields, function signatures, and available methods.
122 
123## Testing Conventions
124 
125- All tests use `std.testing.allocator` (leak-detecting GPA). Every allocation must be freed with `defer`.
126- Use `builtin.is_test` guards to skip side effects (spawning processes, opening browsers, real hardware I/O). Return mock data instead (e.g., `return "test-refreshed-token"`).
127- Tests must be deterministic and reproducible across macOS and Linux.
128- Vendored SQLite hashes are validated at build time.
129- Use `std.testing.tmpDir(.{})` with `defer tmp.cleanup()` for file-based test fixtures.
130- Contract tests in `src/memory/engines/contract_test.zig` verify all memory backends satisfy the same vtable invariants. Follow this pattern when adding new backends.
131- Test helpers (e.g., `TestHelper` structs with `dummyConfig()` / `initTestChannel()`) are defined within each module. Prefer this pattern over shared test utilities.
132- Test naming: `subject_expected_behavior` (e.g., `"sendUrl constructs correct URL"`).
133 
134## Versioning
135 
136CalVer format: `YYYY.M.D` (e.g., `v2026.2.26`). Defined in `build.zig.zon`.
137 
138## CI
139 
140Tests run on Ubuntu (x86_64), macOS (aarch64), and Windows (x86_64). Release builds target 7 platforms including linux-riscv64. Docker images published to ghcr.io (linux/amd64, linux/arm64).
141 
142## Docker
143 
144Multi-stage build: Alpine builder with Zig, then minimal Alpine runtime. Runs as non-root (uid 65534) by default. Use `--target release-root` for root access.
145 
146```bash
147docker-compose --profile gateway up   # HTTP gateway daemon
148docker-compose --profile agent up     # interactive agent
149```
150 
151## Nix
152 
153`flake.nix` provides a dev shell with Zig and ZLS. Activate with `direnv allow` (uses `.envrc`).
154 
155## License
156 
157MIT License.
158