# hiveloom

**Build an agent for a repeatable job. Check its answers. Improve it from evidence.**

An agent is a model plus its harness. hiveloom makes the harness a portable
folder containing task instructions, tools, context policy, budgets, stopping
rules, and acceptance checks. Run it through the CLI, Python SDK, HTTP, or MCP;
each run returns an outcome and leaves a journal you can inspect.

> **1.3.0**, released 4 October 2026. See the
> [release notes](/release-notes) for changes and upgrade considerations.
> Earlier releases remain available as [versioned documentation](/v1.2.0/).

## What you can do

| Your job | What hiveloom provides | Start with |
|---|---|---|
| Turn a recurring task into an agent | Validated construction, declared tools, enforced workflow phases, output checks | [Quickstart](/quickstart) |
| Find out whether it works | Versioned evals, case metrics, model identity checks, cost and outcome reports | [Local evaluations](/evaluating) |
| Explain a failure | Run journal, context at each model call, failure signals, forks and resume | [Workbench](/workbench) or [Journal](/journal) |
| Improve it deliberately | Aimed proposals, assessment, measured keep-or-revert experiments | [Signal-driven evolution](/signal-driven-evolution) |
| Run improvement unattended | A research director, bounded experiments, held-out confirmation, one proposal to review | [Research programs](/research) |
| Put it into an application | Python embedding, MCP tools, HTTP serving, portable packages | [Deploying and evolving](/deploying-and-evolving) |

## Build once, run repeatedly

A summarizer can be required to return a JSON object. A retrieval harness can
be required to select IDs from tool evidence. A triage harness can be checked
against the actual queue for missing, duplicate, closed, or invented tickets.
Validators turn those requirements into feedback the loop can act on, and a
failure status when it cannot satisfy them within the budget.

The author chooses the executor model. A small model may be sufficient for a
narrow task; a larger one may earn its cost. [Measure that choice](/evals)
rather than assuming a harness makes every model better.

| Boundary | Runtime behavior |
|---|---|
| Capabilities | The model can call only tools offered by the harness and current phase or playbook. |
| Autonomy | Declared turn, context, cost, time, and tool limits bound execution. |
| Acceptance | With verification required, declared validators must pass before the run reports success. |
| Change | Evolution can change only permitted fields; safety-critical fields stay frozen. |
| Evidence | Spec and referenced behavioral code are fingerprinted; the journal records calls, results, and verdicts. |

**A passing validator establishes what that validator checks.** A JSON schema
proves shape, not factual accuracy. Grounding checks prove references came from
declared evidence, not that the source is correct. Choose checks that match the
job. [Task confinement](/task-confinement) explains the runtime boundary and
the limits of arbitrary Python hooks and optional OS process isolation.

## New in 1.3.0: improvement as a bounded program

`hiveloom evolve --research` runs the improvement loop across multiple rounds.
You provide an eval or approve an evaluation contract built from your concepts,
choose which fields may change, classify effectful tools, and set a budget.

The director investigates failures and designs candidates. The engine runs and
scores experiments, keeps eligible changes, reserves budget for a sealed
confirmation, and stops on a goal, limit, lack of progress, or an observed
ceiling. Candidate runs stay separate from production evidence.

By default the result is a queued proposal. `--yes` explicitly permits applying
it when confirmation is `confirmed` or `supported`. Concepts mode still needs
contract approval and may ask for labels. Read [Research programs](/research)
before starting a paid program.

The [workbench](/workbench) exposes progress, case comparisons, contracts,
questions, budget pools, reports, and proposals beside the copilot. It also
separates machine-level provider setup from a harness's own model and memory
settings, and gives forks an explicit resume action.

## Choose an entry point

**CLI:** follow the [Quickstart](/quickstart). Inspect the schema and catalog,
construct a harness, validate it, and dry-run before making a model call.
Commands support `--json` for agent and script integration.

**Workbench:** follow [Install](/install) to open the workbench from the
`v1.3.0` source tag, and configure a provider in Settings → Models. Ask the copilot to build or inspect
a harness, then use the workspace to read the underlying evidence directly.
The workbench ships separately from the runtime.

**Examples:** [Demo harnesses](/demos) separates the current live examples from
scripted fixtures that demonstrate runtime mechanics without credentials.

For field-level detail use the [Harness spec](/spec), [Models and
providers](/models), and [Extending](/extending). For task handoffs between
harnesses see [Delegation](/delegation).

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