# agents.wf

**Repeatable workflows for coding agents.**

Coding agents that follow your process. TypeScript fixes the steps, the agents do the thinking, and runs are durable and event-driven. Your workflow is your code, not a feature of someone's platform.

- [Get started](/guide/quick-start.md)
- [Why agents.wf](/guide/index.md)
- [GitHub](https://github.com/romanlv/agentswf)

- **[Deterministic where it counts](/guide/agents.md#a-typed-answer).** The order, the loops, how many rounds and the deadlines are code you wrote, the same on every run. Every answer is checked against your schema before your code sees it.
- **[Real agents do the thinking](/guide/agents.md#compact-switch-fork).** Real coding agents, with their own skills and sessions, do the work that needs judgment. An agent keeps its context across turns, and can fork to try another angle.
- **[Durable and event-driven](/guide/events.md).** A failed CI check, a webhook or a timer starts or wakes a run, which parks in between with no process left. Finished stages are kept, so a crash costs only the stage that was running.
- **[Yours](/guide/harnesses.md#subscription-and-metered).** It runs on your machine, on your own logins and plan limits, and keeps its records as plain files in your project. MIT. No hosted service sits between you and your agents.
- **[Measurable](/guide/cost.md).** Every run records each agent's turns, time and tokens. Swap a model, a prompt or a skill, and compare the runs.
- **[Written by your agent](/guide/quick-start.md#have-your-agent-write-the-next-one).** A frontier model writes the workflow, cheaper ones can run it. The typechecker and awf test, which runs it on scripted answers for free, catch its mistakes before any agent starts.

```sh
bun add -g agentswf
```

## Code decides, agents think

An implementer on claude, a reviewer on codex, and a loop until the reviewer's typed answer
approves. `DONE` and `VERDICT` are [TypeBox](https://github.com/sinclairzx81/typebox) schemas:
`{ summary }` and `{ approved, changes }`.

```ts
const implementer = await wf.agents.open({
  key: "implementer",
  runtime: "claude",
});
const reviewer = await wf.agents.open({
  key: "reviewer",
  runtime: { harness: "codex", model: "gpt-6-luna", placement: "headless" },
});
let prompt = `Implement this task: ${task}`;
for (let round = 1; round <= 3; round++) {
  const work = await implementer.run({ prompt, schema: DONE });
  if (!work.outcome.answered)
    return wf.stop(`implementer: ${work.outcome.reason}`);
  const review = await reviewer.run({
    prompt: "Review the change.",
    schema: VERDICT,
  });
  if (!review.outcome.answered)
    return wf.stop(`reviewer: ${review.outcome.reason}`);
  if (review.outcome.value.approved)
    return { approved: true, rounds: round };
  prompt = `Make these changes:\n${review.outcome.value.changes.join("\n")}`;
}
return { approved: false, rounds: 3 };
```

The loop and its limit are code; the reviewer's verdict is a checked boolean, not a guess from
prose. The implementer works in a pane in [Herdr](https://herdr.dev), a terminal multiplexer,
where you can watch it and type to it; Herdr is optional, and every agent can run headless
instead. The engine handles an agent that goes quiet, answers in the wrong shape, or hangs.
[Why agents.wf](/guide/) says what this is for.

## From hand-run to automated

- **By hand:** you prompt one agent, paste its output to another, and decide when it's done.
- **A workflow:** `awf run review-loop.ts` runs the same steps every time and records each turn.
  If a workflow with [stages](/guide/durability) stops part-way, a continue reuses the stages
  that finished.
- **On its own:** a workflow with [events](/guide/events) gets a run per pull request. Your CI or
  a webhook sends it events, `awf tick` on a schedule brings timers due
  ([Hosting events](/guide/hosting-events)), and between them the run parks. A
  [person](/guide/people) can answer it in the terminal, or through a chat app or script you
  connect.

## How it works

1. Your code calls `agent.run({ prompt, schema })`.
2. awf hands the prompt to a coding agent, in a [Herdr](https://herdr.dev) pane you can watch or
   headless.
3. The agent works in your repo with its own tools and skills, then answers by running
   `wfa result`.
4. awf checks the answer against your schema. A wrong shape goes back to the agent to fix; a quiet
   agent gets a nudge.
5. `await` returns a typed value, and your code decides what happens next.

`awf run ./workflow.ts` runs the workflow, prints its result, and keeps a record of the run in
`.awf/runs`. [How it works](/guide/how-it-works) has the rest.

## Built for agents to write

Your coding agent writes the workflow. Every page here is also Markdown for it to read, and the
[API](/reference/workflow-api) is one page. After a change it runs the typechecker and `awf test`,
which catch its mistakes before any agent starts. What it writes is agents, prompts, schemas and
plain `for` and `if`, so you can review it in a minute: [Quick start](/guide/quick-start#have-your-agent-write-the-next-one)
says what to check.

Write the workflow with a frontier model, then run it on cheaper or open-weight ones: each agent's
model is one line, and [Cost](/guide/cost) shows what the change did to a run.

## Open, and shaped by use

- **Open source.** MIT licensed, on [GitHub](https://github.com/romanlv/agentswf).
- **In its evaluation phase.** The design is still moving, and what people build with it decides
  where it goes. Hit a bug, missing a use case, or have a better idea for the design?
  [Open an issue](https://github.com/romanlv/agentswf/issues).
- **What runs today and what is next:** [status](https://github.com/romanlv/agentswf/blob/main/docs/status.md).
- **How it is tested:** [the test levels](https://github.com/romanlv/agentswf/blob/main/docs/testing.md),
  from free to live agents. **What was measured:** [findings](https://github.com/romanlv/agentswf/tree/main/docs/findings).

## Your first workflow

[The quick start](/guide/quick-start) takes you from install to a first run and its result.