Hornet

Give a local model a coding goal. Keep the work when the conversation ends.

Hornet turns a goal into small cells with explicit file scopes, typed results, acceptance checks and attempt budgets. Each model request gets bounded working context. Files, failed attempts and recovery evidence stay on disk.

It is a command-line tool for developers using local models, including an OpenAI-compatible LM Studio server. Python 3.9+; no runtime Python dependencies.

Install from PyPI

Hornet on PyPI is available as matrixswarm-hornet. Install it in a Python 3.9+ virtual environment:

python -m pip install matrixswarm-hornet
python -m hornet --version
python -m hornet --help

The package also installs the hornet command. Follow the walkthrough below to configure a worker VM and connect your local model for coding goals.

Try one completed goal

1. Open the latest signed release.
2. Download the starter ZIP, SHA256SUMS, SHA256SUMS.asc, the public signing key and VERIFY-RELEASE.md.
3. Verify the download, extract it, and follow START-HERE.md inside.

The walkthrough installs Hornet, checks a local file contract, creates a new Ubuntu worker VM and asks your local model to fix a small Python function. The starter VM setup supports Windows or Linux hosts with VirtualBox. The model runs on the host; agent code runs inside the dedicated VM.

Read the first-goal walkthrough and worker setup before running the demo. Use the downloadable starter for the ready-to-install wheel; GitHub's automatic source archive does not contain that wheel.

What Hornet keeps track of

Workers currently execute sequentially. Separate goal directories share the VM account; the dedicated VM supplies the execution boundary. Passing generated checks is evidence of the checked behavior, and exported code still needs review.

Named agents

Hornet supports a project-root hive.json mapping labels to model connections. Run hornet hive init, select --agent gemma, or assign an unfinished goal cell with hornet hive assign RUN CELL --agent qwen. See the hive guide for role routing, shared resource claims and resume. Named agents are available in 0.16.0 and later.

Quiet supervision

In 0.17.0, explicitly enroll saved goals for bounded automatic resume. The periodic scan uses no inference and respects pauses, questions, active workers and remaining budgets. Each activation leaves a receipt; uncertain outcomes stay stopped for inspection. See the supervisor guide.

Discoverable tools for coding cells

Hornet 0.18.1 improves worker setup errors: missing credential fields, local file paths and the required worker account are checked before SSH. See worker setup troubleshooting.

Hornet 0.18.0 adds a cell tool registry. Agents discover a capability, inspect its exact contract, apply a scoped transformation, and retain write and readback receipts. Use --registry-only to require these tools for edits:

hornet autowork --worker-config coding/worker.json --agent gemma --scope-file calculator.py --registry-only --goal "Fix integer doubling and preserve the public interface."

Replace gemma with your configured hive label. The registry offers 17 reviewed cell tools for Python, JSON and text, plus two recipes. The controller checks source hashes, enforces file scope, and runs the cell and goal acceptance checks. See the registry guide for namespaces, discovery, extension rules and the standalone MCP server.

Questions wait for you

hornet questions coding/recipes/RUN_ID
hornet answer coding/recipes/RUN_ID q-EXACT_QUESTION_ID --text "Use the existing configuration."
hornet autoresume coding/recipes/RUN_ID

An answer is saved before execution resumes. waiting_for_user is a pause; completed is a separate result. There is no background model polling while a required question waits. Use resume for standalone work runs.

A measured first run

In the 0.15.0 first-user trial, Gemma 12B completed the small coding demo using 16 model requests and 5 tool calls, with a peak input of 3,084 tokens. Only calculator.py changed; independent checks returned [-6, 0, 14]. The original worker baseline was preserved.

That was one focused goal on a fresh Python environment and Ubuntu VM on an existing Windows host. It is not a general model-reliability benchmark. See the validation record.

Install from source

git clone https://github.com/matrixswarm/hornet.git
cd hornet
python -m venv .venv

On Windows:

.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\hornet.exe --version

On Linux/macOS:

.venv/bin/python -m pip install .
.venv/bin/hornet --version

Our publishing workflow verifies the signed GitHub package files before uploading those same bytes to PyPI. See the CLI reference for goals, revisions, contracts and recovery commands.

Upgrading

Install the new version in a separate environment and use its matching starter for a new worker. Preserve the old environment, VM, keys and saved goals together. Worker code and registry bindings are checked when loading saved work, including completed cells and linked revisions. This release does not migrate existing deployments or registry bindings.

Project

Created and led by Daniel F. MacDonald, with AI engineering collaboration credited in AUTHORS.md. See CONTRIBUTING.md for development and SECURITY.md for the execution boundary and reporting.

The roadmap records planned work, including a Strategy-pattern builder that assembles agent implementations through durable contracts.

License

Copyright (c) 2026 Daniel F. MacDonald. Licensed under AGPL-3.0-only; see LICENSE.

Victory Always.

Hive terminal

Run hornet hive terminal from the project root to browse saved goals, all cells and active cells. Select a cell to see its inverted tree, agent, observed checks and time since the last recorded action. Named connections may use local or compatible remote model servers. See Hive connections and the terminal guide. These features are available in 0.16.0.

The goal controller adds optional root-plan approval by a user or named supervisor, bounded recovery for repeated cell operations, and a closeout receipt after the controller releases its leases. Drafts, rejected attempts and frozen checks stay available across resumes.