codex-flows/docs/pages/tutorials/first-flow.md

title	description
Build your first flow	Create a minimal Bun-backed flow package and run it locally.

Build your first flow

This tutorial creates a flow package that handles a demo.hello event and prints a FLOW_RESULT.

1. Create the files

Flow packages live under flows/* while installed copies can live under .codex/flows/*. Create this structure:

flows/hello-flow/
  flow.toml
  schemas/hello.schema.json
  exec/hello.ts

2. Write the manifest

name = "hello-flow"
version = 1
description = "Greets a person from a demo event."

[[steps]]
name = "hello"
runner = "bun"
script = "exec/hello.ts"
timeout_ms = 30000

[steps.trigger]
type = "demo.hello"
schema = "schemas/hello.schema.json"

3. Add the event schema

{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": { "type": "string" }
  }
}

4. Implement the step

const context = JSON.parse(await Bun.stdin.text());
const name = context.flow.event.payload.name;

console.log(`FLOW_RESULT ${JSON.stringify({
  status: "completed",
  message: `hello ${name}`,
})}`);

The runner sends JSON on stdin. The step must print a final line beginning with FLOW_RESULT followed by JSON.

5. Fire the event

Create event.json:

{
  "id": "demo:hello:ada",
  "type": "demo.hello",
  "source": "tutorial",
  "receivedAt": "2026-05-15T00:00:00.000Z",
  "payload": {
    "name": "Ada"
  }
}

Run all matching steps:

bun run flow fire --event event.json

You should see the event id and one result for hello-flow/hello.