hzr

HZR

HZR — heAdz0r's Zero-Redundancy engine — turns RTK fork-core, grepai, ICM, Caveman-derived response density, policy, and observability into one coherent system. It is local-first, project-scoped, and designed to reduce repeated work without hiding what was filtered, estimated, or left unmeasured.

The product is not “another wrapper around tools.” HZR is the ownership boundary that prevents those tools from building competing indexes, memories, caches, and accounting.

The shift

Most agent stacks optimize isolated steps. Each layer scans the same repository, stores its own context, compresses output again, and reports a different idea of savings. The result may look efficient while consuming more work and losing observability.

HZR assigns one owner to each concern:

Before	With HZR	What you get
independent command wrappers	one policy-aware execution route	bounded output and explicit exact recovery
duplicate semantic stores	one grepai index per worktree	no competing scans or watchers
per-client memory processes	one supervised ICM store	durable context without orphan processes
disconnected counters	one typed operation ledger	actual usage kept separate from estimates
opaque background failures	doctor + lifecycle + local observatory	degraded state is visible and actionable

Architecture

flowchart TB
    CC["Claude Code<br/>hook · MCP stdio"]
    CX["Codex · IDE · other agents"]
    CLI["hzr CLI"]

    CC --> D
    CX --> D
    CLI --> D

    D{{"HZRD — control plane<br/>policy · workspace identity · supervision · accounting"}}

    D <--> X["RTK fork-core<br/>exec router + output filters"]
    D <--> S["grepai<br/>semantic index + symbols"]
    D <--> M["ICM<br/>durable memory"]
    D <--> C["Caveman-derived<br/>response density"]

    D ==> L[("Typed operation ledger")]
    L --> O["Doctor · Stats · Session ROI · Observatory"]
    P["Versioned public pricing<br/>opt-in · overridable"] -. "preliminary estimate" .-> O
    O -. "repair · policy feedback" .-> D

    style D fill:#e64a19,stroke:#7f2704,stroke-width:3px,color:#ffffff

This architecture gives HZR three properties that a loose tool collection cannot:

1. A single decision point. Agent shell work enters through hzr exec run; known routes are filtered, unsupported paths are tracked, and ambiguous bypasses fail closed.
2. A single project identity. Search, memory, traces, and UI selection use the same repository/worktree boundary. One project cannot become another project's fallback.
3. A single operational truth. Engine health, exclusions, estimates, fidelity requests, and incomplete accounting remain visible instead of becoming false savings.

HZR does not invoke every engine on every turn. It selects the smallest sufficient path, deduplicates evidence by identity, and supervises long-lived components centrally.

Evidence, not slogans

The 2026-09-25 benchmark reruns the cases an external evaluation measured on a Go repository, against RAW commands, HZR 0.9.13, HZR 0.10.0 and upstream RTK v0.50.0. Each output is also capped at the 30,000 characters Claude Code shows the model, because savings above that window never reach the context.

16 cases, host-visible bytes	RAW	HZR 0.9.13	HZR 0.10.0	RTK v0.50.0
total	139,256	108,006	86,748	104,644
go test with a compile failure	250	3,451	318	275
git diff HEAD~5	30,000	30,000	21,187	30,000
find crates -name '*.rs'	6,046	6,139	965	847
grep -rn (lossless)	10,355	10,355	8,264	10,355

HZR 0.10.0 delivers 38% less than RAW and 17% less than upstream RTK v0.50.0 on that set, without dropping content silently: every bounded or truncated output names its exact recovery command. git status is deliberately larger than in 0.9.13, which hid files. Methodology, all cases and a reproduction script: benchmarks/hzr-vs-rtk-upstream-v0.50.0.

The earlier 2026-08-01 run against RTK v0.44.1 reported −23.6% versus upstream, but its largest win (read README.md, −95.6%) compared a Markdown outline with the full file — a different fidelity, not the same content in fewer bytes (recorded run).

These values use ceil(UTF-8 bytes / 4). They measure delivered command-output size, not provider billing or total-session savings. In a session dominated by exact file reads (sed -n, cat), which no filter can shrink without loss, the effect on billed input is small; HZR's per-turn instruction overhead is 1.6 KB.

Install

HZR 0.11.5 ships self-contained native bundles for Linux x86_64/ARM64 and macOS Apple Silicon. Intel macOS is no longer supported. System Git is the only engine prerequisite; Node.js, RTK, grepai, and ICM are bundled. Windows is not currently published.

Download, inspect, then run the installer:

