The open-source Aharness project promises to solve what may be the next frontier of AI coding agent failures: process drift. Built specifically for Codex CLI, Aharness converts multi-step workflows into finite state machines (FSMs) that actively enforce transitions, typed evidence collection, and approval gates—something traditional prompts simply cannot guarantee.

The Process Drift Problem

Modern agents have crossed a threshold. They can handle long-running, autonomous, multi-step work when given the right guardrails. But according to Aharness creator Alfredvc on Hacker News, "the main failure mode has shifted from task ability to process drift: skipping approval, forgetting recovery rules, claiming evidence that was not produced, or continuing from stale context." Prompts describe processes; they don't enforce them. That's the gap Aharness fills.

FSMs as Workflow Runtimes

Aharness defines workflows in TypeScript using createFsm, fsm.state, fsm.submit, and fsm.choice constructs. The approach sits between two bad extremes—raw code flexibility that can't be constrained versus YAML/JSON rigidity too strict for real development work. By authoring FSMs in TypeScript, developers get typed data validation, guards, reducers, effects, npm ecosystem access, and composable modules. "The bet is that useful workflows are reusable software," the project states. They should be authored, reviewed, versioned, composed from smaller FSMs, and published as npm packages instead of copied around as prompts.

Architecture: Three Jobs During a Run

Aharness runs perform three distinct functions: First, it verifies the workflow before Codex starts—invalid FSMs fail early before the model begins work. Second, it keeps Codex inside the active state by telling the agent current state, valid exits, and required submit schemas, then validates submitted evidence before deciding transitions. Third, it records everything under .aharness/runs// including event logs, state history, final artifacts, and data for browser inspection views. The architecture connects Aharness CLI as FSM actor/verifier, Codex CLI as the agent worker, a loopback browser UI for live operator input and approvals, and run directories storing sensitive evidence.

Codeflow Package and Quickstart

The bundled @aharness/codeflow package handles recipe-driven development against implementation roadmaps with npm install -g @aharness/core followed by aharness install @aharness/codeflow. Commands include aharness verify for structural validation, aharness run to execute workflows, and aharness view [run-id] to reopen completed runs from recorded artifacts. The demo workflow at examples/coding-smoke.fsm.ts repairs a broken TypeScript fixture while demonstrating states, submissions, approvals, hooks, and composition.

Key Takeaways

  • FSMs enforce transitions that prompts can only describe
  • Workflows authored in TypeScript stay enforceable yet composable via npm packages
  • Browser UI provides live state visualization, compact transcripts, and owner controls
  • Runs produce canonical artifacts including events.jsonl, state history, and browser views for inspection
  • Aharness ships with a bundled FSM authoring skill so Codex can design workflows itself

The Bottom Line

This is exactly the kind of infrastructure layer that gets taken for granted until it's missing. If you're running autonomous agents on real codebases where approval gates, typed evidence, or recovery paths aren't optional—Aharness deserves your attention before your agent gaslights you about work it never actually completed.