# agents.wf

> Workflows for coding agents, in TypeScript. A workflow is a TypeScript file that opens coding
> agents (claude, codex, pi, cursor), gives them work and gets typed answers back; `awf` runs it
> and keeps a record of every run.

Use agents.wf when a process between agents is worth writing down once: one agent implements and
another reviews until it approves, several reviewers look at one change, a cheap model triages
before an expensive one works. For one agent doing one task, ask the agent; a workflow adds
nothing.

## How to use these docs

- Start with the [Quick start](/guide/quick-start.md): `awf init`, a test, one real run.
- Every page is also plain Markdown: add `.md` to its URL. A section's index is `index.md`, so
  `/guide/` is `/guide/index.md`.
- Read the [Workflow API](/reference/workflow-api.md) before writing code: every call, option,
  default and outcome is on that one page. Tests use the [Testing API](/reference/testing-api.md).
- [/llms-full.txt](/llms-full.txt) is every page but the landing page, in one file.

## Rules for writing a workflow

The `AGENTS.md` that `awf init` writes into a workflow folder, as written:

````md
# Workflows

This folder holds [agents.wf](https://agents.wf) workflows: TypeScript files
that run coding agents, started with `awf`.

- A workflow is a folder with a `workflow.ts`, which default-exports
  `defineWorkflow(…)` from `agentswf/workflow`, and a `workflow.test.ts` beside it.
  `hello/` is the smallest one; copy it to start another.
- The API, with every option and outcome, as Markdown:
  https://agents.wf/reference/workflow-api.md. Every other page is in https://agents.wf/llms.txt.
- `awf test` runs the tests with each agent replaced by scripted answers: no agent starts, and it
  costs nothing. After a change, run it and `bun run check`, which typechecks.
- `awf run hello/workflow.ts` starts real agents, on the operator's accounts. Don't run a workflow
  unless asked.
- Each run is kept in `.awf/runs/{workflow}/{id}`. `awf runs` lists them; `awf logs {run}` shows
  what one did.
````

## Home

- [agents.wf](/index.md): Repeatable workflows for coding agents: TypeScript fixes the steps, real coding agents do the thinking, and runs are durable and event-driven.

## Get started

- [Why agents.wf](/guide/index.md): Repeatable workflows for coding agents: your process in code, agents for the judgment, durable and event-driven runs, and a workflow that stays yours.
- [Install](/guide/install.md): What awf needs on your machine, per harness and for sandboxes, how a workflow folder gets editor types, and how to update.
- [Quick start](/guide/quick-start.md): Set up a folder with awf init, test its workflow for free, run one real agent, and read what the run kept.
- [How it works](/guide/how-it-works.md): The words the docs use, and what awf does between your workflow and the agents it runs.

## Learn: agents

- [Agents](/guide/agents.md): Calling an agent from a workflow: opening one, giving it turns, getting a typed answer back, what each outcome means, and compacting, switching and forking its session.
- [Harnesses](/guide/harnesses.md): Picking each agent's harness, model and effort, which logins awf runs on and when an agent is metered, and where its pane goes.
- [Sandboxes](/guide/sandboxes.md): Limiting what an agent can write and reach with srt or docker, sharing a sandbox or keeping one private, and sandboxing a whole run from the command line.
- [Tools](/guide/tools.md): Giving an agent your own code to call mid-turn, with a typed input, and what happens when a call is wrong, fails or runs long.

## Learn: workflows

- [Workflows](/guide/workflows.md): A workflow file's parts, its arguments, result, report and printed summary, and how it decides what to do next and when to stop.
- [Parallel and loops](/guide/parallel-and-loops.md): The two shapes most workflows take: agents side by side with wf.parallel, and one agent checking another round after round in a for loop, bounded, branching on each outcome, carrying feedback.
- [Timeouts and nudges](/guide/timeouts.md): Bounding how long a run, a group of agents or one turn may take, how those limits nest, and nudging an agent that goes quiet for its answer.
- [Messaging](/guide/messaging.md): Letting agents message each other while they work, on routes your workflow grants, and what your code sees of it.
- [Decisions](/guide/decisions.md): Asking a decision model closed questions about some text, getting a probability for every answer in about 200 ms, and handing the unsure ones to an agent.
- [Testing](/guide/testing.md): Testing a workflow with awf test, its agents replaced by scripted answers, so no agent starts and a test takes milliseconds.

## Learn: runs

- [Runs](/guide/runs.md): A run's id, attempts and status, how an attempt ends, and going on from a stopped run with stages, --continue, --from-stage and --values.
- [Durability](/guide/durability.md): What survives a failed step, a stop, a crash, a closed laptop or a code change, and what a continue reuses and redoes.
- [Following runs](/guide/following-runs.md): Watching a run while it goes and reading it after, from your terminal or from another agent, with awf run's progress, awf runs and awf logs, and asking an agent about its work with awf open.

## In depth

- [Events](/guide/events.md): Runs that react to things that happen and wait days for them with no process left: event workflows, awf emit, receive, race and select, and timers in brief.
- [Timers](/guide/timers.md): Waiting on time in a run with events: race and sleep on a timer, a timer's fixed time, moving one by cancelling it or by keeping the time in state with wf.at, and when a due timer fires.
- [People](/guide/people.md): Letting agents report to and ask a person or an app outside the run, and answering them with awf inbox, awf reply and awf send.
- [Hosting events](/guide/hosting-events.md): What keeps a waiting run going: awf tick on a schedule for timers and crashes, and a webhook, a CI job or another workflow calling awf emit for events.
- [Programs](/guide/programs.md): Drive a workflow's runs from your own Bun program, typed from the workflow: emit its events from a webhook, relay what its runs post, start a run with args and wait for it.
- [Calling session](/guide/calling-session.md): A workflow that uses the coding session it was started from: handing the session over with awf run --here, forking it with forkCaller, and writing a skill so a session knows to run your workflow.

## Running

- [Cost](/guide/cost.md): What a run took: its time, its tokens and an estimate at dated list prices; what is left of your plans; and how to keep runs cheap.
- [Security](/guide/security.md): What awf trusts and what it doesn't: the workflow, your environment and .env, what awf refuses, what each agent may do, and the gaps that are still open.
- [Troubleshooting](/guide/troubleshooting.md): What awf's error messages mean and what to do about each: logins, API keys, Herdr, sandboxes, an agent that never answers, a run that stopped, type errors.

## Patterns

- [Review loop](/patterns/review-loop.md): Implement, review, revise until approved: a reviewer that knows the rules checks the work itself and asks the implementer for each fix by message.
- [Plan, implement, review](/patterns/plan-implement.md): A ticket from plan to approved change, each step a stage: a planner writes the ticket doc, a reviewer on another model gates it, an implementer builds it, and the reviewer gates that too.
- [Review on event](/patterns/review-on-event.md): Review a merge request when it opens and again at each push, with a run per merge request that waits between events with no process.

## Reference

- [Workflow API](/reference/workflow-api.md): Every call a workflow can make today, from agentswf/workflow, with its options and defaults.
- [Testing API](/reference/testing-api.md): Every call, script and option of agentswf/testing, with its defaults, and what a test's run records.
- [Client API](/reference/client-api.md): Every call of agentswf/client, what each returns and throws: emit, start, get, inbox, a run's status and wait, and ClientError's codes.
- [awf commands](/reference/awf.md): Every awf command, with its usage, options and exit codes, as the command itself prints them.
- [wfa](/reference/wfa.md): The agent's command: every wfa command an agent runs in its session, its flags, exit codes, refusal codes and limits.
- [Data](/reference/data.md): Where awf keeps what: a run's folder in .awf/runs and each file in it, what awf keeps per machine in ~/.awf, and what is safe to delete.
- [Configuration](/reference/configuration.md): Every environment variable and file awf reads, what each means, and its default.