sprawl

A collection of composable, Unix-philosophy tools for multi-agent orchestration. Built in Zig with dual-layer storage (JSONL + SQLite).

Philosophy

These tools decompose orchestration into focused primitives that each do one thing well. The goal is not to build a monolithic orchestration system, but to create tools that naturally compose into orchestration when needed.

┌─────────────────────────────────────────────────────────────┐
│                      AGENT / PROMPT                         │
├─────────────────────────────────────────────────────────────┤
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐    │
│  │  tix   │ │  box   │ │  vent  │ │  hold  │ │  mon   │    │
│  │ tasks  │ │messages│ │ events │ │ block  │ │monitor │    │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘    │
└─────────────────────────────────────────────────────────────┘

Tools

Tool	Description	Repository
tix	Lightweight issue tracker with dependencies, priorities, tags, and full-text search	fielding/tix
box	Mailbox messaging system for agent-to-agent communication	fielding/box
vent	Event logging system for observability and debugging	fielding/vent
hold	Block until a shell condition is met	fielding/hold
mon	TUI for humans to monitor multi-agent orchestration	fielding/mon

Quick Examples

# Task tracking
tix add "Fix login bug" -p 1 -a alice -t bug
tix list --status open

# Agent messaging
box send orchestrator -s "Review complete" -m "Found 3 issues"
box inbox alice

# Event logging
vent emit orchestrator "phase transition" --data '{"from": "review", "to": "discussion"}'
vent tail --source opus

# Wait for conditions
hold "box inbox me --json | jq -e 'length > 0'"
hold --timeout 30s "curl -sf localhost:8080/health"

# Monitor everything
mon

Integration Patterns

Wait for Messages, Then Process

hold "box inbox me --json | jq -e 'length > 0'"
msg_id=$(box inbox me --json | jq -r '.[0].id')
box read $msg_id

Assign Work and Wait for Completion

task_id=$(tix add "Implement feature" -a worker)
box send worker -s "New task" -m "Check tix ready"
hold "tix show $task_id --json | jq -e '.status == \"closed\"'"

Condition-Based Orchestration

# Wait for all workers to check in
hold "box inbox orchestrator --json | jq -e 'length >= 3'"

Shared Infrastructure

Dual Storage (tix, box, vent)

• JSONL: Append-only, git-friendly, source of truth
• SQLite: Fast queries, FTS5 full-text search

ID Schemes

• prefix-hash - Issues (tix) - e.g., tix-a3f2b1
• msg_ULID - Messages (box) - 26-char ULID, sortable
• evt_ULID - Events (vent) - 26-char ULID, sortable

JSON Output

All tools support --json for machine-readable output, enabling composition with jq.

Design Principles

1. Emergence over Design - Don't build infrastructure until patterns emerge from real usage
2. Composition over Integration - Tools work together via stdin/stdout/exit codes
3. Shell as Glue - Bash scripts orchestrate tools
4. Exit Codes Matter - Enables &&, ||, hold, if
5. JSON for Machines - --json flag for scripting
6. Files as State - JSONL is git-friendly, debuggable, recoverable

Building

Each tool is built with Zig:

git clone https://github.com/fielding/tix && cd tix && zig build -Doptimize=ReleaseFast
git clone https://github.com/fielding/box && cd box && zig build -Doptimize=ReleaseFast
git clone https://github.com/fielding/vent && cd vent && zig build -Doptimize=ReleaseFast
git clone https://github.com/fielding/hold && cd hold && zig build -Doptimize=ReleaseFast
git clone https://github.com/fielding/mon && cd mon && zig build -Doptimize=ReleaseFast

Binaries are placed in ./zig-out/bin/.

License

MIT