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.
Common fields
Section titled “Common fields”| 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. |
Agent steps
Section titled “Agent steps”An agent step renders its prompt and runs it on a harness with a model, in the run’s workspace.
Harness & model
Section titled “Harness & model”| 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.
Prompt
Section titled “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.
Subagents
Section titled “Subagents”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.
What counts as success
Section titled “What counts as success”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.
Shell steps
Section titled “Shell steps”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
0is success; anything else fails the step withCommand exited with code N. - Every interpolated
{{value}}is shell-quoted automatically, so issue text can’t inject commands. Add| rawas 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.
# 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"Running in each repository
Section titled “Running in each repository”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_BRANCHare the repository’s base branch.$FACTORY_REPOis 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: passedIf 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.
# Run in: Each changed repository{{vars.testCommand | raw}}Approval steps
Section titled “Approval steps”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}},.selectedIdsand.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.outputhere: the loop resets the approval step and clears itscommentandapprovedBy, but keeps its output.
Approval steps ignore Timeout, Retries and the pass/fail patterns: they wait indefinitely and run once per pass.
Pipeline steps
Section titled “Pipeline steps”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.
Pipeline
Section titled “Pipeline”| 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. |
Inputs
Section titled “Inputs”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>}}.
How it runs
Section titled “How it runs”- 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, orThe 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.
Condition steps
Section titled “Condition steps”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.
Condition
Section titled “Condition”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"→ yesBranches
Section titled “Branches”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.
Limits
Section titled “Limits”- 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.
Integration steps
Section titled “Integration steps”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.
After this step
Section titled “After this step”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}}" } } ]}Flow options (all step types)
Section titled “Flow options (all step types)”| 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.
Environment (all step types)
Section titled “Environment (all step types)”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.
JSON reference
Section titled “JSON reference”{ "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" }}{ "id": "test", "name": "Run tests", "type": "shell", "command": "{{vars.testCommand | raw}}", "dependsOn": ["implement"], "timeoutMinutes": 20, "loopBackTo": "implement", "maxLoops": 2}{ "id": "approve", "name": "Human approval", "type": "approval", "approvalMessage": "Approve to push {{run.branch}} and open a pull request for {{issue.key}}.", "dependsOn": ["review"]}{ "id": "review_pr", "name": "Review → PR", "type": "pipeline", "pipelineId": "p_review_pr", "inputs": { "plan": "{{steps.plan.output}}", "reviewer": "codex" }, "dependsOn": ["implement"], "timeoutMinutes": 90}[ { "id": "is_bug", "name": "Is it a bug?", "type": "condition", "condition": { "match": "any", "rules": [ { "value": "{{steps.triage.output}}", "op": "contains", "compare": "TYPE: bug" }, { "value": "{{issue.labels}}", "op": "contains", "compare": "bug" } ] }, "dependsOn": ["triage"] }, { "id": "quick_fix", "name": "Quick fix", "type": "agent", "harnessId": "claude-code", "prompt": "…", "dependsOn": ["is_bug"] }, { "id": "plan", "name": "Plan", "type": "agent", "harnessId": "claude-code", "prompt": "…", "dependsOn": ["is_bug"], "onBranch": { "is_bug": "no" } }]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 |