# HALO, a loop that reads an agent's own traces to fix the harness

> HALO is a methodology and a set of tools for building recursively self-improving agent harnesses, where execution traces are analysed for failure modes and the resulting report is handed to a coding agent to change the harness. The engine ships as a Python package with a CLI, and the desktop app is a separate download.

**context-labs/HALO** — Hierarchal Agent Loop Optimizer

- Repository: https://github.com/context-labs/HALO
- Stars: 1,194 · Forks: 101
- Language: TypeScript
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/context-labs-halo

## The loop is five steps and one of them is your coding agent

HALO stands for Hierarchal Agent Loop Optimizer, and the README describes it as a methodology for building recursively self-improving agent harnesses using RLMs. The loop itself is the part worth reading, because it is short.

First, collect execution traces from the agent harness, and HALO uses OpenTelemetry compatible tracing for that. Second, feed the traces into the HALO-RLM engine. Third, the engine decomposes the traces to understand common failure modes across harness executions, and produces a report with its findings. Fourth, that report goes into a coding agent such as Cursor or Claude Code, which generates and applies changes to the harness. Fifth, the harness is redeployed, more traces are gathered, and the cycle repeats.

So the unit of improvement is the harness, not the prompt. The thing being optimised is the code that wraps the model, and the feedback signal is what real executions did, not a score someone wrote down.

The README also states the conditions under which it works, and this is the honest part of the pitch. HALO is described as good at finding issues in production agent deployments, and the reason given is data volume: high-traffic environments tend to generate more data with higher variance across executions, which creates the kind of issues HALO is good at identifying. That is a constraint on the method rather than on the software. If you have twenty runs a day, the variance across them may not support the generalisation the loop depends on.

The repository holds several pieces. There is the HALO Desktop App for running HALO locally, information on the methodology, a Python package implementing the core HALO-RLM engine, a demo project showing how to build HALO loops for your agents with that package, and benchmarking examples that apply HALO to popular agent benchmarks, with AppWorld called out by name.

## Why a general coding agent is the wrong reader for traces

The README justifies the RLM choice directly. A general-purpose harness like Claude Code is the wrong tool for trace analysis, and the stated reason is not that the model is not smart enough. It is that traces can get extremely long and you need a specialized toolkit to make observations about systemic agentic behaviour.

The second half of the argument is about a failure mode that the team ran into. In their testing, harnesses like Claude Code would often overfit to an error present in a single trace or a few traces rather than generalise to harness-level problems. A report that names one particular tool call as the culprit is actionable in the wrong way, because the fix lands in the prompt for that call instead of in the loop that produces it.

That diagnosis shaped the design of the specialised RLM they built, and it is also the strongest argument for the whole approach. If your agent fails the same way across many runs because of how you retry, how you parse a tool result or how you slice a context window, then the fix is a code change and the evidence is in the traces. A general coding agent reading one trace will instead propose a one-off patch.

The dependency list backs up the claim that this is a runtime rather than a prompt. The engine package depends on the openai client and the openai-agents SDK, plus numpy and pandas for working over trace data, and on inference-catalyst-tracing, which the pyproject comments describe as mandatory because the engine always imports it for a span helper and for the optional hosted OTLP backend.

## The engine installs from PyPI and exposes a halo command

The Python engine and its CLI are on PyPI under the name halo-engine, and the install is a pip command followed by a sanity check:

```bash
pip install halo-engine

# Verify installation
halo --help
```

The console script is defined in the project metadata as halo = "halo_cli.main:app", and the CLI is built with typer and rich, so the interface follows the usual pattern of a Python command line tool with formatted terminal output.

The package requires Python 3.10 or newer, and the runtime dependencies are pinned exactly, including pydantic 2.13.3, openai 2.32.0, openai-agents 0.14.7, numpy 2.2.6, pandas 2.2.3, deno 2.7.14, typer 0.25.0, rich 15.0.0 and inference-catalyst-tracing 0.1.10. Exact pins across a set this size mean a dependency bump is a deliberate act rather than something a resolver does for you.

Two of those dependencies deserve an explanation, because the comments in pyproject.toml explain the packaging rather than the logic. The deno binary ships as a platform wheel so the WASM sandbox runs out of the box after a pip install, with wheels for macOS on x86_64 and arm64, Linux on x86_64 and aarch64, and Windows on x86_64; on unsupported platforms such as musl Linux, pip falls back to the source distribution and the sandbox looks for deno on PATH instead. The ripgrep dependency is marked as required for the code tools, since glob, grep and tree all run through it so that .gitignore is honoured, but wheels exist only for macOS arm64 and Linux x86_64, so the marker pins it to those platforms. Elsewhere it is not pulled at all, and the user needs a system rg on PATH, otherwise opening a repository fails fast with an install hint.

## The desktop app is a separate download, not the same thing as the package

There are two front doors, and the README keeps them apart. The desktop app is installed with a shell one-liner:

```bash
curl -fsSL https://inference.net/halo/install.sh | sh
```

