Skip to content

Step types

Every step has a type:

Type In the type picker JSON type
Agent Run a coding agent or LLM with a prompt agent
Shell Run a command: tests, linters, git, deploys shell
Approval Pause until a human approves approval
Pipeline Run another pipeline as one step pipeline
Condition Branch: continue on its yes or no path condition
Integration Do something in another app: Slack, Todoist… integration

You can switch a step’s type at any time with the type picker at the top of the step’s settings; fields for other types are kept but ignored.

UI label JSON Default Notes
Name name New agent step / Run command / Approval / the chosen pipeline’s name / Condition Display name in the graph, logs and notifications.
Step id id agent, command, approval, a slug of the pipeline’s name, condition (+ a number if taken) Stable key used in templates: {{steps.<id>.output}}. Letters, digits, -, _; must start with a letter or _. Unique within the pipeline. The UI strips other characters as you type.
— description — Optional free text. Not shown in the editor.

An agent step renders its prompt and runs it on a harness with a model, in the run’s workspace.

UI label JSON Default Notes
Harness harnessId the first enabled, detected CLI harness when the step is added (falls back to the first enabled harness, then claude-code) ● marks harnesses detected as available, ○ those that aren’t. API harnesses are labelled “(API)”. Disabled harnesses are hidden unless the step already uses one. Changing the harness clears the model.
Model model Default (the harness’s default model) Chips for the harness’s known models, a Default: … chip, and a text box for any other model id. A refresh chip pulls the latest model list when the harness supports it.

The editor warns when the chosen harness is disabled (“… is disabled, so this step will fail”) or not detected (“… is not available: …”). At run time:

  • An unknown harness fails the step with Harness "x" is not configured.
  • A disabled harness fails it with Harness … is disabled — enable it on the Harnesses page or pick another harness.
  • A CLI that isn’t installed fails with Failed to start <command>: … - is "<command>" installed and on PATH? (Settings → Extra PATH entries).

See Harnesses for what each harness does with the prompt, model and system prompt.

UI label JSON Default Notes
Prompt prompt Resolve {{issue.key}}: {{issue.title}} + blank line + {{issue.description}} Required. A template. Not shell-quoted. Generate with AI writes or revises it for you.
System prompt (optional) systemPrompt empty A template. Passed with the harness’s system-prompt flag if it has one (Claude Code and Pi use --append-system-prompt, which appends to the agent’s built-in system prompt). For CLI harnesses without such a flag it’s prepended to the prompt, separated by a --- line. API harnesses send it as the system message.

Each agent runs in isolation and only knows what its prompt says. Include the issue, the upstream outputs it needs, what not to do, and what to output. See Templates and the prompt guidance in Generating pipelines with AI.

Chips for each subagent defined in Pipeline settings → Subagents; click to attach (subagents: ["id", …]). Only harnesses with Subagent arguments configured receive them (the built-in Claude Code harness does); others ignore them, and the editor warns “… has no subagent arguments configured, so these subagents will be ignored.” See Subagents.

An agent step succeeds when the harness process exits with code 0 (and, for structured output formats, doesn’t report an error result), or the API call completes normally. The Claude API harness fails on a refusal or max_tokens stop reason. Then the verdict patterns are applied.

A shell step runs a command with a POSIX shell in the run’s workspace: /bin/sh on macOS and Linux, and Git Bash (from Git for Windows) on Windows. The same commands work on every OS.

UI label JSON Default Notes
Command command npm test Required. A template. Generate with AI can write it.
Run in inRepos The workspace root (field absent) Each changed repository (changed) or Each repository (all) runs the command once per repository in a folder of several repositories. See Running in each repository.
  • Exit code 0 is success; anything else fails the step with Command exited with code N.
  • Every interpolated {{value}} is shell-quoted automatically, so issue text can’t inject commands. Add | raw as the last filter to insert a value unquoted, for values that are themselves commands: {{vars.testCommand | raw}}. See Shell quoting.
  • Issue and run data is also exported as environment variables ($FACTORY_ISSUE_KEY, $FACTORY_ISSUE_TITLE, $FACTORY_BRANCH, $FACTORY_WORKSPACE, …). Using them inside double quotes is often the most readable option. See Environment variables.
  • The step’s output is stdout and stderr combined.
  • Multi-line commands are fine; the whole text is passed to the shell.
  • Child processes inherit a non-interactive environment: CI=1 (unless already set), NO_COLOR=1, FORCE_COLOR=0, GIT_TERMINAL_PROMPT=0. There is no stdin, so anything that prompts will hang until the timeout.
Terminal window
# Open a PR (from the built-in templates)
git push -u origin HEAD && gh pr create --base {{run.baseBranch}} \
--title "$FACTORY_ISSUE_KEY: $FACTORY_ISSUE_TITLE" \
--body "Automated by Jimothy run #$FACTORY_RUN_NUMBER. $FACTORY_ISSUE_URL"