curl --proto '=https' --tlsv1.2 -fL \
  https://raw.githubusercontent.com/heAdz0r/hzr/v0.11.5/install.sh \
  -o /tmp/hzr-install.sh
sh /tmp/hzr-install.sh

The installer verifies the release checksum and internal manifest, installs into a versioned root, atomically switches current, initializes the workspace, and configures the single user service. To separate file installation from agent adoption:

HZR_INSTALL_HOOKS=0 sh /tmp/hzr-install.sh
hzr install --dry-run
hzr install --force

Useful controls include HZR_INSTALL_ROOT, HZR_BIN_DIR, HZR_INSTALL_HOOKS=0, HZR_INSTALL_SERVICE=0, HZR_PROJECT_ONLY=1, HZR_FORCE=1, and HZR_VERSION.

One bundle contains pinned HZR, RTK fork-core, grepai, ICM, caveman-code, Node.js, and the Vue operator UI. Exact commits, archive checksums, patch digests, and npm integrity values live in engines.lock.toml.

First minute

Inside a repository:

hzr doctor --workspace .
hzr init --if-needed --workspace .
hzr daemon status
hzr search "where is command policy" --workspace .
hzr context plan "change command policy" --workspace .
hzr stats --workspace .

Open the local observatory at http://127.0.0.1:47391/. It shows the selected project's engine lifecycle, grepai readiness, anonymous memory topology, command routes, exclusions, latency, traces, and accounting posture. Public loopback views are bounded and pseudonymized; authenticated detail remains project-scoped.

Daily control plane

hzr read README.md --outline
hzr read README.md --from 120 --to 180
hzr search "authorization boundary" --mode auto
hzr context plan "change authorization boundary"
hzr write patch app.rs --old @/tmp/old.txt --new @/tmp/new.txt --cas
hzr memory recall "release decision"
hzr exec run 'cargo test 2>&1 | tail -80'
hzr stats --evasion --since 7d

Bounded reads retain exact-range recovery; writes are atomic and confined. hzr build is an inherited fork-core command, so build projects through hzr exec run '<project build command>'.

Observe an agtx board without operating it

HZR can watch an existing agtx board — its tasks, their dependency graph, the transitions HZR sees while it is watching, which sessions belong to which task, and what that work reportedly cost. Monitoring creates no task, starts no agent, advances no phase and answers no permission prompt on agtx's behalf.

The pinned agtx runtime and read-only observer ship together in HZR. No Rust toolchain or separate agtx installation is needed. Monitoring remains opt-in and is one command; onboard verifies the bundled observer itself, then enrolls the project:

hzr agents onboard --project /absolute/worktree --agtx-data-dir /absolute/agtx/data
# New board only: open the bundled app once, then run `onboard` again.
hzr agents board --project /absolute/worktree --agtx-data-dir /absolute/agtx/data
hzr agents status --json

The visualizer gains an Agents workspace — board, dependency graph, observed timeline and task economics — fed by the same daemon and privacy projections as every other view. Reported usage, reported cost and catalog-priced estimates stay separate; nothing is summed into a fake total, and an unobserved value renders as an em dash with a reason rather than a zero. Ownership, protocol, safety and limits are documented in integrations/agtx/README.md; the pinned commit, patch digests and the confirmed Apache-2.0 licensing provenance are recorded in integrations/agtx/PROVENANCE.json.

Things are named, not numbered. The dashboard shows each workspace by its own directory (hzr, with ~/Programming/hzr beside it), each ICM topic by its topic name, each memory by what it says, and each observed agtx task by its title — with the pseudonymous identity kept beside the name as the stable handle. That is the default because a list of a hundred Project 6a1be071 rows cannot be used to find anything. An install whose loopback port other people can reach turns it off and gets the pseudonymous view back:

[privacy]
publish_workspace_names = false
publish_memory_content = false
publish_command_summaries = false # 0.9.1: hide `cargo test --locked`-style command summaries

[integrations.agtx]
publish_task_titles = false

Session ROI where the agent can see it

HZR does not wait for someone to open a dashboard. At the end of a session it turns the same accounting model behind hzr stats into a compact ROI card:

HZR session ROI
Saved (estimated net): 8000 tokens (66.7%; gross 8000, regression 0; 12000 -> 4000)
Measured commands: 7 | Top: hzr read <arguments omitted> x5
Policy: prevented 5 (1 native denial); asked 0; avoidable leakage 0 ops / 0 tokens
Evidence: prevented output not estimated | top evasion e10-capability-gap | hook events 464
Shadow guard: T3 observe-only | limit 40 ops / 250000 tokens