The installer downloads the latest release for your platform and sets up the desktop app, and on macOS that release is a signed, notarized DMG. The GitHub releases page is the alternative route if you would rather not pipe a script into a shell. A full walkthrough of the desktop app lives in the HALO Desktop guide on the documentation site, covering the path from loading demo traces to running HALO and shipping fixes with a coding agent.

The commented-out screenshot table at the top of the README describes what the app does, which gives a picture of the workflow even in a text only reading. You can import agent traces from Langfuse, Arize, JSONL or a local agent, browse the imported trace history and understand the shape of a dataset, launch reports over trace groups and follow each analysis step, review trace timelines to spot latency, retries, expensive spans and branching behaviour, inspect full sessions with conversations, tool calls and model responses in context, read HALO reports with ranked failures, bottlenecks and concrete recommendations, and send a report to Claude, Cursor or Codex for implementation.

The repository layout matches that desktop app being a separate codebase from the engine. The top level carries an app/ directory, an engine/ directory, a halo_cli/ directory, a demo/ directory with the appworld and openai-agents-sdk-demo projects, a skills/ directory, tests/, docs/, and a Taskfile.yml. A pyrightconfig.json is present for type checking, and uv.lock is committed for the development environment.

There is also a hosted option. The README says that for a hosted, plug-and-play version of HALO, the route is to sign up for inference.net and follow the capture-first-trace instructions.

## What the documentation does not settle

Several things a reader would want are not documented in the README, and it is better to name them than to guess.

The first is licensing. The README carries an MIT badge, but the repository's licence field is not classified by GitHub. For a project that reads your traces and reports on your agent's behaviour, the terms matter, so read the licence file directly before you build on it.

The second is the exact shape of the engine. The usage section in the README is a three step list, integrate tracing using the OpenTelemetry agents SDK guide, collect traces by running your agent, and run the HALO engine, and the environment setup begins with an OPENAI_API_KEY export with the comment that you can point HALO at another OpenAI compatible provider, and the project metadata mentions a hosted OTLP backend selected by INFERENCE_API_KEY, with a local JSONL backend used when the token is unset.

The third is the benchmark story. The README says there are benchmarking examples applying HALO to popular agent benchmarks and points at AppWorld, and the demo/ directory contains an appworld/ project, but the numbers are not in the README. A method whose case rests on finding real failure modes deserves published figures before you commit engineering time to it.

The fourth is the maturity level. The desktop release tags are app-v0.1.17 from 2026-06-24, app-v0.1.16 from 2026-06-23 and app-v0.1.15 from 2026-06-22, all below 1.0, while the engine package is at version 0.3.5. The last push was on 2026-09-08, so the project is still being worked on, and a telemetry file named halo-telemetry-run-legacy.jsonl at the repository root suggests earlier experiments are being kept around for comparison.

## Conclusion

HALO suits teams running agents in production with enough traffic that failures repeat across executions, and it suits engineers who already have OpenTelemetry tracing and a coding agent in the loop, since the pipeline plugs into both rather than replacing them. It is the wrong choice for a prototype with a handful of runs, because the whole method depends on systemic failure patterns appearing across traces, and it is the wrong choice if you cannot ship a harness change, since a report that nobody applies produces nothing. Before adopting it, confirm you can emit OpenTelemetry compatible traces, check the deno and ripgrep platform situation, since the sandbox ships a deno wheel and ripgrep has wheels only for macOS arm64 and Linux x86_64, and read the licence file directly, because the repository metadata does not classify it while the README shows an MIT badge.

## FAQ

### What is HALO and what does the loop actually do?

HALO is a methodology for improving agent harnesses recursively. It collects OpenTelemetry compatible traces from the harness, feeds them to the HALO-RLM engine, which reports common failure modes, and hands that report to a coding agent such as Cursor or Claude Code to change the harness before the cycle repeats.

### How do I install the HALO engine?

The Python engine and CLI are published on PyPI as halo-engine, so pip install halo-engine is enough, and halo --help verifies the installation. The package requires Python 3.10 or newer and exposes a console script named halo.

### How do I install the HALO desktop app?

The README gives curl -fsSL https://inference.net/halo/install.sh | sh, which downloads the latest release for your platform, with a signed and notarized DMG on macOS. You can also install from the GitHub releases page, or use the hosted version offered through inference.net.

### Why not just use a general coding agent to analyse the traces?

The README says general harnesses like Claude Code would often overfit to an error present in a single or a few traces rather than generalise to harness-level problems, and that traces can get extremely long. A specialised RLM was built to make observations about systemic agentic behaviour across executions.

### What extra system tools does the HALO engine need?

The engine ships a deno wheel so the WASM sandbox runs after installation, and ripgrep is required by the code tools so that .gitignore is honoured. ripgrep has wheels only for macOS arm64 and Linux x86_64, so on other platforms you need a system rg on PATH, otherwise opening a repository fails fast with an install hint.

## Sources

- [context-labs/HALO on GitHub](https://github.com/context-labs/HALO)
- [Issues](https://github.com/context-labs/HALO/issues)
- [README](https://github.com/context-labs/HALO/blob/main/README.md)
- [Releases](https://github.com/context-labs/HALO/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/context-labs-halo