This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
A Zig SDK for building agentic LLM applications. Three build targets:
- Zig module (
src/root.zig) — for@import("agent")consumers - C ABI shared library (
src/c_api.zig) —libagent.so/.dylibfor FFI - NAPI addon (
napi/src/bridge.zig) —agent_napi.nodefor Node.js
Zero external dependencies — Zig standard library only.
zig build # Build all (lib + shared lib)
zig build test # Run all tests (unit via root.zig + e2e smoke test)
zig build napi # Build NAPI addon → zig-out/napi/agent_napi.nodeMinimum Zig version: 0.14.0
QueryEngine → QueryLoop → Provider.stream_text() → EventIterator
The agentic loop lives in src/query.zig. QueryLoopIterator drives phases: start → streaming → tool_dispatch → tool_collecting → yielding_result → done. QueryEngine (src/query_engine.zig) is the high-level API that owns the message store, session, and drives the loop.
- VTable polymorphism:
Tool,Provider, andContextStrategyall use type-erasedptr+ function table for runtime dispatch.buildTool(T, impl)generates VTables at comptime from struct declarations. - Dependency injection:
ToolUseContextcarries all context (allocator, cwd, abort, file_cache, permissions, hooks) — tools receive it, never reach for globals. - Pull-based streaming:
EventIteratorwithnext()callback for lazy evaluation. - DAG-linked messages: Every
Messagecarries aHeaderwithuuidandparent_uuid, enabling branching conversations and undo. - Receipt-order tool yielding:
StreamingToolExecutoryields tool results in the order they were requested, not completion order. - Atomic cancellation:
AbortControllerwith acquire/release semantics.
| Module | Role |
|---|---|
query_engine |
High-level API: owns messages, session, drives query loop |
query |
Agentic loop iterator with phase transitions (tool_use, compact, escalate) |
providers/ |
LLM backends — anthropic, openai_compat, ollama via Provider VTable |
streaming/events |
Event tagged union (text_delta, tool_use, thinking, result, etc.) + EventIterator |
streaming/tool_executor |
Tracks concurrent tool invocations, yields in receipt order |
tool |
Tool VTable + ToolUseContext DI container + buildTool() comptime helper |
tools/registry |
ToolRegistry — StringHashMap of Tool by name |
message |
Message tagged union (User/Assistant/System/Progress/Tombstone) with Header DAG |
permission |
7-step evaluation chain: deny rules → ask rules → tool callback → bypass → allow rules → default ask → dont_ask deny |
hook |
HookRunner with 24+ event types; exit 0=ok, 2=block, other=warn |
context/ |
Context trimming — SlidingWindowStrategy keeps last N logical turns |
session |
Transcript persistence to disk with retry-flush |
file_cache |
LRU FileStateCache with max_entries + max_size_bytes eviction |
compact |
Token estimation (4 chars ≈ 1 token), compaction boundary markers |
http/ |
HttpClient + SseParser for streaming API calls |
json |
Thin wrappers around std.json + JsonSchema type |
c_api |
C ABI surface: opaque handles for Engine/Provider/Iterator/ToolRegistry |
testing |
MockProvider (scripted responses) + FakeTool (records calls) |
Node.js → napi/src/bridge.zig → src/c_api.zig → src/query_engine.zig
→ src/providers/*.zig
The NAPI bridge (napi/src/bridge.zig) wraps C API functions with Node-API calling conventions. napi/index.js loads the .node addon (tries zig-out/napi/ first, then bundled). TypeScript types are in napi/ts/index.d.ts.
Unit tests are discovered through src/root.zig (which re-exports all modules). The E2E smoke test (tests/e2e_smoke_test.zig) demonstrates the standard usage pattern:
- Create
MockProviderwith scripted responses - Register
FakeToolin aToolRegistry - Create
QueryEnginewith bypass permissions submitMessage()→ consumeEventIterator→ verify events and tool calls