name	tau-maintenance
description	Maintain the tau codebase (Zig 0.16, non-interactive agent-first CLI). Use when maintaining, extending, or debugging tau.

tau-maintenance (local — tau project)

A maintenance guide for the tau codebase — a Zig 0.16, non-interactive, agent-first CLI. Lives at this project root.

Build & Test

zig build                    # Compile (binary → zig-out/bin/tau)
zig build test               # Full test suite
./scripts/smoke.sh           # Offline smoke tests
./scripts/smoke.sh --net     # Online smoke tests

Project at a glance

File	Purpose
`src/main.zig`	CLI parse → dispatch. Owns `help_text` and `flag_specs` (must stay in sync).
`src/args.zig`	Argv parser. `Action` enum + `Parsed` struct.
`src/agent.zig`	Single-turn agentic tool loop.
`src/goal.zig`	Goal directive + `<GOAL_MET>` sentinel.
`src/loop.zig`	Author↔Critic primitive.
`src/fleet.zig`	Fleet orchestration (run/status/list/logs/cancel).
`src/config.zig`	`Config` struct + `Provider` / `Role` / `AcpSub` enums.
`src/acp.zig`	Agent Client Protocol server.
`src/llm/provider.zig`	`Message` / `ToolCall` / `Response` / `complete` / `completeStreamWithTools`.
`src/session.zig`	Session persistence at `~/.config/tau/sessions/`.
`src/context.zig`	Auto-compaction at threshold fraction of context_window.
`src/skills.zig`	Skills autodiscovery (`tau skills list\|search\|load`).
`src/agents_md.zig`	AGENTS.md scanner (`--scan-agents`).
`src/tools/{bash,read,write,edit,ls,grep,find}.zig`	Built-in tools.

Known issues (v0.4)

Skills JSON escape: descriptions with " produce malformed JSON. Fix: escape before {s} insertion.
Fleet cancel: global_status: cancelled is in-memory only (not persisted across tau restarts).
Fleet worker results: workers report status: running until the harness polls.
topoSort cycles: surface as {"code":110,"message":"toposort failed: Cycle"}.
--schema + --dry-run: schema flag is set but not applied to dry-run planning turn.

Allocator conventions

All public functions that allocate take gpa: std.mem.Allocator and arena: std.mem.Allocator explicitly.
gpa is freed manually; arena is per-process scratch space.
Config is passed by value with anytype in some helpers.
[]const u8 strings owned by the arena are sliced out of argv_list / msg_parts / sys_parts.

Zig 0.16 gotchas

orelse try requires a block — use orelse blk: { ... break :blk value; }
if (x) \|y\| defer ...; is invalid — defer must be at statement level
Empty string literal "" is *const [0:0]u8 — use &.{} for empty slice
spawn returns *const Child — use \|*ch\| to call wait

Deployment gotchas

rbm21 / LXC containers: "Illegal instruction" (exit 132)

When building for deployment on LXC containers (especially Proxmox LXC like rbm21), the default zig build -Doptimize=ReleaseSafe may produce a binary that crashes with Illegal instruction (exit 132) because Zig emits modern x86-64 instructions the target CPU doesn't support.

Fix: Build with a conservative CPU baseline:

zig build -Doptimize=ReleaseSafe -Dcpu=x86_64_v2

This targets the x86-64-v2 microarchitecture level (roughly Sandy Bridge / 2011), which is compatible with virtually all x86-64 LXC hosts. The binary is slightly larger (~5.4MB vs ~5.3MB) and may be a few percent slower, but runs everywhere.

Check the target CPU:

ssh rbm21 "cat /proc/cpuinfo | grep 'model name' | head -1"
# → 13th Gen Intel(R) Core(TM) i5-13400T  (still needed -Dcpu=x86_64_v2!)

name	tau-maintenance
description	Maintain the tau codebase (Zig 0.16, non-interactive agent-first CLI). Use when maintaining, extending, or debugging tau.