HLock introduces a package-manager-style lockfile for AI coding agents. Its generated harness.lock records the harness version, model selections, MCP servers, skills, plugins, instruction files and configuration, so developers can commit an agent setup alongside the code it works on. The project names Anthropic’s Claude Code, Codex, Pi, OpenCode and OpenClaw among its supported harnesses. HLock documentation
The operational problem is straightforward: sharing a repository does not mean sharing an agent environment. Two contributors can use the same application code while giving their agents different instructions, tools, permissions and models. HLock makes those surrounding dependencies visible and versionable.
October 29, 2026 is the observation date associated with this update, not a confirmed release date. HLock’s documentation does not specify a launch date. This article analyzes those documents; cross-harness fidelity and security properties have not been independently benchmarked here.
What harness.lock Actually Records
HLock separates the agent’s setup into components that can be captured, checked and restored. The lockfile is generated TOML, intended for version control rather than manual editing. Its reference example uses schema version 1 and identifies its generator as harness-lock 0.2.0; that is an example version, not evidence of the latest release. Lockfile reference
| Component | What the documentation records | Why it matters |
|---|---|---|
| Harness | Name, installed version, installation source where available, configuration digest | A harness update can change behavior even when the model stays the same |
| Models | Role, provider, model identifier, parameters and fingerprints where recorded | Different agent roles can use different models |
| MCP servers | Source, transport, command, arguments, environment variables or remote URL | Tool availability and connections become reviewable |
| Skills, plugins and instructions | Component sources or digests, scope and vendored files as applicable | Local customizations can travel with the setup |
| Configuration | File format, digest, restore method and captured content | Restoration can cover a whole file or selected settings |
The reference example illustrates selective restoration. One configuration entry restores an entire settings.json; another restores only the /mcpServers portion of ~/.claude.json. That distinction is useful because sharing an MCP configuration should not necessarily mean replacing unrelated application state.
Files another machine cannot download are copied into .hlock/vendor/. A team sharing a lock therefore needs to include its referenced vendored material, not assume the lockfile alone contains every required byte. How HLock works
A Recorded Dependency Is Not Always Immutable
The published example reveals an important limit to the package-lock analogy. Its Claude model is recorded as opus, while a GitHub MCP server is launched through npx using a package name without an explicit version. A second MCP server is represented by an HTTP endpoint. Skills and instruction files, meanwhile, have SHA-256 digests and vendored paths. Lockfile reference
Those entries offer different strengths of reproducibility. A digest can identify captured file content. A model alias or remote endpoint identifies a service selection, but the example does not demonstrate that the service’s underlying implementation is frozen.
My view is that this is the first detail teams should inspect. HLock can make configuration drift reviewable, but a recorded service name should not be treated as an immutable artifact. Identical configuration also cannot, by itself, guarantee identical generated answers.
Capture a Setup, Then Restore or Launch It
hlock pin captures an existing environment without requiring a manifest or evaluation tasks. It reads the harness through its profile and records the relevant components. Adding --user includes user-level material from locations such as ~/.claude or ~/.pi/agent, alongside project-level configuration. How HLock works
A documented starting sequence is:
pip install hlock
hlock pin --user
hlock check
hlock launch
These commands install the CLI, capture the current setup including user scope, check it for changes and launch the locked harness. They are an example workflow, not commands executed for this article. Installation and workflows Pinning behavior
The restoration commands serve different purposes:
hlock syncreconstructs the setup on a machine, in a directory or in a Docker image.hlock launchstarts the harness in an isolated environment built from the lock, excluding unrelated local configuration.hlock runruns a prompt through the locked stack.
For teams, HLock also documents separate locks under .hlock/locks/, such as harness.alice.lock. Another contributor can launch that setup with hlock launch --lock and its path. Team workflow
That layout makes a useful practical distinction: a repository can preserve several deliberate agent setups without pretending everyone uses one universal configuration. I’d start by capturing an existing setup before attempting model optimization. A stable baseline makes later changes easier to explain.
Secret Placeholders Keep Credentials Separate
HLock documents replacing API keys and tokens with HLOCK_SECRET_* placeholders. Users supply the actual values when syncing. The lockfile reference shows this pattern for a GitHub MCP server:
[tool.env]
GITHUB_TOKEN = "${HLOCK_SECRET_GITHUB_GITHUB_TOKEN}"
The reference also records a secret entry identifying which component uses that placeholder. This preserves the connection between a credential and its consumer without putting the credential value in that field. Lockfile reference
A teammate therefore receives a configuration that says which credential is needed, while supplying their own value separately. The placeholder is not an encrypted credential or a secret-distribution system.
I would still review the lock and vendored files before committing them. The documented substitution mechanism is useful, but arbitrary instruction files and configuration deserve inspection too. Likewise, launching an isolated configuration should not be mistaken for a security sandbox: the schema has explicit sandbox policy fields, and those settings can be empty. Lockfile policy fields
Pinning and Resolving Answer Different Questions
hlock pin answers “What is installed here?” The separate hlock resolve workflow answers “Which permitted setup performs best on these tasks?”
Resolution starts with a handwritten harness.toml. It declares candidate models and harnesses, evaluation packs, objectives, constraints, budget and execution backend. HLock expands the candidates into concrete stacks, runs them against the evaluation tasks and records success, cost and latency. Resolver documentation
The documented selection process has three stages:
- Apply constraints, such as a minimum task-success rate.
- Remove dominated options, where another stack performs better on both success rate and cost.
- Apply the selection rule, such as
min-costormax-quality.
If no stack satisfies the constraints, resolution fails instead of locking an unsuitable candidate. Trial-count and dollar-spend budgets limit the search, with trials allocated round-robin across candidates.
A resolved lock can retain evaluation-pack identity and digest, trial counts, success rates, cost in US dollars per task, and latency in seconds per task. These are fields for evidence produced by a configured evaluation, not independent benchmark results demonstrating that HLock improves coding performance.
Frequently Asked Questions
3 questions
1Do I Need harness.toml to Start?
No. hlock pin captures an existing setup without a manifest or evaluation tasks. harness.toml is used when declaring candidates and objectives for resolution.
