Introduction
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 for changes and upgrade considerations. Earlier releases remain available as versioned documentation.
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 |
| Find out whether it works | Versioned evals, case metrics, model identity checks, cost and outcome reports | Local evaluations |
| Explain a failure | Run journal, context at each model call, failure signals, forks and resume | Workbench or Journal |
| Improve it deliberately | Aimed proposals, assessment, measured keep-or-revert experiments | Signal-driven evolution |
| Run improvement unattended | A research director, bounded experiments, held-out confirmation, one proposal to review | Research programs |
| Put it into an application | Python embedding, MCP tools, HTTP serving, portable packages | 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 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 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
before starting a paid program.
The 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. 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 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 separates the current live examples from scripted fixtures that demonstrate runtime mechanics without credentials.
For field-level detail use the Harness spec, Models and providers, and Extending. For task handoffs between harnesses see Delegation.
Apache-2.0 licensed. Source: FrancescoMrn/hiveloom.