Pig

Pig is a local-first coding-agent project implemented in Zig.

The Zig implementation targets Zig 0.16.x.

M0 established the engineering foundation and CLI diagnostics. M1 added the provider layer foundation: provider message/content types, unified streaming events, SSE parsing, OpenAI-compatible recorded parser, Anthropic recorded parser, provider auth resolution, and optional live smoke harness. M2 added the reusable core agent runtime: state ownership, turn loop, provider-event bridge, fake tool-call loop, agent events, middleware hooks, cooperative abort, and offline agent fixtures. M3 added built-in local coding tools: read, write, edit, bash, grep, find, and ls. M4 added the local append-only session JSONL store and context tree foundation. M5 added print/json CLI modes, M6 added the terminal UI foundation and live interactive loop, and M7 added config/auth/models/resources loading.

Available local commands:

zig build run
zig build run -- --version
zig build run -- --help
zig build run -- doctor
zig build run -- paths
zig build run -- --interactive

Zig Requirements

• Zig 0.16.x
• No third-party Zig dependencies in M1

Check your version:

zig version

Zig Build and Test

Default checks are offline:

zig build
zig build test
zig build smoke
zig build provider-fixtures
zig build agent-fixtures
zig build tools-fixtures
zig build session-fixtures
zig build provider-live
zig build fmt-check

zig build provider-live skips unless explicitly enabled. M1 includes the live harness; actual live HTTP streaming transport currently reports unsupported when fully enabled. To attempt a live OpenAI-compatible streaming check once transport is implemented:

PIG_PROVIDER_LIVE=1 \
PIG_OPENAI_COMPAT_BASE_URL="https://..." \
PIG_OPENAI_COMPAT_API_KEY="..." \
PIG_OPENAI_COMPAT_MODEL="..." \
zig build provider-live

API keys must come from the environment and must not be committed.

Zig Project Structure

• build.zig / build.zig.zon — Zig 0.16 build configuration
• src/main.zig — Zig CLI entry point
• src/app — CLI dispatch and build info
• src/core — shared errors, ID placeholders, and M2 core.agent runtime
• src/provider — M1 provider models, events, SSE parsing, auth, transport, recorded parsers
• src/tools — M3 built-in coding tools, metadata, approval, path policy, and registry adapter
• src/session — M4 session entry DTOs, append-only JSONL store, and context tree index
• src/resources — settings, model registry, context files, metadata discovery, and warnings
• src/tui — terminal lifecycle, input decoding, editor state, layout, components, renderer, and testing helpers
• src/rpc / src/plugin — protocol version placeholders
• src/util — path and testing helpers
• test — unit, fixture, provider, and agent runtime tests
• fixtures — small offline fixtures
• docs — architecture, error, fixture, allocator, and provider notes

Documentation

• docs/architecture.md
• docs/error-model.md
• docs/fixtures.md
• docs/allocator-policy.md
• docs/provider-events.md
• docs/provider-auth.md
• docs/provider-transport.md

Notes

• .env is local-only and gitignored.
• Default tests are offline and do not require API keys.
• M2 agent runtime is available as a reusable core module and is tested with scripted providers/fake tools.
• M3 built-in coding tools are available as reusable modules and through the M2 tool registry adapter.
• pig with no arguments starts the terminal UI. In non-TTY contexts, interactive mode uses a cooked fallback and exits cleanly on EOF.