How the agent loop works

The plan→implement→review cycle that every spec task runs through, and why each step exists.

Every spec task in Helix runs through the same loop:

1. Define   You write a spec describing the desired outcome
2. Plan     An agent reads your codebase and proposes an execution plan
3. Approve  You review and approve (or give feedback to revise)
4. Implement The agent works inside an isolated sandbox
5. Review   A pull request is opened for human review and merge

This isn't just a workflow convention — each step exists for a specific reason.

Why planning comes before implementation

Agents that jump straight to implementing make more irreversible mistakes. A plan is cheap to revise; committed code is expensive to undo.

The planning step also surfaces assumptions early. If the agent misunderstood the scope — planning to change the backend when you only wanted a frontend fix — you catch it before any code is written.

The plan lives in a helix-specs branch in your repository, which means it's reviewable, versioned, and linkable.

Why you approve the plan

Agents are capable but not infallible. The approval step keeps a human in the loop at the highest-leverage point: before implementation starts. This is when changing direction is cheapest.

Helix doesn't require you to read every line of the plan — many teams scan the top-level steps and spot-check the details. The pull request is the real review gate.

What happens during implementation

The agent runs inside an isolated sandbox — a containerized Linux desktop with Zed IDE, a terminal, and a browser. The sandbox has:

• Your repository pre-cloned to the approved plan's starting state
• Access to your configured LLM provider for inference
• No access to the host machine, other sandboxes, or the internet beyond what the task needs

The agent uses the same tools a developer would: reads files, edits them, runs tests, commits. It can browse the web, install packages, and run arbitrary commands — inside the container.

Each edit is committed to a working branch. If the sandbox crashes mid-implementation, commits are preserved and the agent can resume.

Why pull requests, not direct pushes

The agent never merges to your main branch. Pull requests give you:

• A standard diff review in your existing tooling
• CI to run before merge
• A record of what changed and why (the spec task is linked)
• The ability to close the PR and try again with a revised spec

This also means Helix integrates with your existing code review culture — reviewers don't need to know Helix exists. They see a normal pull request.

The agent loop and your role

Helix is designed around the idea that agents do better work when humans stay in the loop at the right moments:

The agent handles implementation; you handle direction and quality gates.

Parallel tasks

Multiple spec tasks can be in the Implement phase simultaneously. Each gets its own sandbox — they don't share files, processes, or network. Running tasks in parallel doesn't increase the risk to any individual task.

See Manage your backlog for how to run tasks in parallel in practice.