Zaica: The Focused Coding Agent

What is Zaica?

Zaica (pronounced "ZAI-tsah") is a Zig AI coding assistant that runs in your terminal, calls tools autonomously, and streams responses in real-time. It is built from scratch in Zig 0.15 with zero runtime dependencies beyond the standard library, plus two optional dependencies: vaxis (terminal UI library) and zefx (a custom reactive state management library, both authored by the same developer).

The binary is distributed via Homebrew for macOS (aarch64 + x86_64) and Linux (aarch64 + x86_64), with pre-built binaries on GitHub releases. It uses std.http.Client directly — no HTTP library dependency.

Architecture overview

The agentic loop (node.zig)

The central abstraction is the Node in src/node.zig (731 lines). It is the generic agentic loop used by both the REPL and sub-agents:

1. LLM call — sends accumulated message history to the provider with streaming enabled
2. Parse response — accumulates SSE deltas into content text and tool call fragments
3. Execute tools — runs each tool call (parallel in terminal mode, sequential in silent mode)
4. Append results — tool results become tool_result messages in history
5. Repeat — up to the iteration limit, or until no more tool calls

Parallel tool execution is a key feature: in terminal mode, tools run in parallel using std.Thread.spawn — each tool executes in its own OS thread with a done-flag atomic (std.atomic.Value(bool)) tracking completion. In silent mode (sub-agents, chain mode), tools run sequentially to avoid "threads-inside-threads."

Wyhash loop detection

Zaica implements a sophisticated loop detection system in src/node.zig using a Wyhash-based ring buffer of tool call signatures (tool name + args hash). It detects repeating patterns of length 1, 2, or 3 within a 10-call window with a 3-tier escalation:

• Tier 1 — Warning message to the LLM: "You seem to be repeating the same actions"
• Tier 2 — Stronger "STOP" warning with explicit instruction to change approach
• Tier 3 — Force break the loop with a summary instruction

This is significantly more nuanced than simple tool-name deduplication. The same tool called with different arguments or producing different output gets a different hash.

6 provider support

All providers use the OpenAI-compatible /chat/completions endpoint format except Anthropic, which uses the .anthropic_native tool format. The wire format enum (ToolFormat) is defined in src/config/types.zig with three variants: openai_compatible, anthropic_native, and gemini_native.

The HTTP client (src/client/http.zig, 388 lines) uses Zig 0.15's std.http.Client API directly. It disables compression (.accept_encoding = .omit) because SSE needs a raw byte stream.

The SSE parser (src/client/sse.zig, 408 lines) parses each data: {json} line and returns a tagged union with variants: .content, .reasoning, .tool_call_delta, .done (carrying token usage), and .api_error.

The 7 tools

Zaica ships with exactly 7 tools, each with a declared risk level:

Tool output truncation uses a head/tail strategy — keeping the first half and last half of the output, with a truncation warning marker in the middle. This aligns with the "Attractor coding-agent-loop-spec." Per-type limits: read_file caps at 50,000 chars; execute_bash at 30,000 chars / 256 lines.

3-tier permission system

Zaica's permission model is elegantly simple:

• [y]es all — all tools allowed
• [s]afe only — only read-only tools (read_file, list_files, search_files)
• [n]o — nothing allowed

The ask happens once per session. The --yolo / --dangerously-skip-permissions CLI flag grants all tools automatically.

Bash execution wraps commands in a safety wrapper that: redirects stdin from /dev/null (interactive programs get EOF and exit immediately), sets a timer that kills the process tree with pkill -9 -P $PID then kill -9 $PID, detects SIGKILL (exit code 137) to report timeout, and caps output at 1 MB.

Chain mode: structured workflows

Chain mode (src/chain.zig, 528 lines) is one of zaica's most distinctive features. It allows you to define multi-step pipelines in .chain.md markdown files with YAML frontmatter:

Each step has: name, prompt (with {task} and {previous} variable substitution), optional tool filter, and max_iterations.

Reactive state management (zefx)

Instead of imperative state management, zaica uses a custom Effector-inspired reactive state machine (lib/zefx/). Events trigger Store reducers, which trigger watchers. This gives a declarative data flow:

tokens_received event → prompt_tokens / completion_tokens stores → total_tokens derived store → status bar watcher.

The engine uses a two-phase flush (pure reducers first, then effects) ensuring watchers always see consistent state. This is a genuinely novel approach in a coding agent — no other agent in this set uses a reactive state graph for UI state.

Terminal-level control

Unlike Python agents that rely on libraries like rich or prompt_toolkit, zaica does raw /dev/tty access with manual tcsetattr for cooked/uncooked/stream modes, manual escape sequence parsing (CSI, CSI u), and direct ioctl for terminal size.

It supports full UTF-8 and Cyrillic input including Cyrillic keyboard layout mapping for Ctrl keys. The REPL (src/repl.zig, 2,153 lines) implements manual line editing with history — no readline dependency.

Skills system

Skills are SKILL.md files with JSON frontmatter in .zaica/skills/<name>/ (project-local) or ~/.config/zaica/skills/<name>/ (user-global).

• "Always-on" skills are injected directly into the system prompt
• Other skills appear as an XML summary that the LLM can load on demand via load_skill
• Skills can declare required binaries/env vars; missing ones are reported to the LLM

Session management

Sessions are stored as JSONL files in ~/.config/zaica/sessions/<timestamp>.jsonl. Each line is a typed JSON object: meta, text, tool_use, tool_result, or summary.

Supports listing, loading, resuming (-c / --continue), and targeting specific sessions (--session <id>).

6-layer config system

The config module (src/config/, 9 files, ~1,500 lines) implements a 6-layer priority chain:

1. Comptime defaults — hardcoded at compile time
2. Provider presets — per-provider default models/settings
3. ~/.config/zaica/config.json — user config
4. .zaica.json — project-level config
5. ZAICA_* env vars — environment overrides
6. CLI flags — highest priority

API key resolution follows a 4-tier chain: CLI flag → ZAICA_API_KEY → {PROVIDER}_API_KEY → ~/.config/zaica/auth.json.

Unique engineering decisions

Strengths

• Code quality — ~9,100 lines with extensive test coverage across all modules
• Focus — stays tight on the coding agent experience without feature creep
• Reactive state graph — the zefx engine is genuinely novel UI architecture
• Chain mode — structured workflows with per-step tool filtering
• Loop detection — Wyhash-based 3-tier escalation is the best in this set
• Terminal craftsmanship — raw /dev/tty, Cyrillic, manual line editing
• Parallel sub-agents — OS-thread-based dispatch for independent agent loops

Tradeoffs

Key files to read

Verdict