When the workspace is a folder of several repositories, Run in decides where the command runs:

  • The workspace root (default): once, in the workspace folder.
  • Each changed repository: once in each repository the run has changed so far.
  • Each repository: once in every repository.

In a workspace that is a single repository, the command runs once at the root whatever you choose.

For each repository, the command is rendered and run separately:

  • The working directory is the repository.
  • {{vars.setupCommand}}, {{vars.testCommand}} and the other commands are that repository’s own: set on the repository in the app, else from its Jimothyfile, else the project’s. See Commands for each repository.
  • {{repo.path}}, {{repo.name}} and {{repo.baseBranch}} are set, and {{run.baseBranch}} and $FACTORY_BASE_BRANCH are the repository’s base branch. $FACTORY_REPO is the repository’s path.
  • If the command renders empty for a repository (for example {{vars.lintCommand | raw}} where it has no lint command), that repository is skipped.

Every repository runs even if one fails. The output has a ### <path> section per repository with its output, then a summary:

### api
…
### web
…
Repositories:
- api: failed (exited with code 3)
- looker: skipped (no command)
- web: passed

If any repository fails, the step fails with the list of them, here Failed in api, and a feedback loop can read the summary to see where. With Each changed repository and no changed repository, the step succeeds with No repository has changed, so there is nothing to run.

The step’s Timeout applies to the whole step, not to each repository.

Terminal window
# Run in: Each changed repository
{{vars.testCommand | raw}}

An approval step pauses its branch of the pipeline until a human decides.