The first line is the measured local reduction from commands that actually ran. The policy line is different evidence: a prevented bypass has no output to count, so HZR celebrates the catch without inventing savings. Zero leakage therefore reads as the good result it is; an unavailable ledger reads unknown, never a reassuring fake zero. Top commands are privacy-safe families, not paths, queries, or arguments.

The same session boundary can now translate potentially avoided model-input tokens into a preliminary public-list price estimate. It is opt-in, labels the exact catalog identity and pricing method, and is never presented as a provider invoice:

[billing]
public_estimate_enabled = true
harness = "codex"
provider = "openai"
model = "gpt-5.6-terra"
method = "standard_short_context_lte_272k"
request_input_tokens = 100000
pricing_basis = "input"
# pricing_file = "/absolute/path/to/private-pricing.json"

Run hzr billing catalog before selecting a model. The built-in, versioned catalog covers current public API prices from OpenAI, Anthropic, Google, DeepSeek, Qwen, Mistral, and xAI. request_input_tokens is the actual priced request/session input, not the model's maximum context capacity; tiered prices fail closed when that evidence is absent or outside the method. Set pricing_file to an absolute JSON path to merge strict overrides by exact pricing key. HZR fails closed on an unknown model, method, currency, or expired price; it performs no FX conversion. Receipt imports remain a separate evidence class and are labelled user-supplied unless a trusted adapter verifies their provenance. Public prices never turn an estimate into a provider bill.

Make the efficient path the easy path

Having a good filter is not enough if an agent can reach a familiar RAW command faster. HZR 0.6 closes that incentive gap: the normal route needs less judgment than the bypass.

effective managed route exists  → use it; RAW is forbidden
no equivalent route exists      → tracked fallback; no invented savings
exact bytes are truly required  → explicit reason + bounded fidelity allowance
native bypass is still observed → E10 finding + zero credit + named replacement

hzr exec run accepts the original shell string and chooses the first-class implementation. It looks through common shell and environment wrappers, so wrapping rg, git, curl, or another managed command does not turn it into an invisible escape hatch. If hzr exec rewrite proves an allow_rewrite decision, an unfiltered route cannot override it.

This is more than a warning in a prompt. Avoidable bypass is recorded outside the optimized bucket, contributes zero reduction, lowers visible coverage, and returns the HZR command that should replace it. A genuinely unsupported operation remains available and auditable instead of being falsely called optimized.

Exactness is a controlled capability

Bounded output must identify what it represents, what was omitted, and how to recover authoritative evidence. Exact ranges and structured recovery stay first-class. Fully unfiltered execution requires an explicit fidelity marker and one closed reason:

HZR_RAW_FIDELITY=1 \
HZR_RAW_FIDELITY_REASON=machine_protocol \
hzr exec run '<command>'

Allowed reasons are binary, checksum, machine_protocol, complete_log, full_patch, and verbatim_source. Requests are budgeted before execution; uncertain post-execution state stays visible for operator reconciliation. RAW receives zero savings credit. If a managed equivalent exists, the direct bypass remains forbidden.

One workspace, one index, one memory plane

HZR derives identity from the Git common directory and worktree, or from the canonical path before git init. It owns one grepai store per worktree, one centrally supervised ICM database, and one typed ledger with positive project/global namespace checks.

Legacy and foreign stores are diagnosed, never silently adopted. doctor is read-only by default; doctor --fix only applies bounded, unambiguous repair paths with backups and CAS. Fleet reconciliation can migrate one unambiguous root store transactionally. Ambiguous nested duplicates require an explicit hzr migrate archive-index --dry-run, followed by --force after reviewing the source, hash manifest, and retained backup. If a source is recreated at the same path, HZR reports an explicit conflict and makes no mutation; an old manifest cannot hide it.

Use hzr install --project-only --dry-run when global activation is undesirable; explicit hzr enable and hzr disable keep that scope visible.

Semantic search needs a local embedding provider. The index is configured for Ollama at http://localhost:11434 with nomic-embed-text (ollama pull nomic-embed-text); Ollama is not bundled. Without it every search still works through the lexical ripgrep fallback, and each result names the backend that produced it (ForkRgaiGrepai or ForkRgaiRipgrep). hzr doctor probes the provider and reports embedding_provider as a warning when semantic search is unavailable. Memory recall uses ICM's FTS5 lexical retrieval; embeddings for memory are disabled in this release.

MCP without a second control plane

Clients without hooks launch the stateless stdio gateway:

