autohelix 0.0.1

Put an AI agent in a verified improvement loop.

Set constraints and metrics; the agent proposes changes in a loop.
Only changes that pass checks get merged. Improvements compound across iterations.

works with Claude Code · Codex · OpenCode

How it works · Quick start · Examples · Configuration · Other features · FAQ

AutoHelix is a lightweight harness that lets you point an agent at a goal and leave it looping unattended. It provides the isolation, validation, scope, and budget control to make that safe, and it's general enough for any measurable goal, from optimizing code to training models.

Looping an agent can be far more effective than a single prompt, because later iterations fix and build on what came before, and because it gives you a knob for controlling how much effort (time or cost) to put toward the goal rather than letting the agent decide when it's done. AutoHelix makes this pattern easy to run and customize, so you can let the agent climb for as long as you want.

How it works

You define a goal, the constraints that must hold, and the metrics to track. The agent proposes changes and the harness decides if they land.

Core features:

• Isolation. Each iteration runs in a fresh git worktree. A rejected attempt's code is cleanly discarded.
• Scope enforcement. Only files marked editable can be changed; everything else is frozen.
• Constraints gate changes. Tests, type-checks, or any command that must exit 0. Break a constraint and the iteration is discarded.
• Metrics track progress. Metrics are captured and shown to the next iteration. Optionally gate on them to reject regressions. Logs and artifacts can be saved too.
• Persistent memory. Each iteration is a fresh session, but the agent reads and writes notes that survive across all iterations, including rejected ones.
• Budget control. Cap the run by iterations, time, or cost.

Quick start

Install from source:

git clone https://github.com/awslabs/AutoHelix.git
cd AutoHelix
python -m venv .venv && source .venv/bin/activate
pip install -e .

AutoHelix uses Claude Code by default (looks for claude on your PATH). Codex and OpenCode are also supported — see agent setup.

cd my-project
autohelix init          # initialize config and state
autohelix run           # start the loop

init creates a commented autohelix.yaml to fill in — see the configuration section below. Other commands are described in the CLI reference.

Examples

The examples/ directory has ready-to-run tasks across different domains, from a 2-minute sorting function example to algorithm optimization and model training. To list what's available:

python examples/setup_example.py --list

Code optimization. AlgoTune is a benchmark for optimizing widely used algorithms in math, physics, and CS. AutoHelix can scaffold any of them via examples/algotune (we measure speedup with our own eval setup, not identical to AlgoTune's official harness). The plot below shows a run with Claude Opus 4.8: across 154 tasks, the median speedup climbs each iteration, reaching ~8.5× by iteration 5.

Model training. The same loop works when each iteration is a training run rather than a code edit: the agent writes the training code and trains a model, and AutoHelix scores the result with a frozen eval the agent can't modify. In examples/posttrain (inspired by PostTrainBench), the agent is asked to post-train Qwen3-4B-Base on GSM8K. Given an open-ended goal (no method prescribed), the agent worked its way up from supervised fine-tuning through rejection sampling to reinforcement learning (GRPO) — reaching 93% accuracy over 8 iterations on one H200. See the ML Experiments Guide for setup tips.

In the wild. Beyond the bundled examples, we've used AutoHelix on real projects. In Hybrid Model Factory — an open-source toolkit for training hybrid architectures (Attention + SSMs) from our team — the agent autonomously developed a faster sequence-parallelism implementation. Over multiple runs (with some algorithmic hints in the goal), it arrived at a state-passing approach that propagates recurrent state between GPUs instead of redistributing the full sequence, reaching ~5× faster per layer and 1.6× faster end-to-end training at 128K sequence length on a 27B model.

Configuration

A run is defined by a single autohelix.yaml. Every field is documented in docs/config.md.

Project layout

my-project/
├── autohelix.yaml       # your config
└── .autohelix/          # runtime state (gitignored)
    ├── prompt.md        # the prompt the agent gets each iteration (editable)
    ├── history.jsonl    # per-iteration results
    ├── notes/           # agent's persistent notes (the only agent-owned state)
    ├── observations/    # per-iteration captured metrics output and artifacts
    ├── reviews/         # reviewer feedback per iteration (if a reviewer is set)
    ├── hints.md         # messages from `autohelix hint`
    ├── logs/            # per-iteration prompts and agent output
    ├── output/          # dashboard.html and reports
    └── worktrees/       # temp iteration dirs (recreated each time)

Other features

FAQ

Citation

@software{autohelix2026,
  title   = {AutoHelix: Verified Iteration for AI Agents},
  author  = {Trager, Matthew and Mansimov, Elman and Zhang, Yi and Xia, Wei and Soatto, Stefano},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/awslabs/AutoHelix}
}

License

AutoHelix is licensed under the Apache License 2.0.