UI label JSON Default Notes
Message shown to the approver approvalMessage Approve {{issue.key}} to continue. A template, rendered as Markdown. If empty at run time: Approve to continue.
Let the approver pick from choices.fromStep Nothing (field absent) An agent or shell step whose numbered options (### Idea 1: … headings or a 1. … list) the approver picks from. See Picking from options.
Selection choices.mode multiple multiple (one or more) or single (exactly one). Shown once a source step is set.

When the step starts, it becomes Needs approval, the approval.required notification fires (desktop by default, plus any channel subscribed to it), and the run page shows a banner with the message, an optional comment box, and Reject / Approve. See Approvals.

  • Approve: the step succeeds. Its output is the comment. With choices, the approver must pick first, and the output is the picked options’ text followed by the comment as Approver notes: ….
  • Reject: the step fails with Rejected by <name>: <comment>. Dependents are skipped and the run fails, unless the step has Continue on error or a loop-back.
  • The decision is recorded with the approver’s name (Settings → General → Your name, default me) and time. Templates can read {{steps.<id>.comment}} and {{steps.<id>.approvedBy}}, and with choices {{steps.<id>.selected}}, .selectedIds and .selectedTitles.
  • Other parallel branches keep running while an approval waits.
  • Rejecting with a loop-back sends work back upstream: set On failure, loop back to on the approval step, and the rejection comment is available to the re-run steps as {{steps.<approval id>.output}}. Use .output here: the loop resets the approval step and clears its comment and approvedBy, but keeps its output.

Approval steps ignore Timeout, Retries and the pass/fail patterns: they wait indefinitely and run once per pass.

A pipeline step runs another pipeline as a single step. Use it to reuse a pipeline you already have (for example a shared Review → PR tail) instead of copying its steps.

UI label JSON Default Notes
Pipeline to run pipelineId the first pipeline that can run here Required. Pipelines that already run this one (directly or through their own pipeline steps) are disabled and marked (runs this pipeline), and a pipeline can’t run itself. Open … jumps to the chosen pipeline.
Work in this run’s workspace and branch ownWorkspace (inverted) on (field absent) On: the sub-pipeline works in this run’s workspace and branch, so it sees and builds on this run’s changes, and uses this pipeline’s workspace settings (base branch, cleanup). Off ("ownWorkspace": true): it prepares its own workspace from its own settings and doesn’t see this run’s changes.

Set the sub-pipeline’s variables for this run (inputs). The section lists the variables the chosen pipeline declares, with their defaults as placeholders; Other variables adds any other name. Values are templates rendered in this run, for example {{steps.plan.output}}. An empty value keeps the pipeline’s default. Inside the sub-pipeline they’re {{vars.<name>}}.

  • The sub-pipeline starts as its own linked run with the same issue, shown as triggered by Run #<n> · <step name>. The step waits for it and succeeds or fails with it.
  • Its progress is mirrored into the step’s log (▸ Plan, ✓ Implement (4m 12s), ✗ Run tests: …), and approvals inside it also show up on this run’s page. You can open, approve or cancel the sub-run on its own page too.
  • Output: the sub-pipeline’s final output, meaning the output of its last step (or of each final step, under ### <step name> headings, when it ends in parallel branches). On failure it’s the failing step’s output, so a feedback loop gets the reason.
  • Its steps are available as {{steps.<id>.steps.<sub-step id>.output}}.
  • Links it finds (pull requests, previews) are added to this run, and its cost and tokens count toward this step.
  • It runs inside this run’s concurrency slot but still respects its own pipeline’s Max concurrent runs. While that’s full, the step logs Waiting for a free slot and waits.
  • Cancelling this run cancels the sub-run. Timeout cancels it too, failing the step with Timed out after N min. Retries and loop-backs start a fresh sub-run.

Errors that fail the step before anything runs:

  • No pipeline chosen, or The pipeline this step runs no longer exists (…).
  • "<name>" is already running further up this chain; running it again would loop forever.
  • Sub-pipelines are nested more than 10 deep.
  • Can't start "<name>": … when the pipeline (or, with its own workspace, its workspace) isn’t valid.

A condition step checks values from the run and answers yes or no. Steps after it are on its yes or no branch, and only the branch that matches the answer runs. It doesn’t run an agent or a command.

Each rule compares a value to check with something, using a comparison:

Comparison JSON op Passes when
contains / does not contain contains / not_contains The value includes the text (or doesn’t).
equals / does not equal equals / not_equals The value is exactly the text (or isn’t).
matches regex / does not match regex matches / not_matches The regex finds a match (or doesn’t).
is empty / is not empty is_empty / is_not_empty The value is blank (or isn’t). No compare value.
is greater than / is less than greater_than / less_than The first number in the value is greater (or less) than the first number in the compare value. Coverage: 83% compares as 83. False if either has no number.
  • Both sides are templates, such as {{steps.triage.output}}, {{issue.labels}} or {{vars.deploy}}. The value box suggests the values available to the step.
  • Text comparisons ignore case and surrounding whitespace. Regexes are case-insensitive and multi-line, like verdict patterns.
  • A new condition starts with one rule that checks the output of the step before it with contains.
  • Add rule adds another. With more than one rule, choose All must pass ("match": "all") or Any can pass ("match": "any").
  • The editor previews the rules against example values and shows what they would answer.

The step’s output is yes or no ({{steps.<id>.output}}), and its log lists each rule as it was checked:

✓ "TYPE: bug" contains "bug"
→ yes

Each step that runs after a condition is on one of its branches, set with Yes / No:

  • On the condition, the Branches section lists the steps that follow it.
  • On a following step, On the branch of condition appears under Flow.

A step is on the yes branch unless set otherwise, and steps you add while a condition is selected start there. The JSON stores only the no branches: "onBranch": { "<condition id>": "no" }.

When the condition answers, the branch that isn’t taken is skipped (Not taken: "<condition>" answered no), along with every step that only follows it. A step that runs after both branches, or after a taken branch and another step, still runs, so branches can join again. If the condition itself is skipped or fails, the steps on both of its branches are skipped.

  • A condition step needs at least one rule, and each rule needs a value, and a compare value where the comparison takes one. Saving is blocked otherwise.
  • An invalid regex fails the step at run time: Invalid regex /…/: ….
  • Conditions ignore Timeout and Retries, and have no quality gate or loop-back. Runs after, Run only if and Continue the pipeline even if this step fails still apply.

Use a condition when the path depends on a step’s result, such as running a bug-fix fast lane for bugs and a full plan for features. To just skip one step, Run only if is simpler. See Retries, timeouts & conditions.

An integration step does one thing in another app with a signed-in account, such as creating a Todoist task. See Integrations for the apps and their actions.

UI label JSON Default Notes
Account integration.connectionId none Required. Any account from Settings → Accounts & integrations whose app has actions. With none, the step offers a link to sign in.
Action integration.action the app’s first action Required. E.g. Create task. Its description is shown under the menu.
the action’s fields integration.params.<field> per field Templates, rendered in the run. Fields marked (optional) may stay empty; the others must have a value when the step runs. Dropdowns (like a Todoist project) list values from the account.
  • The step’s output is a short summary, e.g. Created Todoist task "Review ENG-123": https://…. The run page shows the action and its rendered fields as the step’s Action.
  • Values the action returns are {{steps.<id>.data.<field>}}, e.g. {{steps.review-task.data.url}}. The step’s settings list which ones it has.
  • If the app returns an error, or the account has been removed, the step fails with that error. Retries and Continue on error work as for other steps.
  • Slack’s Ask and wait for a reply keeps the step waiting until someone replies; see Slack.

Every step except a condition can do integration actions when it finishes, in the After this step section (after). Each action has:

UI label JSON Notes
When the step after[].when succeeds (success), fails (failure) or finishes (always). A step that loops back counts as failed.
Account, Action and fields after[].connectionId, .action, .params As for integration steps. Templates can use the step’s own result: {{steps.<this id>.output}} and .error.

Actions run in order, after the step’s result is final and before the steps that depend on it start. A failing action doesn’t change the step’s result: the error is logged to the step as After step: <action> failed: …, and the run carries on.

{
"id": "review",
"type": "agent",
"after": [
{
"when": "failure",
"connectionId": "con_01h…",
"action": "comment",
"params": { "task": "{{issue.id}}", "text": "Review asked for changes:\n\n{{steps.review.output}}" }
}
]
}
UI label JSON Default Notes
Runs after dependsOn previous step (field absent) Steps this one waits for. [] = starts immediately. See DAG & parallelism.
On the branch of condition onBranch Yes (field absent) Shown for each condition step this one runs after. See Branches.
Timeout (minutes) timeoutMinutes none Kills the attempt (whole process tree, or the sub-run for a pipeline step) after this long. Empty or 0 = no timeout. Not applied to approvals or conditions. Each request an integration step makes to the app times out after 30 seconds. Slack’s Ask and wait for a reply then waits for an answer until this timeout, if one is set.
Retries on failure retries 0 Extra attempts after a failure (UI allows 0–10). Exponential backoff 2s, 4s, 8s, 16s, 30s cap. Not applied to verdict failures, approvals or conditions.
Run only if runIf empty Template; the step is skipped unless it renders truthy. Placeholder: {{vars.deploy}}.
Continue the pipeline even if this step fails continueOnError off Dependents run and the run can succeed even though this step failed.
Artifacts artifacts empty Agent and shell steps: globs for the files to keep and show on the step, e.g. docs/designs/**, *.png. Empty = every document and image the step adds or changes. See Artifacts.

Details and examples: Retries, timeouts & conditions.

Quality gate & feedback loop (all step types except condition)

Section titled “Quality gate & feedback loop (all step types except condition)”
UI label JSON Default Notes
Pass if output matches (regex) passPattern empty If set and the output doesn’t match, the step fails. Placeholder VERDICT:\s*APPROVE.
Fail if output matches (regex) failPattern empty If it matches, the step fails. Checked before the pass pattern. Placeholder CHANGES_REQUESTED.
On failure, loop back to loopBackTo — fail the step — When the step fails, re-run from this step.
Max loops maxLoops 2 How many times this step may loop back per run (UI allows 1–10). Disabled until a loop-back target is chosen.

Patterns are case-insensitive and multiline. They don’t apply to approval steps. For pipeline steps they’re checked against the sub-pipeline’s output. See Loops & verdicts.

env adds environment variables for this step only (agent and shell steps), on top of global (Settings) and project env. For agent steps the harness’s own env is applied last. FACTORY_* variables can’t be overridden. See Environment variables.

In the editor, the eye button next to a variable lets AI assistants connected through the MCP server read its value; values are hidden by default. The names of visible variables are stored as envShown.

{
"id": "implement",
"name": "Implement",
"type": "agent",
"harnessId": "claude-code",
"model": "sonnet",
"prompt": "Implement {{issue.key}}: {{issue.title}}\n\n{{issue.description}}\n\nPlan:\n{{steps.plan.output}}",
"systemPrompt": "You are a careful senior engineer. Keep changes minimal.",
"subagents": ["test-writer"],
"dependsOn": ["plan"],
"timeoutMinutes": 60,
"retries": 1,
"env": { "NODE_ENV": "development" }
}

All fields:

Field Type Applies to
id string all
name string all
type "agent" | "shell" | "approval" | "pipeline" | "condition" all
description string all
harnessId string (harness id, e.g. claude-code, codex, anthropic-api, simulator) agent
model string; empty = harness default agent
prompt template agent
systemPrompt template agent
subagents string[] (subagent ids) agent
command template shell
inRepos "changed" | "all"; absent = the workspace root shell
approvalMessage template approval
choices { "fromStep": step id, "mode": "single" | "multiple" } approval
pipelineId pipeline id pipeline
inputs object of templates (variable name → value) pipeline
ownWorkspace boolean; absent = work in this run’s workspace pipeline
condition { "match": "all" | "any", "rules": [{ "value", "op", "compare" }] } condition
onBranch object: condition step id → "yes" | "no"; absent = yes steps after a condition
dependsOn string[]; absent = previous step all
timeoutMinutes number agent, shell, pipeline
retries number agent, shell, pipeline
continueOnError boolean all
passPattern / failPattern regex string (JSON-escaped: "VERDICT:\\s*APPROVE") agent, shell, pipeline
loopBackTo step id all
maxLoops number, default 2 all
env object of strings agent, shell
envShown array of env names whose values AI assistants may read agent, shell
runIf template all