hzr init                                                # exact Codex project pin
hzr mcp config --client claude-code --workspace "$PWD" # worktree .mcp.json
hzr mcp config --client claude-desktop --workspace "$PWD" --apply
hzr mcp status

Codex and Claude Code support exact project scopes. For linked Claude Code worktrees, use the generated .mcp.json/-s project registration; HZR never retargets shared local state. Claude Desktop is different: it has one selected workspace. In every other project doctor reports unavailable_for_this_workspace with a retarget-or-CLI action instead of pretending one global pin can serve the whole fleet. Every mismatched MCP session still fails closed.

The user-level Codex entry is only a dynamic fallback; every initialized repository keeps its exact pin in .codex/config.toml. A global install preserves an existing valid Claude Desktop selection instead of silently retargeting it. Change that singleton deliberately with hzr mcp config --client claude-desktop --workspace "$PWD" --apply, then reconnect the client.

The gateway exposes 13 schema-validated tools for context, search, confined read/write, memory lifecycle, managed execution, observability, doctor, and codec operations. It owns no database and starts no internal engine; every project-scoped operation goes through the same hzrd boundary. The executable contract is contracts/agent-capabilities.json.

Capability	MCP tools
context and code	hzr_context_plan, hzr_search, hzr_read
confined mutation and execution	hzr_write, hzr_exec
durable memory	hzr_memory_recall, hzr_memory_get, hzr_memory_store, hzr_memory_update, hzr_memory_forget, hzr_memory_prune
operations	hzr_observability, hzr_doctor, hzr_codec

hzr_codec distinguishes four coverage states: applied, shadow_measured, instructed, and unavailable. A transformed tool/CLI payload is observable and may receive estimated token credit. Claude and Codex cannot let HZR replace every final assistant response, so managed instructions and SessionStart ask for concise generation instead of a post-hoc transform: sending finished prose back through the codec cannot refund tokens already emitted. hzr_codec stays an explicit-request and shadow evaluation tool, and global-response coverage receives zero credit until a trusted host confirms replacement. Provider-billed $ is never inferred from it.

Claude Bash hooks rewrite commands only when an allow rule for the original command is confirmed or the host explicitly reports bypassPermissions. Otherwise, including Auto mode without a confirmed allow rule, HZR leaves the command unchanged for Claude to evaluate. Such calls are unfiltered and receive no savings credit. No broad shell-wrapper allowlist is needed; explicit ask and deny decisions remain enforced.

Keeping a fleet of projects current

Every registered workspace carries a managed contract block. When the contract moves, those blocks go stale, and a report that can only name 158 stale files across 79 projects is a chore, not a fix. One command repairs them:

hzr doctor --reconcile-fleet --dry-run   # exact files first
hzr doctor --reconcile-fleet
hzr doctor --reconcile-fleet --fix       # also stop orphaned engines, prune deleted worktrees,
                                         # clear failed index watchers

Since 0.8.3 the first session on a new HZR version schedules this pass once, detached from the SessionStart hook, and hzr update runs it in the foreground. runtime/reference-state.json and the reference_state doctor check report whether it completed, is still running, or ended with findings. Registrations whose worktree directory was deleted are pruned; a root whose parent directory is also absent is retained in case the volume is unmounted.

It refreshes stale blocks and creates missing managed Claude/Codex instruction surfaces and Codex project MCP pins for already registered workspaces. Claude Code .mcp.json remains an explicit project registration. HZR does not register arbitrary directories. Canonical-root and symlink-confinement checks keep every write inside its intended workspace, while user-authored directives outside the block are preserved and reported. Run it from an installed HZR: a binary started inside a source checkout would hand every other project a contract path only that checkout has, so the command refuses instead.

Doctor also validates the runtime path, not just the presence of index files. A typed semantic readiness probe catches an incompatible grepai configuration, supervised ICM failures stay visible, and a stale cache cannot masquerade as a healthy search plane. Completed global install journals become global facts only after their schema, exact terminal stage receipts, and state validate; incomplete recovery remains bound to its owning workspace. The same auditable waiver rules apply to both current-workspace and fleet checks.

SessionStart uses the same audit for the current project and user-global Claude/Codex surfaces. If it repairs drift or finds a conflict it cannot safely rewrite, the agent receives an immediate alert to run hzr doctor before continuing. A fleet cannot depend on someone remembering to open doctor after the instructions have already diverged.

When a project genuinely cannot route through HZR

Some repositories have to name an engine directly: a benchmark whose measured subject is RTK, or the engine's own source tree. Rewriting those instructions would destroy the thing they measure. Such a project declares a waiver instead of being quietly skipped:

