iterward

LLMs do the work. Iterward decides what happens next.

Iterward is a deterministic control plane for agentic engineering workflows. It moves routing, retries, approvals, failures, and stop conditions out of prompts and into a loop file and code that you can test. Agents own execution, and Iterward owns protocol: a run moves only along the transitions its loop file declares, and Iterward records every human move.

Iterward closes the loop around your agents. In a closed-loop agent workflow, each result decides the next step: a failed verification sends the work back to the builder, a gate holds the run until a human approves, and a limit parks the run after too many attempts. Iterward makes those decisions from the loop file, so your agents don't have to.

Get started

Iterward needs Node.js 22.18 or later and has no npm dependencies. To copy the default loop into your repository and start a run, run these commands from the repository root:

npx @push-based/iterward init
npx @push-based/iterward new --config loops/default/default.loop.json --run runs/example/run.json --subject 'the settings page'
npx @push-based/iterward next --run runs/example/run.json

next prints the first dispatch: the message for the planner agent. To install Iterward as a development dependency instead, see Install.

Use it from an agent

The MCP server exposes the CLI's commands as tools. To register it with Claude Code, add it to the .mcp.json file in your repository root:

{
    "mcpServers": {
        "iterward": { "command": "npx", "args": ["-y", "@push-based/iterward@latest", "mcp"] }
    }
}

To keep a run on the version that started it, see Register the server. The server's build-loop tool gives an agent the build-loop skill, which interviews you about a workflow and writes a loop file that compiles.

Documentation

The following pages cover the rest:

• Iterward: the problem, how Iterward works, a loop in code, and what the engine enforces.
• Run the default loop by hand: play every agent and take a run to done.
• Configuration: the loop file, its hooks, and the standard message.
• CLI reference: the commands, their flags, and the exit codes.
• MCP server: drive a run and design a loop through MCP tool calls.
• Protocol rules: the promise, the terms, and the rules.
• Testing: test a loop with node:test.

Develop

The repository is an Nx workspace with one package, packages/iterward. To build and test it, install the workspace, and run the targets through Nx:

npm install
npx nx run-many -t build test

Every commit follows Conventional Commits. A commit-msg hook, which npm install sets up, checks each message.

License

Iterward is available under the MIT License.