OPEN SOURCE DEEP DIVE
HelixHarness: Bringing Team Engineering DNA into Coding Agents
An Apache-2.0 harness for Codex and Claude Code that keeps requirements, verification evidence, and reusable engineering knowledge in the repository, with an optional evidence-driven platform for framework evaluation.
HelixHarness is an open-source harness for coding agents from Didi’s financial technology team. Rather than trying to build another general coding model, it turns a team’s business rules, architectural boundaries, verification practices, and hard-won project lessons into context that an agent can load when a task actually needs it. A reversible development lifecycle then constrains requirements, implementation, review, and archive. The current source labels both HelixHarness and helixharness-platform as version 1.0.0 and uses Apache-2.0; this review is based on commit 8b23069fb464104ce556798ec69737f7eba469b3.
The most important product decision is the separation between the everyday plugin and the maintainer platform. The plugin installs into Codex or Claude Code and serves application development. The optional helixharness-platform is for people who change the harness itself: it connects usage observations, frozen version evaluation, and evidence-backed candidate improvements. Development does not depend on the platform being online, and the platform is not presented as a generic grading service for business code.
A resumable lifecycle, not a prompt bundle
HelixHarness exposes nine public commands: init, propose, apply, archive, bug-fix, ut, update, status, and config. The central path is Propose, Apply, Archive. Propose establishes scope and acceptance before producing a spec and tasks. Apply implements the work with tests and two-axis review. Archive checks completion evidence and records the stable lessons that the user confirms.
Completion is grounded in repository artifacts and verification results, not in an agent saying that it is done. Specs, tasks, verification reports, and archive outcomes remain in the project, making the process inspectable and resumable after an interruption. propose --loop can continue through all three stages, but it still stops for requirement decisions, acceptance boundaries, or real blockers. The loop deliberately excludes publishing and deployment.
Single-repository work and multi-repository Workspace work share the same business contract. A Workspace keeps a root registry of repository responsibilities and dependencies while each participating repository retains its own spec, implementation, tests, and evidence. The root coordinates a cross-service feature without replacing repository-specific artifacts with one opaque mega-task.
Four kinds of project context
HelixHarness separates project context into Harness, Knowledge, Specs, and Hooks. Harness answers which engineering constraints and architectural boundaries the agent must respect and lives in docs/harness/. Knowledge explains how the system works and which business rules and past decisions matter in docs/knowledge/. Specs define what is being built and what evidence proves completion in docs/specs/. Hooks connect host checks, workflow gates, and review checklists to key stages.
The separation gives each context type a different lifetime. Stable project knowledge can accumulate after Archive, while a task contract ends with its feature and execution checks evolve with the host and project configuration. Instead of placing everything in one giant prompt, each context tree has a root index.md with three columns: file or directory, purpose, and loading trigger. The agent reads the index first and then loads only the leaves relevant to the current requirement, task, or archive step.
The protocol also enforces a useful boundary: a file that is not indexed is not part of the standard read set. An agent cannot guess a path and bypass the index. That reduces the chance of loading an obsolete document by accident, and it requires maintainers to turn durable project knowledge into navigable assets with explicit loading conditions.
Shared workflow core, host-specific adapters
HelixHarness currently supports Codex and Claude Code at the Stable level. The shared core owns workflow order, feature state, checkpoints, artifact contracts, review gates, and finish conditions. Each Host Kit owns command projection, native tool mapping, subagent dispatch, project settings, hook lifecycle, telemetry, updates, and installation. Codex receives a Skill projection; Claude Code uses native commands. Both still point to the same public command contracts and the same stage text.
Host API 1.1 exists to keep platform differences out of business logic. A Host Kit must state whether a capability is native, emulated, or unsupported. If there is no safe fallback, the operation must fail closed rather than silently borrowing another host’s paths or resources. Adding a new agent requires a separate architecture change with manifests, installers, runtime adapters, tests, and real-client acceptance; shared workflow code must not acquire platform-name branches.
The same discipline appears in hook distribution. Codex and Claude Code explicitly select their own hook manifests. A shared lifecycle service consumes an explicit HostManifest and canonical events; it does not infer the host from environment variables or cache directories. A stopped session is not treated as proof that a business stage completed. Start and finish are recorded explicitly.
The optional observability, evaluation, and evolution platform
helixharness-platform is an optional FastAPI, Jinja2, and HTMX service for framework maintainers. Its combined Web UI connects three modules that do not import one another or query one another’s databases. Bench manages calibrated Cases and isolated execution. Eval connects frozen versions, acceptance tests, and review outcomes. Evolution proposes candidates from eligible evidence. The platform is not required to run the plugin.
The evaluation target is a HelixHarness framework version or candidate, not the quality of an application’s generated code. Base and candidate versions are frozen by explicit Git references and exercised against the same published, calibrated Cases. Separate Workers, deterministic checks, and a model Judge produce evidence. Candidates are reviewed before evaluation, and the platform does not publish them automatically.
The repository is unusually explicit about evidence boundaries. The built-in Demo uses synthetic Cases, Mock Runs, and a project ledger, with visible Demo labels. Its numbers must not be read as model performance or as proof that a framework change helped. Real evaluation requires a configured model service and credentials, accessible repositories, and calibrated Cases. Telemetry is off by default, and both reporting and feedback have no default endpoint; configuring an address still does not authorize sending feedback content.
Who it serves, and what it does not claim
HelixHarness is aimed at teams that want their engineering habits, business knowledge, and review gates to travel with a coding agent, especially when work spans multiple services or needs durable evidence. It is a runtime skeleton that can be inspected and extended, not a promise that configuration will autonomously finish all software engineering.
The current boundaries matter. Only Codex and Claude Code are formally supported. More agent hosts and configurable workflow stages remain roadmap items. Real evaluation depends on external model infrastructure and calibrated Cases. People still confirm durable knowledge and decide whether a candidate is adopted. Those constraints are what make the project read as auditable engineering infrastructure rather than another automation shell that hides process risk behind a confident model response.
The source and full documentation are available at didi/helixharness under Apache-2.0. For developers building an agent harness, a coding workflow, or a team knowledge system, three design choices deserve separate study: artifacts as completion evidence, index-driven context loading, and a hard boundary between host adapters and framework evaluation.
SOURCE LINKS