{"slug": "show-hn-hlock-an-agent-harness-lockfile-and-performance-resolver", "title": "Show HN: Hlock – an agent harness lockfile and performance resolver", "summary": "Union AI's open-source project hlock released an early-development Rust tool that writes a `harness.lock` file pinning an AI agent's harness, models, MCP servers, skills and config, with commands including `hlock pin`, `hlock check`, `hlock sync`, `hlock launch`, `hlock run`, `hlock pull`, `hlock add` and `hlock audit`. The tool installs via `pip install hlock` or `cargo add hlock`, ships prebuilt wheels for Linux (x86_64, aarch64), macOS (arm64, x86_64) and Windows (x64) on CPython 3.9+, and supports harnesses including Claude Code, Codex, Pi, OpenCode, Cursor and Gemini CLI. The project also includes eval packs (`hlock evals init -t coding`, plus `data`, `research` and `support`) that measure a pinned stack against a user's own tasks, and per-contributor locks stored at `.hlock/locks/harness.<handle>.lock`; its maintainers warn to expect rough edges and breaking changes between releases.", "body_md": "**Pin your harness, models, MCP servers, skills, and config in\na `harness.lock`, version it, and rehydrate it anywhere.**\n\nYour agent is more than a model. It's a harness, MCP servers, skills, and config,\nhand-tuned on one machine. `hlock` is the missing harness packaging layer, written in Rust 🦀:\n`harness.lock` tracks all of its dependencies, so you can commit it to git and restore\nit anywhere. When you're ready, it measures your stack against your own tasks and finds a\nbetter one.\n\n| You know this from package managers | In `hlock` | \n|---|---|\n| 🔒 `uv.lock` /`Cargo.lock` | **`harness.lock`** : every dependency of your harness, pinned and hashed | \n| 📌 `pip freeze` | **`hlock pin`** : record the setup you already have, and re-pin as it grows | \n| ✅ `--locked` check | **`hlock check`** : show what changed since the pin | \n| 📦 `uv sync` /`npm ci` | **`hlock sync`** : rehydrate the locked setup on any machine | \n| `uv run` | **`hlock launch`** and**` hlock run`** : start sessions and run prompts on the locked setup | \n\nNote\n\n**hlock is in early development.** Expect rough edges and breaking changes between\nreleases. Feedback shapes where it goes next: [open an issue](https://github.com/unionai-oss/hlock/issues/new)\nfor bugs and feature requests, [start a discussion](https://github.com/unionai-oss/hlock/discussions)\nfor questions and ideas, or send a pull request. Agent-written pull requests are\nwelcome, as long as you've reviewed and understand the change. See the\n[contributing guide](https://docs.hlock.ai/project/contributing/) to get started.\n\n```\npip install hlock        # or: uv add hlock  ·  uvx hlock --help\n```\n\nPrebuilt wheels cover Linux (x86_64, aarch64), macOS (arm64, x86_64), and Windows (x64)\nfor CPython 3.9+. For Rust, use `cargo add hlock`.\n\nPin the harness you already use (Claude Code, Codex, Pi, OpenCode, Cursor, Gemini CLI,\nand [more](https://docs.hlock.ai/guides/harnesses/)), then bring it back anywhere:\n\n```\nhlock pin --user                # lock your setup (yours in ~/.claude etc., and the project's) into harness.lock\ngit add harness.lock .hlock/    # version it (secrets are placeholders, never values)\nhlock check                     # see what changed since the pin; re-pin to lock it\nhlock sync                      # on another machine: rehydrate it into .hlock/env (or --in-place, --docker)\nhlock launch                    # start a session on the locked setup, isolated from your config\nhlock run \"summarize README.md\"  # or run one prompt through it (claude -p, codex exec, …)\nhlock pull github:alice/agents  # get someone else's pinned setup; then hlock launch --lock alice\nhlock add skill github:anthropics/skills/skills/pdf   # declare a dependency, pin it, install it\nhlock audit                     # integrity, hidden characters, what it runs, policy, secrets\n```\n\nPlain `hlock pin` records only the project's own skills, MCP servers and config, so your\npersonal setup stays out of the repository; `--user` adds it.\n\nFor your own work, `hlock evals init -t coding` (or `data`, `research`, `support`) writes\nan eval pack template plus an Agent Skill, so the agent you already use can fill it in\nwith real tasks from your project. See [Eval packs](https://docs.hlock.ai/guides/eval-packs/).\n\nSee the [Quickstart](https://docs.hlock.ai/getting-started/quickstart/),\n[Pinning your setup](https://docs.hlock.ai/guides/pin/),\n[Rehydrating with sync](https://docs.hlock.ai/guides/sync/), and\n[Launching a locked harness](https://docs.hlock.ai/guides/launch/).\n\nContributors to one repository rarely share an agent setup. Each person can commit their own\nlock to `.hlock/locks/harness.<handle>.lock`, next to the code it was used on, and anyone\nwith a clone can try a teammate's setup in isolation:\n\n```\nhlock pin -o .hlock/locks/harness.alice.lock         # your harness and model, with the repo's setup\nhlock launch --lock .hlock/locks/harness.bob.lock    # try a teammate's, isolated from yours\n```\n\nAdd the [hlock badge](https://docs.hlock.ai/project/badge/) to your README to point readers\nat the locks. See [Team repositories](https://docs.hlock.ai/guides/teams/) for the layout,\nthe conventions, and pulling a teammate's lock from outside the repository.\n\n**Optimize your harness.** Draft an eval pack from the requests you've already made to your\nagent with `hlock evals init --from-traces` (it reads the sessions Claude Code, Codex, and\nPi logged for the project), and review it with your agent using the Agent Skill it writes. List the models, decision models and harnesses to try in a\n`harness.toml`, and let `hlock resolve` lock the best combination with its success rate,\ncost, and latency. `hlock tune` goes further, into prompts, hyperparameters, and\nfine-tuned small models. The built-in `reference` provider is offline, so you can try the\nloop with no API keys:\n\n```\nhlock evals init                          # write a hello-world eval pack to ./evals\nhlock init --name demo                    # write a starter harness.toml\nhlock resolve                             # measure every combination -> harness.lock\nhlock run \"count the words in words.txt\"  # run the locked agent\n```\n\n**Switch harnesses, or go local.** `hlock migrate --to codex` moves a lock onto another\nharness, with your MCP servers, skills, and instructions rewritten to where it reads them.\n`hlock localize` does the same onto an open-source harness and models served by Ollama or\nLM Studio.\n\n**Let an agent do the busywork.** `hlock meta` hands work that needs judgment (installing\nwhat a lock needs on a new machine, filling in an eval pack, updating skills and MCP\nservers) to a pinned agent and checks the result itself. The default is an agent built\ninto hlock, so there's nothing to install: give it an API key or a local model.\n\n```\nhlock meta init                 # pick a model for the built-in agent, and pin it\nhlock meta run install          # install what harness.lock still needs, then verify\n```\n\nSee [Finding the best stack](https://docs.hlock.ai/guides/resolve/),\n[Eval packs](https://docs.hlock.ai/guides/eval-packs/),\n[Tuning](https://docs.hlock.ai/guides/tune/), and\n[Switching harnesses](https://docs.hlock.ai/guides/migrate/),\n[Going local](https://docs.hlock.ai/guides/localize/), and\n[The meta harness](https://docs.hlock.ai/guides/meta/).\n\n## **Python API**\n\n``` python\nimport json\nimport hlock\nfrom hlock import SearchSpace, Objective, Budget\n\nspace = SearchSpace(\n    llm={\"planner\": [\"reference:qwen-7b\", \"reference:qwen-32b\"]},\n    decision=[\"none\", \"rules:default\"],\n    harness=[\"reference\"],\n    objective=Objective(select=\"min-cost\", constraints={\"success-rate\": \">=0.5\"}),\n    budget=Budget(max_trials=50),\n    evals=json.dumps({\"packs\": [\"./evals\"], \"seeds\": 2}),\n)\nlock = hlock.resolve(space, backend=\"offline\")   # writes ./harness.lock\nprint(lock.summary())\n\nagent = hlock.load(\"harness.lock\")\nprint(agent.run(\"clean ./data/orders.csv\"))   # {\"success\": true, \"model\": \"qwen-7b\", ...}\n```\n\nA Rust core does all the deterministic work. Anything that needs the Python ML ecosystem or a GPU runs on a backend: hlock's Python worker on this machine, Flyte tasks on a cluster, or a backend you write in Rust or Python.\n\n| Path | What lives there | \n|---|---|\n| [`crates/harness-lock-core`](https://github.com/unionai-oss/hlock/tree/main/crates/harness-lock-core) | The core library (pure Rust): manifests, lockfiles, search planning, trial bookkeeping, evidence, lock construction. It orchestrates and aggregates, and never does heavy compute itself. | \n| [`crates/harness-lock-py`](https://github.com/unionai-oss/hlock/tree/main/crates/harness-lock-py) | PyO3 bindings, compiled into `hlock._hlock` and shipped only inside the wheel. | \n| [`crates/hlock`](https://github.com/unionai-oss/hlock/tree/main/crates/hlock) ,[`crates/harness-lock`](https://github.com/unionai-oss/hlock/tree/main/crates/harness-lock) | Thin crates that re-export the core ( `harness-lock` is the alias). | \n| [`hlock/`](https://github.com/unionai-oss/hlock/tree/main/hlock) | The Python package: the `hlock` CLI and the heavy-work worker ([`tasks/worker.py`](https://github.com/unionai-oss/hlock/blob/main/hlock/tasks/worker.py) ). | \n| [`harness_lock/`](https://github.com/unionai-oss/hlock/tree/main/harness_lock) | A shim that re-exports `hlock` , so`import harness_lock` works. | \n| [`packaging/harness-lock`](https://github.com/unionai-oss/hlock/tree/main/packaging/harness-lock) | The `harness-lock` PyPI alias, which pins the matching`hlock` release. | \n| [`docs/`](https://github.com/unionai-oss/hlock/tree/main/docs) | The documentation site ( [Zensical](https://zensical.org) ), published to GitHub Pages. | \n\n| Backend | Where trials run | Use it for | \n|---|---|---|\n| `offline`*(default)* | in-process Rust reference harness | trying it out, CI, deterministic tests | \n| `local` | Python worker on this machine | real LLM calls, your own traces, LoRA on a local GPU | \n| `flyte` | each work item as a Flyte 2 task on your cluster | GPUs, durable caching, shared results | \n| your own | wherever your backend sends it | Ray, Modal, Kubernetes, Slurm, an internal runner | \n\n```\nhlock tune --backend local --depth probe --max-trials 10\n# real LLM calls: export HL_LLM_BASE_URL=http://… HL_LLM_MODEL=qwen-32b [HL_LLM_API_KEY=…]\nhlock tune --backend flyte --depth ft --data user:./runs   # LoRA on a GPU worker\n```\n\nBackends are pluggable: a Python class registered in the `hlock.backends` entry point\ngroup, or any executable named `hlock-backend-<name>` (Rust has a `serve` helper). See\n[Backends](https://docs.hlock.ai/guides/backends/) for setup, the `HL_*` environment\nvariables, and how to write your own.\n\nhlock builds on, and borrows from, a lot of good work. Package managers install agent config, dotfile managers and Nix reproduce it, eval frameworks measure it, and optimizers generate it. hlock isn't trying to replace any of them; it has different devex goals:\n\n- **speed** : one command pins the setup you already have\n- **quick portability** : the whole stack, from harness version and models to MCP servers,\nskills and config, in one lock you can rehydrate anywhere\n- **tunability** : eval packs, the resolver and the tuner measure your stack against your own tasks\n- **let agents do the busy work** : some packaging and syncing work that users need to do around hlock\ncan be further automated with a meta agent.\n\n| If you want to… | Reach for | Where hlock fits | \n|---|---|---|\n| Install skills, instructions and MCP servers from git into many agents, with org policy | [APM](https://github.com/microsoft/apm) | hlock reads `apm.yml` , resolves`apm:` packages by the same rules, and exports`apm.lock.yaml` ; it also pins the rest of the stack and measures whether a package helps | \n| Keep one set of rules in sync across many agents | [rulesync](https://github.com/dyoshikawa/rulesync) ,[Ruler](https://github.com/intellectronica/ruler) | They translate config; hlock locks it, with digests and drift checks | \n| Add skills from the open ecosystem | [`npx skills`](https://github.com/vercel-labs/skills) | `hlock pin` records them with the rest of your setup | \n| Carry your dotfiles to every machine | [chezmoi](https://github.com/twpayne/chezmoi) ,[yadm](https://github.com/yadm-dev/yadm) | hlock knows what a harness's files mean: versions, models, secrets, drift | \n| Reproduce a toolchain bit for bit | [Nix](https://github.com/NixOS/nix) ,[mise](https://github.com/jdx/mise) ,[Dev Containers](https://containers.dev) | Nix pins inputs; a resolved `harness.lock` also records how well the stack did | \n| Run agent evals and benchmarks at scale | [Harbor](https://github.com/harbor-framework/harbor) ,[Inspect](https://inspect.aisi.org.uk) ,[promptfoo](https://github.com/promptfoo/promptfoo) | They measure the variants you list; hlock searches, selects, and locks the winner | \n| Write better prompts and programs | [DSPy](https://github.com/stanfordnlp/dspy) ,[GEPA](https://github.com/gepa-ai/gepa) | They generate candidates; hlock picks among stacks and makes the pick reproducible | \n\nThe [comparison page](https://docs.hlock.ai/concepts/related/) goes through each one,\nincluding \"why not just dotfiles / chezmoi / Nix / APM?\". Already using APM? See\n[Coming from APM](https://docs.hlock.ai/getting-started/apm/).\n\nDevelopment uses [uv](https://docs.astral.sh/uv/) and a Rust toolchain.\n\n```\nuv sync                            # create .venv, build the Rust extension, install dev tools\nuv run pytest                      # Python bindings, CLI, worker\nuv run ruff check harness_lock hlock tests\ncargo test -p harness-lock-core    # Rust core + integration tests\n\nuv run --group docs zensical serve # docs at http://localhost:8000\n```\n\n`uv run` rebuilds the extension automatically when Rust sources change.\n\nWant to help? See the [contributing guide](https://docs.hlock.ai/project/contributing/). Releases are cut from tags. See [RELEASING.md](https://github.com/unionai-oss/hlock/blob/main/RELEASING.md).\n\nWhat works today: `pin`, `check`, `sync`, and `launch` for the\n[supported harnesses](https://docs.hlock.ai/guides/harnesses/), declared dependencies\n(`add`, `remove`, `outdated`, APM packages and `apm.lock.yaml` export), audit and trust\n(hidden-Unicode scanning, executable approval, `hlock-policy.toml`, SARIF, CycloneDX and SPDX\nSBOMs), `localize`, manifest and\nlockfile schema v1, a content-addressed store, eval packs (`hlock evals`) with graders, the\nreference provider and harness, grid search with Pareto selection, `upgrade`\n(plan/apply/rollback), `tune` across the `offline`, `local`, and `flyte` backends and pluggable backends, and the\n`meta` harness. The [design specs](https://github.com/unionai-oss/hlock/tree/main/specs) describe the full design,\nmuch of which is still on the roadmap.", "url": "https://wpnews.pro/news/show-hn-hlock-an-agent-harness-lockfile-and-performance-resolver", "canonical_source": "https://github.com/unionai-oss/hlock", "published_at": "2026-10-21 14:58:06+00:00", "updated_at": "2026-10-21 15:13:42.390259+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "agent-protocols", "ai-products"], "entities": ["hlock", "Union AI", "Claude Code", "Codex", "Cursor", "Gemini CLI", "OpenCode", "Pi"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-hlock-an-agent-harness-lockfile-and-performance-resolver", "markdown": "https://wpnews.pro/news/show-hn-hlock-an-agent-harness-lockfile-and-performance-resolver.md", "text": "https://wpnews.pro/news/show-hn-hlock-an-agent-harness-lockfile-and-performance-resolver.txt", "jsonld": "https://wpnews.pro/news/show-hn-hlock-an-agent-harness-lockfile-and-performance-resolver.jsonld"}}