# hiveloom

**Confine an agent to one job — and make success provable.**

**An agent is a model plus its harness.** hiveloom turns the harness for a
repeatable task into a self-contained folder: the task, tools, context, budgets,
stopping rules, and validators. A human or a capable coding agent can declare
that boundary; a smaller model can then execute inside it repeatedly. The
runtime decides whether the result counts as success.

> **Released:** `1.2.0` (25 September 2026), installable with
> `uv tool install "hiveloom==1.2.0"`. The spec, CLI, Python SDK, runtime,
> journal/Hive memory, generation, gated and signal-driven evolution,
> packaging, MCP integration, delegation between harnesses, and HTTP serving
> surfaces are implemented, along with playbooks, structured artifacts, run
> control, run-scoped notes and durable memory, and a tamper-evident run
> journal you can fork from, replay, and read in [the workbench](/workbench).

## New in 1.2.0

The signal, memory and collaboration release. Full details in the
[release notes](/release-notes).

- **Evolution finds the signal before it proposes.** `hiveloom signal`
  contrasts failing and successful runs feature by feature, counts the
  mechanisms a change would be judged by, and says how much the sample can
  show — for free, before any model call. Every proposal then names the signal
  it aims at and predicts how it will move; `hiveloom assess` checks that
  prediction against the runs that follow, and `evolve --experiment` keeps a
  change only when an eval confirms it. See
  [Signal-driven evolution](/signal-driven-evolution).
- **Memory that scales and learns.** Durable lessons live in `harness.yaml`
  and reach it only through reviewed proposals; with `memory.selection:
  relevant` each run sees only the lessons that match its task. Reflection
  drafts lessons from failed runs for review. Run-scoped `notes` survive
  compaction, and `transform_result` narrows large stored results in place.
- **Delegation between harnesses.** A harness hands a task to a peer that has
  *earned* it in measured runs — locally or over MCP — verifies the answer with
  its own validators, and otherwise names the peer as a referral. See
  [Delegation](/delegation).
- **Runs that recover.** Truncated turns continue within declared budgets,
  transient provider failures are retried, and compaction carries the previous
  summary forward instead of re-summarizing it.
- **Ten demo harnesses as proof.** Each one states what it proves and the
  evidence to look for; four run offline with no API key. See
  [Demo harnesses](/demos).

Upgrading from 1.1.0: a proposal from `evolve` or auto-propose must now name a
`target` from the signal map (a model or script emitting the old proposal shape
needs the field), and a guardrail-blocked output is never returned, even when a
run exhausts its turns — see [release notes](/release-notes).

## The product is the boundary

| The harness confines | How |
|---|---|
| **Purpose** | One task and one system prompt travel with the harness. |
| **Capabilities** | Only declared tools, skills, playbooks, MCP servers, and registered peers enter the loop. |
| **Autonomy** | Turn, time, cost, context, and tool policies bound execution. |
| **Acceptance** | Deterministic validators — not the model — decide whether an answer counts as success. |
| **Change** | Evolution is limited to declared mutable fields, aimed at measured signal, and checked against its own prediction; safety-critical fields stay frozen. |
| **Evidence** | Every run is tied to the exact harness version and written to a checkable journal. |

This is [task confinement](/task-confinement), not a claim that arbitrary code
runs in a virtual machine. It makes a harness more reliable than a prompt and
narrower than a general-purpose agent.

The interface is agent-native on both sides: builder agents inspect the schema
and catalog and drive the JSON-speaking construction CLI; calling agents use a
finished harness through MCP and receive a structured, validator-checked result.

## Where to go next

| If you want to | Read |
|---|---|
| Get it running in five minutes | [Install](/install) then [Quickstart](/quickstart) |
| See each capability proven on a small task | [Demo harnesses](/demos) |
| Understand the product boundary | [Task confinement](/task-confinement) |
| Build one without learning the CLI first | [The workbench](/workbench) |
| Know whether a harness actually helps | [Evaluations](/evals) |
| Measure one on your own dataset | [Local evaluations](/evaluating) |
| Improve one from evidence, and prove the change | [Signal-driven evolution](/signal-driven-evolution) |
| Let harnesses hand work to each other | [Delegation](/delegation) |
| Understand every field in `harness.yaml` | [Harness spec](/spec) |
| See how the runtime fits together | [Architecture](/architecture) |
| Debug a failed run at the turn it went wrong | [Journal and forks](/journal) |
| Point a harness at a different lab | [Models and providers](/models) |
| Add your own tools or providers | [Extending](/extending) |
| Ship and keep improving it | [Deploying and evolving](/deploying-and-evolving) |
| Drive a served harness over HTTP | [Control plane](/control-plane) |

## Two ways in

**The CLI** builds a harness through one validated construction path — `init`,
`add`, `set`, `validate`, `run` — and every command speaks `--json`, so it
scripts cleanly. Start at the [Quickstart](/quickstart).

**[The workbench](/workbench)** is the same framework with a face: a chat-first
development UI where you talk to a copilot that creates, validates, runs, and
diagnoses harnesses for you, with the exact framework state — spec, runs, the
full journal of any one of them, version comparisons, pending proposals — open
beside the conversation. It is the fastest way to see what a harness actually
did, and the only comfortable way to read a long run back.

## Safety invariants

- Evolution can never change `id`, `guardrails`, `model`, `logging.redact`,
  `extensions`, `hooks`, `mcp_servers`, `confinement`, `egress`,
  `evolution.auto_propose`, `evolution.reflect`, `evolution.trace_excerpts`,
  `evolution.objectives`, or the `memory` budgets.
- The executor never writes durable memory; lessons reach `harness.yaml` only
  through a reviewed proposal.
- A guardrail-blocked output is never handed back to the caller.
- The cost guardrail defaults on at `$1.00`.
- The shell tool is disabled unless explicitly configured and remains
  allowlist-only; spawned processes are confined.
- Redaction runs before trace persistence, and provider egress is screened.
- Foreign harness code is trust-gated before loading; a delegation peer is
  offered only once trusted.

Apache-2.0 licensed. Source at
[github.com/FrancescoMrn/hiveloom](https://github.com/FrancescoMrn/hiveloom).