# .hzr/policy.toml
schema_version = 1

[[exemption]]
rule = "direct-rtk"
reason = "benchmark-subject"
justification = "This checkout is the upstream RTK baseline that HZR measures itself against."

A waiver covers only the named instruction rule, requires an auditable justification, and is reported under fleet_instruction_exemptions. It never waives the managed block or execution policy: no repository file can buy an exception to a bypass HZR could replace at runtime.

Honest boundaries

Guarantee	0.11.5 posture
one versioned control plane and pinned engine bundle	implemented
one canonical index owner per worktree	implemented
actual provider usage separated from preliminary public-list estimates	implemented
fidelity bypasses receive zero savings credit	implemented
commands, paths, queries, and raw identifiers excluded from public telemetry	implemented
provider-verified invoice attribution	not inferred from public prices
Windows release artifact	not available

HZR never upgrades an estimate into a billing claim. A daemon-free fallback can preserve command policy but cannot invent a missing ledger receipt; doctor and stats report the accounting gap. Generic semantic equivalence is not inferred merely because output became smaller.

Since 0.6.5 those completeness contracts are executable rather than editorial. Every filtered route declares what it may never drop — exit status, failure lines, warnings, changed files — and fork-core/rtk/tests/must_keep_contract.rs proves it by running the real filters against output carrying each class. Exact recovery remains available when a proof is absent.

The delivered-byte benchmark above measures output size, not what a provider bills. The paired billed-input benchmark tests the strongest objection to it — that a mid-turn filter invalidates a cached request prefix, so billed input can rise while delivered bytes fall. That harness ships in 0.6.5 and has not been run; it refuses to report a figure without paired provider receipts.

Built from practical RTK experience

HZR is built by heAdz0r, an RTK contributor who has worked directly with the filtering techniques this system extends. The fork is not a reduced reimplementation: HZR preserves the complete imported engine, its provenance, and a deterministic parity contract while evolving it behind a broader architecture.

The immutable v0.1.0 baseline records the original RTK worktree. Current fork development lives in fork-core/rtk; provenance and regression rules are documented in FORK_PARITY.md.

Frontier planning with Flash workers

Keep your chosen Codex or Claude model as planner and reviewer, and send bounded routine tasks to a cheaper worker through the same HZR tools:

hzr settings login --provider opencode-go
hzr settings delegation --provider opencode-go --model deepseek-v4.1-flash --enabled true
hzr delegate --file task.md

Delegation is off by default. Each user supplies their own protected key; settings contain no credentials. The worker ends every run with a report (status, changed paths, verification commands with exit codes, risks) and one summary line with its tokens; its turn quota is extended while it makes progress, and a run without a report exits 2 with a report HZR writes from what the worker actually did.

Delegation sends repository content to the selected provider. The worker's system prompt carries the repository's AGENTS.md and CLAUDE.md, the pre-fetched context plan, and every hzr_read, hzr_search and hzr_exec result the worker requests travels to that provider's API (opencode.ai, openrouter.ai or api.deepseek.com). Enable it only for repositories whose content may leave the machine under that provider's terms. The allowed-file list is an instruction to the worker, not a filesystem sandbox. OpenRouter and direct DeepSeek are also available, with an explicit model, turn limit and timeout. Disable with hzr settings delegation --enabled false. The parent model is unchanged.

Workers run under the repository's own AGENTS.md and CLAUDE.md. Rules larger than the 24 KiB preload budget are preloaded head-first and read on demand, so delegation works in every repository rather than only in small ones. hzr doctor reports both the worker credential and that split.

The visualizer's Delegation tab shows real worker activity, exact provider/model, and observed token usage. Open its local URL with ?view=delegation inside Codex. Worker completion still requires parent review; no unmeasured savings are claimed.

See configuration and permission boundaries. The upstream orchestration pattern is adapted to HZR's bundled runtime. No external Router, Python, npm or additional runtime download is required. These workers appear in HZR's panel inside Codex, not in Codex's native subagent tree.

Build and contribute

Source builds require Rust 1.85+, Go, Git, Bash, curl, and standard Unix tools:

scripts/build-bundle.sh "$PWD/dist"
scripts/package-release.sh "$PWD/dist" "$PWD/dist-release"

See CONTRIBUTING.md, RELEASE_NOTES.md, CHANGELOG.md, SECURITY.md, and the immutable release archive.

The HZR control plane is Apache-2.0. Fork-core and bundled engines retain their own licenses and provenance; see NOTICE and THIRD_PARTY_NOTICES.md.