Bee Box documentation · directory: https://beebox.run/docs/capabilities/ · index: https://beebox.run/docs/capabilities/index.md · root: https://beebox.run/llms.txt

# Procedures

A box is a directory of your data, kept under version control with a full
history of changes (using git); a card is a markdown file with a structured
header; the agent is the coding agent (Claude Code or Codex) that operates the
box. A procedure is a named, reusable, multi-step process defined as a card.

**What it does for you**

- Runs a defined sequence of steps in order, each with an optional
  precheck (should this step even run), the action itself, and a
  validation (did it actually work), including a model judging whether a
  step did what it was supposed to.
- Lets you pass a one-off instruction (a "directive") into a run without
  editing the procedure itself, e.g. "prefer the reading list over
  trashing."
- Keeps a record of every run, resumable if it fails partway through, so a
  long process does not have to restart from scratch.
- Can be triggered by a mail rule or other automation, not only run by hand.

**What it needs**

Nothing beyond the box itself. Procedures are cards you or the agent write
(kept in `_config/procedures/`, for the curious).

**How it works, briefly**

Each step saves its work to the box's history before the next step starts,
so the box's state after a partial run is always a clean, inspectable
snapshot. Steps can run a command, an agent turn, or both. A run is tracked
as a `procedure-run` card while it is recent; the box's history keeps every
finished run afterward. Procedures run when you invoke one, when another
automation triggers it, or as a triage "handle" step (the reference page
below covers the details).

**Limits**

A run's record is kept only temporarily, not as a permanent archive: finished
runs expire on a timer (30 days by default, configurable) unless pinned. The
documentation does not describe a visual procedure editor; procedures are
written as cards.

**Go deeper**

[../reference/procedures.md](https://beebox.run/docs/reference/procedures.md),
[../reference/cards/procedure.md](https://beebox.run/docs/reference/cards/procedure.md),
[../reference/cards/procedure-run.md](https://beebox.run/docs/reference/cards/procedure-run.md),
[../reference/bbx-commands.md](https://beebox.run/docs/reference/bbx-commands.md)