Core concepts

The dozen words Peractor is built from, and how they fit together.

Peractor's model is small. Learn these terms once and every screen, YAML file, and API response reads the same way.

The hierarchy

Account            you — one sign-in identity
└─ Organization    the shared tenant: members, connectors, billing
   └─ Project      one codebase's workspace, bound to one repo
      └─ Task      a unit of work — typed by hand or imported
         └─ Run    one execution of a workflow for that task
            └─ Phase → Steps    what actually happens, in order

The vocabulary

Term	What it is
Task	A unit of work in the backlog. Keeps its origin (manual, or a tracker issue) and its full run history — one run active at a time.
Workflow	A declarative pipeline in YAML — phases, steps, gates. A project keeps several; every run follows one.
Phase	A stage of the pipeline (spec, coding, merge…) with ordered steps and, usually, a gate at the end.
Step	One typed unit of work: `prompt`, `check`, `command`, `git`, `notify`, `publish`, `preview`, `loop`.
Gate	The human checkpoint between phases: approve to advance, or request changes to send work back.
Live session	The real-time view of a run — reasoning, diffs, commands, cost — on every surface.
Status	A board column. Yours are user-defined; imported tasks keep their tracker's own columns, untranslated.
Persona	A reusable agent identity — a system prompt with a name and face — bound per step.
Agent	The coding model that does the work: Claude Code or Codex, chosen per workflow or per step.
Connector	An integration: issue trackers, notifiers, git hosts.
Runner	Where phases execute — the built-in sandbox, or machines you register.

Three properties worth internalizing

The branch is the state. Each run works one git branch; phases hand off through it and nothing else. That's why runs survive crashes, waits, and machine loss.
Humans hold the gates. Agents run with their own prompts disabled inside a sandbox; the control point is the gate, where the full evidence is in front of you.
Configuration lives on the host. Workflows, statuses, personas — all edited in the app, shared by the team, versioned per project. A repo carries only peractorrc.json.