Quickstart

This builds a real harness from nothing, runs it without an API call, then runs it for real. Every mutation is validated and rolls back on error.

1. Explore the contract #

No API key needed for either of these:

hiveloom schema --annotated
hiveloom catalog tools

2. Construct a harness #

hiveloom init ./summarizer --name summarizer \
  --task "Summarize a text file into JSON."

printf '%s\n' "The quick brown fox jumps over the lazy dog." \
  > ./summarizer/notes.txt

hiveloom add tool --builtin file_read --dir ./summarizer
hiveloom add validator --builtin regex_match --pattern '"summary"' \
  --dir ./summarizer
hiveloom validate ./summarizer --json

Do not hand-edit harness.yaml. Use init, add, set, remove, or the gated evolve flow — they share one transactional construction API.

3. Assemble the first call without contacting the model #

hiveloom run ./summarizer --input notes.txt --dry-run --json

--dry-run makes no model call. Note that declared MCP servers are still contacted, because their tools are discovered eagerly.

4. Run it for real #

export ANTHROPIC_API_KEY=sk-...
hiveloom run ./summarizer --input notes.txt --json

Or point it at any other lab:

hiveloom models
hiveloom set model openai/gpt-4.1-mini --dir ./summarizer

5. Inspect evidence and propose an improvement #

hiveloom stats ./summarizer --json
hiveloom evolve ./summarizer --propose --json

evolve --propose never writes to the harness. It queues a proposal that a human applies explicitly — see Deploying and evolving.

Prefer model-driven construction? #

hiveloom generate "Summarize a text file into JSON." -o ./summarizer --json

A complete credential-free example lives in harnesses/example-summarizer.

A harness is a folder #

my-harness/
├── harness.yaml          # declarative runtime contract
├── tools/                # optional code tools
├── validators/           # optional task-specific verification
├── schemas/
├── skills/
├── .hiveloom/traces/     # append-only run memory
├── .env.example
└── requirements.txt

Core interfaces #

Every CLI command supports --json. Exit codes are stable: 0 success, 1 verification failed, 2 guardrail halt, 3 invalid spec or request, and 4 runtime failure.

# Explore and construct
hiveloom schema --json
hiveloom explain context.compaction --json
hiveloom catalog validators --json
hiveloom set loop.max_turns 20 --dir ./my-harness --json
hiveloom add tool --builtin file_read --dir ./my-harness --json

# Run and inspect
hiveloom run ./my-harness --input input.txt --stream
hiveloom trace <run-id> --json
hiveloom stats ./my-harness --json

# Improve with a human gate
hiveloom evolve ./my-harness --propose --json
hiveloom proposals list ./my-harness --json
hiveloom proposals apply ./my-harness <proposal-id> --json

# Extend and ship
hiveloom extensions --json
hiveloom mcp list-tools --dir ./my-harness --json
hiveloom package ./my-harness --docker --json
hiveloom serve ./my-harness
hiveloom mcp serve ./my-harness ./other-harness

Serving a harness to other agents #

mcp serve is the agent-facing front door. It exposes each harness as an MCP tool (run_<name>) plus a list_harnesses tool that carries each harness's measured success rate and cost — so any MCP-capable agent can pick a harness on evidence and delegate to it, getting back a structured, validator-checked result instead of improvising the task itself.

Input is always treated as literal text, and untrusted directories fail at startup (approve them with hiveloom trust). Register harnesses once and serve them together:

hiveloom registry add ./my-harness
hiveloom mcp serve --registered
hiveloom mcp serve --registered --http   # needs HIVELOOM_API_KEY

Python SDK #

The root package exposes a small, semver-stable embedding surface:

from hiveloom import (
    Hive,
    dry_run,
    generate_harness,
    load_spec,
    run_harness,
    validate_harness,
)

info = dry_run("./my-harness", "input.txt")
result = run_harness(
    "./my-harness",
    "input.txt",
    on_event=lambda event: print(event.type),
)
spec = generate_harness("Reconcile invoices", "./invoice-reconciler")

Inject a ModelProvider into run_harness or a StrongModel into generate_harness for custom embedding and deterministic tests. For language-neutral integration, use run --stream (JSONL) or serve (HTTP).