Skip to content
Home
Docs/Workflows

Workflows

A workflow is a trigger plus a tree of steps that runs on your device, over a shared context. This page covers every screen of the module, the 25 triggers, the 15 actions, the seven kinds of step, expressions, scheduling, secrets, sharing, and what Free and Pro each get.

What it is and how to open it

Workflows is a full-screen window that opens over the app, not one of the five pages of the pager. A workflow is saved on your device and runs there: one main trigger (plus up to five more) and a tree of steps of seven kinds. Scheduled runs go through Android's WorkManager; while any run is alive PocketCode keeps a notification with a Stop button.

Ways to open it

Where you areWhat you tapWhat opens
The Tools sheet of the navigation barWorkflows, in the second row of cellsThe module, on its welcome screen
The side menuWorkflows, in the tools categoryThe module
HomeAny row of the Workflow runs widget (the widget only draws when there are runs)The module
A run notification, or the notice of a scheduled workflow that could not startTap itThe detail of that run, or the editor of that workflow
The activity panel of the AI chatA row for a workflow runThe module
Outside the appA link: pocketcode://workflows, pocketcode://workflows/run/<runId>, pocketcode://workflows/<workflowId> or pocketcode://workflows/import?url=<https address>The module, that run, that workflow, or the import sheet. A link only opens a screen: it never runs, deletes or downloads anything by itself

How the window behaves

  • The module is its own window, so you can't see the rest of the app while it is open. Back goes one level up: editor to list, run detail to the history or the tabs, secrets to the tabs, the tabs to the welcome screen, and the welcome screen closes the module.
  • On a wide window (840 dp wide and 480 dp tall or more, such as a tablet) the list stays on the left and the editor, history or run detail opens on the right. The step settings panel (360 dp wide) is only used when the editor keeps at least 400 dp beside it; otherwise step settings open as a sheet.
  • A workflow can also be started without opening the module: from a home screen shortcut, a Quick Settings tile or the system Share menu (see Running and watching).
Workflows welcome screen on a tablet in landscape: My Workflows, and under Explore the Templates and CI / CD cards
The welcome screen on a tablet held sideways: My Workflows, and under Explore the Templates and CI / CD cards. There is no Generate from prompt card in landscape.

You can't, and why

  • Open it from the command palette: the palette has no Workflows command, and Workflows is not a page of the pager either.By design

Screen map

One row per screen, sheet and dialog of the module, and where it comes from.

ScreenHow you get thereWhat you can do
Welcome screenOpening the module; Back from the tabsOpen My Workflows, Generate from prompt (portrait only), Templates or CI / CD (both open the Templates tab).
Header and tabsAlways on topSwitch between My Workflows, Templates and Activity. On the first tab only: Import a workflow from a file, Manage secrets and the + button (New workflow). The banner Scheduled workflows need attention shows above the tabs when something would hold scheduled runs back.
My Workflows tabFirst tabSearch, sort and filter by tag; switch a workflow on or off; run, stop, schedule, open its history, delete; open the long-press menu.
Tags dialogTags in a card's menuAdd or remove up to 8 tags on a workflow.
Templates tabSecond tab; the Templates and CI / CD cards of the welcome screenSearch the 17 templates, filter by family, open a preview, Activate or Add another copy.
Template previewTap a template cardRead Starts when, the steps, What it needs, and run a dry run (Test now) that touches nothing.
Activity tabThird tabSee the latest runs of every workflow; search in the errors; filter by status, date and workflow; stop a live run; open a run; copy the filtered runs as JSON; Delete history.
EditorTap a card, Edit in its menu, the + button, a notice of a scheduled workflow, Open in editorName it; declare Inputs; set Workflow settings and Permissions; choose triggers and filters; build the step tree; test; save.
Step settings (seven sheets)The pencil of a step, or Add stepConfigure an action, If / Else, Loop, In parallel, Try / on failure, Subflow or Wait. On an action, also Reliability and Conditional.
Add step paletteThe + button of the editor, or the + of a branchSearch the 15 actions and the six control-flow blocks by name, description or output; use favourites and recents.
Insert data pickerThe button of the same name in a parameterPick an input, a trigger field, an earlier step's output or status, or the item or error of the block you are in.
Problems panelInside the editor, above the stepsRead errors, warnings and tips and jump to the step with Go to step.
Convert to subflow dialogTurn into a subflow in a step's menuName the new workflow and move the step and its contents into it.
Run dialog (run inputs)Run now on a workflow with required inputs; Run with these inputs in a runFill the declared inputs (defaults already in) and press Run.
Run historyRun history on a card or in its menuSee one workflow's runs; Stop this run; open a run.
Run detailA run in the history or in Activity; a notification; a deep linkRead every step (result, duration, attempts, error, JSON output), follow the live shell log, Run again, Repeat from the failed step, Run with these inputs, Analyse with AI, Copy as JSON.
Repeat this run dialogRun again or Repeat from the failed stepRead what changed since that run before confirming.
Schedule sheet (Schedules for …)Schedule on a card or in its menuList and remove schedules; add presets or Custom cron; set Device conditions and If a run is missed.
SecretsManage secrets (key icon)Add, change the value of, or delete encrypted secrets; see which workflows use one before deleting it.
Share this workflow sheetShare as file in a card's menuCheck which secret fields are emptied and share the .pcwf.json file.
Import workflow sheetImport a workflow from a filePreview a file (trigger, steps, missing secrets, linter result) and save it switched off.
A link wants to import a workflowA pocketcode://workflows/import?url=… linkSee the address it comes from and choose Download or No thanks.
Generate workflow from prompt and Change … with AIGenerate from prompt on the welcome screen; Change with AI in a card's menuDescribe an automation or a change, review the result, Save & enable or Open in editor.
Irreversible-steps dialogsSwitching on a workflow with irreversible steps; saving one that is Available to AI agentRead the steps and decide: Enable anyway or Allow the AI.
Shortcut, tile and Send to a workflowThe home screen, Quick Settings and the Android Share menuStart a workflow without opening the module.
Run notificationThe notification shade while a run is aliveFollow Step n of m and press Stop.

The list, tags and templates

The module has three tabs, My Workflows, Templates and Activity (the last one is covered under Running and watching). Above the tabs, on My Workflows only, sit Import a workflow from a file, Manage secrets and the + button (New workflow), which opens the editor with an empty workflow that is switched off and has the Manual or scheduled trigger.

Welcome screen

The module always opens here. Back from the tabs returns here; Back from here closes the module.

You can

  • Tap My Workflows (Manage your active automations) to open the list.
  • Tap Generate from prompt to describe an automation in a sentence (see AI: generate, change and the chat). The card is only there in portrait.
  • Under Explore, tap Templates or CI / CD. Both open the same Templates tab: CI / CD doesn't filter anything.

You can't, and why

  • Create a blank workflow from here: use the + button on My Workflows.​By design
  • See Generate from prompt in landscape (a phone on its side, a tablet held sideways): the landscape welcome screen has only My Workflows, Templates and CI / CD. Change with AI in a card's menu still works.Not yet

My Workflows tab

One card per workflow, with its status, when it last ran, health dots and, if it is scheduled, the next run.

My Workflows on a tablet: tabs, the battery-optimisation banner and two workflow cards with their switches and icons
My Workflows on a tablet: the battery-optimisation banner, a workflow that starts on every push, and a manual one with its ▶, clock, history and bin icons. The two icons at the top right are Import a workflow from a file and Manage secrets.

You can

  • Search your workflows: it looks in the name, the description and the tags, ignoring accents.
  • Sort by Recently edited, By name, Last run or Problems first.
  • Filter by tag with the chips (All plus your tags, most used first).
  • Switch a workflow on or off with the switch on its card. Switching one on that has irreversible steps asks once (see Running and watching).
  • Tap the ▶ icon to run a workflow whose main trigger is Manual or scheduled; while it runs the icon becomes a ■ Stop with a progress ring, for any workflow, whatever started the run.
  • Use the clock icon (Schedule), the history icon (Run history) and the red bin (delete).
  • Delete a workflow with the red bin or with Delete in the card's menu. A dialog asks Delete “<name>”? (“The workflow and its schedules are removed. This cannot be undone.”) and removes it only when you tap Delete; Cancel leaves everything as it was.
  • Long-press a card, or use a secondary click, to open its menu.

You can't, and why

  • Have a ▶ on the card of a workflow that starts from an event or a shortcut: for those, Run now is in the card's menu.By design
  • Keep the search, the sort or the tag filter when you leave the screen: a filter hides things, so it is asked for again every time.By design
My Workflows on a phone with the three tabs, the battery-optimisation banner and cards for verify-hello, Tests then Deploy if they pass and Prettier on Save with their health dots
The same list on a phone: tabs, the banner, a workflow with its health dots and 100% success, one that has never run and one whose last runs failed (0% success).

What a card shows

PartWhat it tells you
StatusIdle, Running, Completed, Failed or Cancelled, and Last run: (or Never run).
HealthDots for the last 5 runs and the success rate (for example 100% success); No finished runs yet when there is none.
TriggerThe label of the main trigger, such as On git push or Manual or scheduled.
Next:The next scheduled run, if the workflow has a schedule.
Live progressStep n of m while it runs.

The card menu

ItemWhat it does
EditOpens the editor.
Change with AIOpens the change sheet (see AI: generate, change and the chat).
Activate / DeactivateThe same as the switch.
Run now / StopStarts a run of any workflow, whatever its trigger; with required inputs it asks for them first. While a run is going the item is Stop.
ScheduleOpens the schedule sheet.
Run historyOpens that workflow's runs.
DuplicateMakes a copy that is switched off, with new step ids and copy after its name.
Share as fileOpens the sheet that exports a .pcwf.json.
TagsOpens the tags dialog.
DeleteAsks Delete “<name>”? and, once you confirm, deletes the workflow and its schedules.

Tags

Tags group the list without moving anything. They live in the workflow's settings, so they travel in the exported file.

You can

  • Open Tags from a card's menu, type in New tag and add it; remove a tag from the same dialog.
  • Filter My Workflows by tag; the chips are ordered by how many workflows use them.

You can't, and why

  • Put more than 8 tags on a workflow (8 tags is the limit.): twenty tags organise nothing.By design

Templates tab

17 ready-made workflows, grouped by what starts them. Each card shows its name, a description, its trigger, the kinds of action it uses and What it needs: irreversible steps, terminal commands, a connected deploy provider, an AI provider with a key, the network, writing files, an open project.

You can

  • Search templates by name, description, trigger or action; filter by family with the chips (All and the six families below).
  • Tap Activate to get an editable copy with a new id that is switched on and appears in My Workflows; tap Add another copy if you already have it. The copy does not share anything with the template.
  • Open the preview, run a dry run, and edit the copy afterwards in the editor.

You can't, and why

  • Edit a template in the gallery: you edit your copy. The catalogue is fixed at 17 templates.By design
  • Be asked about irreversible steps when you press Activate: the question only appears when you move the switch of a workflow later. Read What it needs before you activate.Not yet
Template gallery with the When you edit and When you use git groups and an Activate button on each card
The template gallery grouped by when you would want them, here When you edit and When you use git. Each card has its trigger and Activate.

The six families

FamilyWhat it contains
When you edit3 templates, all of them starting from On file save. The family also holds anything that starts from a file being created, deleted or renamed, or changed by the AI.
When you use git5 templates: three start from On git push and two from On git commit.
Around a deploy1 template, which starts from Deploy completed. The family also covers Deploy failed.
When something breaks1 template, which starts from An error was detected. The family also covers a build or a run finishing.
From your phone1 template, which starts from Text shared to PocketCode. The family also covers the home screen shortcut, the Quick Settings tile and shared files.
On demand, or on a schedule6 templates that start with Manual or scheduled: you run them, or you add a schedule from the clock button.

The 17 templates

TemplateStarts whenWhat it does and what it needs
Prettier on SaveOn file save, for .js filesRuns prettier --write on the file you just saved, not on the whole project.
Auto-Commit on Kotlin SaveOn file save, for .kt filesCommits only the saved file, on the checked-out branch, and does not push. Saving with no real change is not a failure.
Lint the File You Just SavedOn file save, for .ts filesWaits two seconds, runs eslint on that file and notifies only if it finds something. Saving again while it waits cancels the pending run.
Tests, then Deploy if they passOn git pushRuns the test command, and asks for a deploy only when it exits with 0; otherwise it notifies and deploys nothing. Needs a deploy provider connected in the Backend Manager.
Auto-Deploy on Push to mainOn git push, filter mainDeploys after a push to main and notifies with the status and URL.
Tests after Push to mainOn git push, filter mainRuns the test suite after a push to main and notifies with its exit code (it cannot block the push).
Test on CommitOn git commitRuns the tests after a commit and notifies with the exit code and the message. It only fires for commits made from Projects.
Test Every Module You TouchedOn git commitA loop over the directories of the commit (up to 20) that runs the test command once per directory; a failing module does not stop the rest. Same limit as above: only commits made from Projects.
DB Backup after DeployDeploy completedRuns a pg_dump and reports the file; edit the command for your own database.
AI Analysis of a Failed WorkflowAn error was detectedSends the error to the AI and notifies with the answer. Needs an AI provider with a key. The card says it only sees workflow failures; today the trigger also hears editor build and run errors and failing terminal commands run by the AI.
Nightly BackupManual or scheduledDumps your database into a folder of the project and tells you only when it fails. Attach a schedule (for example Daily at 9:00) from the clock button: a schedule is not a trigger.
Test a Branch You PickManual or scheduledAsks for a branch (default main), checks it out in the open project and runs the tests. It changes your working tree: commit or stash first.
Release Notes from the Last CommitsManual or scheduledReads the last 20 commits, asks the AI for release notes and writes RELEASE_NOTES.md, overwriting it. Needs an AI provider.
Check an EndpointManual or scheduledA GET request and a notification with the status code and the time. The URL has a default, so it can run unattended once you set yours.
Check Three Endpoints at OnceManual or scheduledAsks for three URLs and calls them in parallel, waiting for all three. Open the run to see each status code.
Deploy, and Tell Me Even If It FailsManual or scheduledA Try / on failure around a deploy that notifies either way. Needs a deploy provider connected.
Save a Shared Link to links.mdText shared to PocketCodeAppends a page shared from any app to links.md in the open project, never overwriting it.

Template ids never change, so a workflow created from one keeps its link to its template.

Template preview

Tap a template card to see what it would do before you activate it.

You can

  • Read Starts when, the step tree with its branches (If it matches, Otherwise, Try this, If it fails) and What it needs.
  • Run a dry run with Test now. If the template has required inputs the defaults are filled in. The preview says which steps are skipped because they can't be simulated, or what is missing, and ends with n steps · n ms · not persisted.

You can't, and why

  • Dry-run a template that declares a required input with no default value: the preview says Cannot be tested without: and names the input. None of the 17 templates does today, and a missing deploy provider or AI key does not block the test.By design

The editor

Open the editor by tapping a card, Edit in its menu, or the + button for a new workflow. From top to bottom it holds the name and description, Inputs, Workflow settings (collapsed), Permissions (its own collapsed card), the Enabled and Available to AI agent switches, Trigger, and Steps with the step tree and the + button (Add step). The top bar has close, Undo, Redo, Test now and Save. Undo keeps the last 100 states and merges consecutive edits of the same kind made within 800 ms. Closing (the x or Back) saves when the workflow can be saved; if it has content that can't be saved yet it asks Discard changes? (Keep editing or Discard); with nothing written it just closes. Save is disabled while there is an error: an empty name, no steps, an empty required parameter or an invalid input.

Two panes on a tablet: the workflow list on the left and the Edit workflow screen on the right with Inputs, Workflow settings, Permissions, Enabled, Available to AI agent and Trigger
Two panes on a wide window: the list on the left and the editor on the right, with Workflow settings and Permissions as their own collapsed cards, then Enabled, Available to AI agent and Trigger.

Name, switches and AI exposure

Name and Description sit at the top. Enabled (when off, the workflow stays saved but doesn't run) and Available to AI agent (when on, the chat agent can invoke it as a tool) come after the settings, with Description shown to the AI: if you leave it empty the workflow description is used.

You can

  • Switch Enabled: it is the same switch as on the card.
  • Switch Available to AI agent and write Description shown to the AI. Saving with the switch on and irreversible steps in the workflow asks Let the AI run this workflow? once (Allow the AI).
  • Read the Security warning when a shell step contains a {{…}} binding in a workflow that is exposed to the AI: the chat agent could inject text into the command through the inputs.

You can't, and why

  • Have the agent call a workflow that is switched off: a workflow is announced to the chat only when it is both Available to AI agent and Enabled.​By design
The workflow editor on a phone: name, description, Inputs, Workflow settings, Permissions, and the Enabled and Available to AI agent switches
The editor on a phone: name, description, Inputs, Workflow settings, Permissions with its summary sentence, and the Enabled and Available to AI agent switches.

Inputs

Values the workflow asks for when it runs. You read them anywhere as {{var.<name>}}.

You can

  • Add input with a Name (letters, digits and _, not starting with a digit, unique), a Type (Text, Long text, Number, Yes / no, Choice, JSON), Required, a Default value, Options (comma-separated, for Choice), a Label and a Description (shown when it asks, and to the AI). Move inputs up or down, or remove them.
  • Run it with Run now: a workflow with required inputs opens the Run dialog with the defaults filled in, so you only change what you need.

You can't, and why

  • Save with an invalid input: a blank, invalid or duplicate name, a Choice without options, or a default that is not one of the options or not a number blocks Save.​By design
  • Start by itself a workflow whose required input has no default: a scheduled run, an event, a shortcut or a tile has nobody to ask. The editor warns with Required with no default and the scheduler records a failed run.By design

Workflow settings

A collapsible card (Show / Hide) with settings for the whole run.

You can

  • Cap for the whole run (seconds): empty is no cap. When it runs out the run is cancelled as if you had stopped it.
  • When a step fails: Stop or Continue. It is the default every step inherits. A step that says Continue keeps its own choice; but with the workflow on Continue, no step can ask for Stop again.
  • When a run is already going: Skip the new one (the default), Queue it (up to 10 waiting per workflow) or Cancel the one in flight. It applies to event triggers and scheduled runs; manual runs and runs started by the AI are not limited by it.
  • History kept: Runs kept and Days kept. Empty means the default (100 runs, 30 days); you can set 1 to 1000 runs and 1 to 365 days. Older runs are trimmed with the workflow's next run, not when you save.

You can't, and why

  • Keep a log of the events thrown away by Skip the new one: with the default policy, an event that arrives while the workflow is running is dropped without an entry in the history, on purpose: a burst of saves would otherwise write one row per event. (A run turned away by the queue or by the app-wide limit is recorded as cancelled, with the reason.)By design

Permissions

Its own collapsible card under Workflow settings, so the one decision that can make a step stop running is never hidden inside a drop-down. The summary sentence is visible even when the card is collapsed. Everything is allowed by default.

You can

  • Switch Go out to the network (HTTP requests, AI steps, deploys and git push or pull), Write files (writing, checking out and backups; reading is never affected) and Run terminal commands (also the command of a database backup step).
  • Add Domains it may reach: empty means any domain, github.com also covers api.github.com, and what you paste is cleaned (scheme, path and port are removed).
  • Rely on one rule for subflows: a subflow runs with the intersection of its own permissions and its parent's, and if the domain lists have nothing in common the network is closed.

You can't, and why

  • Use permissions as a security boundary: the summary ends with “This is not a sandbox: anyone who can edit the workflow can change these permissions.” They protect you from carelessness, not from a hostile author.By design
  • Make the domain list restrict an AI, deploy or git step: the list only covers HTTP request steps, and the summary says so.By design
  • Get protection against SSRF from the domain list: the host name is compared, not the address it resolves to, and an HTTP step can reach 127.0.0.1 or 10.x.​By design
Permissions card with a summary sentence saying the workflow can go out to the network, write files and run terminal commands, and that it is not a sandbox, above the Enabled and Available to AI agent switches
The Permissions card: one sentence says what the workflow may do and that it is not a sandbox. Below it, Enabled and Available to AI agent.

Triggers

A workflow has one MAIN trigger and up to six in total (Add trigger, Make it the main one). When two of them match the same event, one run starts and the main one wins. Pick the type in the dropdown: there are 25. Many carry data you read as {{trigger.<field>}}; the fields are listed in the tables.

You can

  • Choose any of the 25 types, add up to 6 triggers, and promote one to the main one.
  • Build a typed filter (below) so the workflow only starts for the events you care about.
  • Press Capture under Capture the next event: the editor listens for 60 seconds, shows the real data of the next event of that type, and keeps it as sample data for Insert data.
  • Filter On git push by branch (for example main): the four places that emit a push (Projects, twice, the editor's Git panel and the AI chat) send the branch that was checked out, so Auto-Deploy on Push to main and Tests after Push to main fire.

You can't, and why

  • Use Project closed and The AI finished its turn: they are in the dropdown but nothing in the app emits them, so a workflow that starts from them never fires. The linter warns (“Nothing in the app emits PROJECT_CLOSED yet, so this workflow will not fire.”) and Capture says “Nothing in the app emits this trigger yet, so waiting longer will not help.”Not yet
  • Start from a commit made in the Source Control panel of the editor or by the AI chat: On git commit only fires for a commit made from Projects.​Not yet
  • Filter the four system triggers (Home screen shortcut, Quick settings tile, Text shared to PocketCode, File shared to PocketCode): Android launches them and the launcher only chooses workflows by type, so a filter is ignored.Not yet
  • Read a real exit code from Command finished when the command was typed in the interactive terminal: that event comes with exitCodeKnown set to false.Not yet
  • Add a seventh trigger or a ninth condition (6 triggers is as many as fit. and 8 conditions is as many as fit.).​By design
Trigger type dropdown listing On git push, On git commit, On file save, Deploy completed, Deploy failed, An error was detected, App opened and Command finished, over a saved text filter
The trigger type dropdown, and a workflow saved with the old free-text filter (.js) with Turn it into a condition.
Trigger section with On git push, the message No condition: this trigger fires with every event of its type, Add condition and Capture the next event
A trigger with no condition says so in words, and Capture the next event (the Capture button) listens for a real one.

The 25 triggers

Git (2)

On git pushAfter a push from Projects, the editor's Git panel or the AI chat. Fields: projectId, projectName, branch (the branch that was pushed, for example main).
On git commitAfter a commit made from Projects. Fields: projectId, projectName, message, branch.

Files (4)

On file saveFields: filePath, language, linesChanged.
File createdFields: filePath, fileName.
File deletedFields: filePath, fileName.
File renamedFields: filePath, previousPath.

Projects and builds (5)

Project openedWhen you select a project. Fields: projectId, projectName.
Project closedListed, but nothing emits it: it never fires.
Build finishedFields: status, exitCode, durationMs, output.
Run finishedFields: filePath, runtime, exitCode, output.
Command finishedFields: command, exitCode, output, exitCodeKnown.

Deploys, data and tools (5)

Deploy completedFields: provider, projectName, status, url.
Deploy failedFields: provider, projectName, error.
Query executedFields: data, format, rowCount, columns.
API tester responseFields: url, method, status, durationMs.
Design exportedFields: designId, designName, format.

Errors and the AI (3)

An error was detectedHears the failure of another workflow, build and run errors of the editor, and terminal commands run by the AI that exit with a code other than 0. A workflow never triggers itself. Fields: source, message, filePath, exitCode, workflowId, workflowName, error.
The AI changed a fileA file written by the AI agent. It is separate from On file save on purpose: an automatic write must not fire the automations you built for your own work. Fields: filePath, fileName.
The AI finished its turnListed, but nothing emits it: it never fires.

The app and manual (2)

App openedWhen the app comes to the foreground. Field: sessionId.
Manual or scheduledNo data. It is what you start with ▶ or Run now, what a schedule starts, and what the AI chat runs.

From Android (4)

Home screen shortcutNo data. See Running and watching.
Quick settings tileNo data.
Text shared to PocketCodeFields: text, subject.
File shared to PocketCodeFields: uri, fileName, mimeType.

The typed filter

Under a trigger, Add condition (up to 8) gives a Field (the fields of that trigger), a Comparison and a Value. Join them with All or Any, and put Not on any of them. With no condition the editor says “No condition: this trigger fires with every event of its type.” Changing the type drops the conditions whose field doesn't exist in the new type and tells you. A workflow saved with the old free-text filter keeps it as Text filter, still working, with Turn it into a condition.

ComparisonWhat it does
isThe field equals the value.
containsThe field contains the value.
starts with / ends withThe field starts or ends with the value.
matches pathA glob for path fields: one * stays inside a folder, two cross folders, and a leading dot matches the extension.
is one ofThe field is one of several values separated by commas.
is emptyThe field has no value.
is greater than / is less thanNumeric comparison. If either side is not a number the condition does not match.

Steps: the tree, the card and the palette

The Steps list is a tree: blocks nest inside blocks. Steps are numbered 2, 2.1; an else branch reads 2.e1, a catch branch 2.c1 and a parallel branch 2.<n>. Blocks can be collapsed (Collapse / Expand), and a step nested very deep gets a notice such as 5 levels deep saying it still runs the same but stops fitting on a phone screen.

You can

  • Tap the + button (Add step) to open the palette: search by name, description or output (“Name, description or output (stdout, url…)”), pick a category chip (Shell, Git, Deploy, AI, Data, HTTP, Files, Control, Notify, Other), and use favourites and the last 5 recents. Each entry shows what it gives (Gives: …) and marks irreversible, runs commands, network, writes files or Cannot be simulated. The new step lands at the end of the slot you chose and its settings open.
  • On each card: the reorder handle, the number, the title and a one-line summary, an On / Off switch (an Off step is skipped and does not count as a failure), the If this step fails chip, Test this step, the pencil (opens the settings and selects the step) and the ⋮ menu.
  • In the menu: Move up, Move down, Copy step, Paste below (only active when the clipboard holds PocketCode steps, so you can paste into another workflow), Duplicate, Note (it only shows in the editor), Turn into a subflow and Delete.
  • Spot pinned data: the card of a step with a pinned output shows sample data.

You can't, and why

  • Drag a step into another block: the handle moves a step one position for every 48 dp of drag inside its own list; use Move up and Move down from the menu.By design
  • Draw the flow as a graph, or use an N-way switch or a free merge: the flow is a nested tree, If / Else has exactly two branches and In parallel joins its branches with one of three policies.By design
  • Edit a step the app doesn't know (Unknown step, written by a newer version): it is kept as it is and can only be moved or deleted.By design
Add step sheet with a search box, category chips and the Run terminal command and Git operation entries showing what they give back
Add step: search by name, description or output, category chips and what each action gives. The hint under Git operation is older than the action: it handles seven operations, not three.
Step tree with an If step, steps 2.1 and 2.2 under If it matches and 2.e1 under Otherwise
A branch from the Tests, then Deploy if they pass template: 2.1 and 2.2 under If it matches, 2.e1 under Otherwise. Deploy offers Run this step for real because it cannot be simulated.

The seven kinds of step

KindWhat it doesWhat you set
ActionRuns one of the 15 actions.The action's parameters. Only on an action: Reliability (retry, timeout) and Conditional (When).
If / ElseRuns If it matches when the condition is true and Otherwise when it is not.A condition tree with AND, OR and NOT.
LoopRepeats its steps For each item of a list.List to go through, Name for each item (read it as {{item.<name>}}), Most iterations (default 100, never more than 10 000) and Iterations at once (1 runs them one after another, up to 16).
In parallelRuns several branches at the same time.Branches (add one, or remove one that is empty) and When do we move on: When they all finish, With the first one to finish or With the first one that works. The last two cancel the branches that lose, mid-way and with their side effects.
Try / on failureRuns Try this; if anything in it fails, runs If it fails.Name for the error (default error, read as {{var.error}}, up to 4 096 characters).
SubflowRuns another workflow with the values you give it and uses its last result.Workflow to run and Values for the subflow. Up to 5 levels deep, no recursion, and permissions are the intersection with the parent's.
WaitPauses the workflow for a time, or until something happens.A time in milliseconds, or Wait for something to happen with Event to wait for, an optional filter (same rule as a trigger) and Cap in milliseconds (5 minutes if you set none).

Actions

Fifteen actions, in eight palette categories. Each one lists the outputs you can read as {{step.<id>.output.<key>}}; the names below are the keys. The labels are the English ones the palette shows.

Shell (1)

Run terminal commandRuns a command in the terminal's shell. Parameters: command, cwd, env, failOnNonZero (on by default), timeoutMs. Outputs: command, exitCode (-1 if the cap killed it), stdout, stderr (each limited to 64 KB, head and tail), durationMs, timedOut.

Git (1)

Git operationSeven operations: status, commit, push, pull, checkout, log, diff. Parameters: operation, message, branch (letters, digits, ., _, /, -), n (default 20), path, projectPath. Outputs: sha, branch, changedFiles, ahead, behind, text. Only push (or an operation that comes from a binding) counts as irreversible; commit, pull and checkout write files; status, log and diff touch nothing. diff is per file.

Deploy (1)

Trigger deployTriggers a deploy on render, netlify, digitalocean or railway and waits for the provider's verdict (15 minutes by default, 1 to 60). Parameters: provider, project, timeoutMs; branch and env are recorded but not honoured. Outputs: status, url, provider, projectName, logsTail, durationMs, timedOut. It cannot be simulated: Test now skips it and the step test offers Run this step for real. On Free it fails with “Upgrade required to trigger another active deploy” when a deploy of that project is already in flight (queued, building or deploying), and you see a notice that the action needs PocketCode Pro.

AI (2)

Ask AI to analyzeSends a prompt, with optional context, to your active AI provider. Parameters: prompt, context, outputFormat (TEXT or JSON), schema. Outputs: text, json (only in JSON mode) and tokensEst, a local estimate of the tokens, not the provider's count.
Ask AI to generateThe same, framed as code generation. Parameters: prompt, context, language. Outputs: text, tokensEst. It does not write files; use Write file with its text.

Data (4)

Query databaseRuns SQL against a named connection: neon, supabase, turso, upstash or cloudflare (D1), or one of your saved PostgreSQL connections (by name or id). Parameters: connection, sql, maxRows (200 by default, 5 000 at most), allowWrites. Outputs: rows, rowCount, columns, truncated, durationMs, message, writes. A query with write verbs (DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT), or SQL that comes from a binding, counts as irreversible and fails unless allowWrites is on. The palette hint calls it read-only; it is not.
Backup databaseRuns your own backup command (for example pg_dump); with no command it can only copy PocketCode's internal database. Parameters: connection, command, outputDir, timeoutMs (10 minutes). Outputs: filePath, sizeBytes, tables, exitCode, stdout, stderr, timedOut, durationMs.
Set variableParameters: name, value. Outputs: name, value. It writes {{var.<name>}} for the steps that follow (the value can also be read as {{step.<id>.output.value}}). A dry run (Test now) does not write the variable.
Transform valueEvaluates an expression with the filters and returns value. No side effects, and a dry run does the same as a real run.

HTTP (1)

HTTP requestParameters: method, url, headers (JSON), authorization (a secret), body, contentType, timeoutMs (1 000 to 120 000, 30 000 by default), followRedirects. Outputs: status, headers, body (up to 128 KiB), json, durationMs, bodyTruncated, finalUrl, redirects. Only http and https; up to 5 redirects, and credentials never cross to another origin.

Files (4)

Read fileParameter: path. Outputs: content (up to 128 KiB), sizeBytes, exists, contentTruncated, filePath.
Write fileParameters: path, content, append. Outputs: filePath, sizeBytes, bytesWritten, overwritten. It is never counted as irreversible, not even when it overwrites.
File existsParameter: path. Outputs: exists, isDirectory, sizeBytes, filePath.
Open file in editorParameters: file, line. Outputs: opened (true only if the editor confirms within 1.5 seconds, so it is false with the app in the background), file, line.

Notify (1)

Show notificationParameters: title, message, deepLink (only pocketcode://workflows/…), importance (LOW, DEFAULT, HIGH). Only HIGH uses the Workflows · alerts channel; the rest go to the silent Workflows channel. Outputs: notificationId, delivered (it means the event left for the notification system, not that you saw it; false in a dry run), deepLink, importance.
  • The three file actions that read or write (Read file, Write file, File exists) are confined to the root of the project; Run terminal command and Git operation are not.
  • In the palette, irreversible marks the worst case of the type; the confirmation dialog, the step test and the Problems panel look at the values you actually typed.

You can't, and why

  • Deploy to any provider: only render, netlify, digitalocean and railway have a call that triggers a deploy, and the branch and environment are not honoured.Third party
  • Query a saved connection that is not a remote PostgreSQL one (the embedded local database, MySQL and the rest): from a workflow you can only reach neon, supabase, turso, upstash, cloudflare (D1) and your saved PostgreSQL connections.Third party
  • Back up any database without a command: with no command the step can only copy PocketCode's internal database.Not yet

Conditions: If / Else and When

An If / Else step holds a condition tree and two branches. A step of kind Action can also carry When (expression), under Conditional: the step is skipped when the expression resolves to empty, false, 0 or null. When exists only on action steps.

You can

  • Build the condition with Add condition and Add group, combine with AND, OR and NOT, and use Group it and Remove. An empty group always matches.
  • See It matches or It does not match, evaluated with your pinned sample data, not with the next run.

You can't, and why

  • Put When on a loop, a parallel, a try, a subflow, a wait or an If / Else: only an action step has it.By design
OperatorTrue when
equals / is notThe two values are equal, or not.
greater than / less thanNumeric comparison.
greater or equal / less or equalNumeric comparison, inclusive.
contains / starts with / ends withText comparison.
matchesA regular expression (keep it short).
is one ofThe value is one of several separated by commas.
is null / is empty / is trueChecks the value itself.
alwaysAlways true.

Variables and expressions

Any parameter takes a literal or an expression between double braces: {{ root.field[0] | filter:"arg" | filter }}. Insert data opens a picker (Inputs, Trigger, Earlier steps, Step status, and the item or the error of the block you are in), so you never type a step id by hand; it warns Inside a branch: it may not have run and “Inside a loop: only the last iteration is left”. A reference that doesn't resolve gives an empty string. \{{ writes a literal {{. Filter arguments always go in double quotes: replace:a:b is a syntax error, replace:"a":"b" works.

You can

  • Chain filters with | after any reference.
  • Pin an output as sample data, so Insert data and If / Else can preview with it.

You can't, and why

  • Add your own functions or run code in an expression: the list of 13 filters is closed, with no user functions and no eval; very long paths, filter chains or text between braces are rejected when parsed.By design
ExpressionResolves to
{{var.<name>}}A declared input (including the values of Run with these inputs and the defaults of a schedule or shortcut), the error name of a Try / on failure, the values a Subflow passes to its child, and the value a Set variable step writes (a dry run does not write it).
{{step.<id>.status}}SUCCESS, FAILURE, SKIPPED, TIMED_OUT, or RUNNING for a step still going.
{{step.<id>.output}}The output map of the step, or one field of it: {{step.<id>.output.json.items[0].name}} walks into JSON with [n].
{{step.<id>.error}}The error message of a step that failed.
{{item.<alias>}}The current item of a Loop (the bare alias works too).
{{trigger.<field>}}The data of the event that started the run; {{trigger.type}} tells which of the workflow's triggers it was (MANUAL when there was no event).
{{secret.<NAME>}}A saved secret. It is terminal: you can't walk inside it.

The 13 filters

FilterWhat it does
linesSplits text into lines; one trailing newline is dropped.
first / lastThe first or last item of a list, or the first or last character of text. It fails on empty.
trim / upper / lowerTrims spaces, upper-cases, lower-cases.
lengthThe number of items of a list or characters of text.
jsonRenders the value as JSON.
default:"x"A fallback when the value is missing or empty.
split:","Splits text on a separator into a list.
join:","Joins a list with a separator.
date:"HH:mm"Formats a date from epoch milliseconds or an ISO date, in the device's time zone.
replace:"a":"b"Replaces text; the text to replace can't be empty.

Examples

{{step.<id>.output.stdout | lines | first | trim}}The first line of a command's output, trimmed.
{{step.<id>.output.json.items[0].name | default:"none"}}A field inside a JSON response, with a fallback.
{{trigger.filePath | replace:"src/":""}}The saved file's path without a prefix.

Loops, parallel, try / on failure and subflows

The blocks of the tree, with the limits that matter in practice.

You can

  • Loop: up to 10 000 iterations (default 100) and up to 16 at once; with Iterations at once above 1 they run in batches.
  • In parallel: When they all finish waits for every branch and fails if one fails; With the first one to finish and With the first one that works cancel the others.
  • Try / on failure: the failure branch reads the message in {{var.<name>}}; the failure still shows in the history.
  • Subflow: build the part once and call it from several workflows; Turn into a subflow extracts a step and everything inside it into a new workflow that is switched off, and leaves a subflow step in its place, listing the references that will break (They will resolve to nothing, quietly.).

You can't, and why

  • Nest subflows more than 5 levels or let a workflow call itself: a recursive subflow is skipped and the linter warns.By design
  • Loop more than 10 000 times or run more than 16 iterations at once, whatever the field says.By design

Retry, timeout and failure

Open the settings of an action step and expand Reliability. These fields exist on action steps only.

You can

  • Set Max attempts (1 means no retry), Wait between retries (a text field: EXPONENTIAL, LINEAR or FIXED), Initial delay (ms), Max delay (ms) and Timeout (ms) (empty means no cap).
  • Rely on timeouts being retried: a step that times out is marked TIMED_OUT and, if attempts remain, it runs again like any other failure.
  • Choose If this step fails: Stop (the run ends here), Continue (it goes on and the failure stays in the history) or Use the workflow setting. With Continue the step stays red and the run can still end green.
  • Read the result in the run detail: succeeded on attempt n, or n attempts if it never did.

You can't, and why

  • Set a retry or a timeout on a loop, a parallel or any other control block: the fields exist on action steps only. The workflow-wide cap is in Workflow settings.​By design

Test a step, pin data, test the workflow

You can try things without running the whole workflow.

You can

  • Tap Test this step: it simulates the step with your pinned data as context and says Simulated in n ms: nothing was touched. It warns No pinned output for: … when a reference points at a step with nothing pinned.
  • When the action can't be simulated (today only Trigger deploy), or the values you typed would be irreversible, the button is Run this step for real. It asks first: only that step runs, the rest of the workflow is untouched and the run is not saved to history.
  • Pin a step's output (and Unpin it) as sample data for the picker and the previews. Pinned outputs live on the device, up to 50 steps per workflow, and are dropped after 14 days.
  • Tap Test now (or press Ctrl+Enter) to dry-run the whole workflow as it is on the screen, not as it was last saved. It shows Test passed or Test failed and n steps · n ms · not persisted. A dry run saves no run and fires no events.

You can't, and why

  • Test a control-flow block on its own: “Only action steps can be tested on their own: testing a branch or a loop means running what is inside it.”By design
  • Use secrets in a dry run: they are not resolved, and the step is skipped telling you which ones it uses.By design
  • Export or sync pinned outputs: they stay on the device.By design

Problems

The linter runs while you edit and lists Errors, Warnings and Tips with a count for each. Every row names the rule, the step (Step: … or Whole workflow) and has Go to step. When there is nothing it says Nothing to fix. The same linter checks what the AI generates and what you import.

You can

  • Fix what a warning points at, or leave it: only the three rules that are errors block Save.
  • Jump straight to the step with Go to step.

You can't, and why

  • Save with an error (an empty name, no steps, a required parameter left empty): the three error rules are the ones that would leave the workflow unreadable or unsaveable. Everything else, permission rules included, warns and does not block, because someone who closes the network usually does it before removing the step that used it.By design
Problems panel with one warning about an unquoted binding and Go to step, above a step card with On, default: Stop and Test this step
The Problems panel above a step: a warning about a binding that goes into the command unquoted, with Go to step. The card shows On, default: Stop and Test this step.

The 34 rules

GroupRules
Structure (6)Error: the workflow has no name; it has no steps. Warning: an empty branch; a step that can never run. Tip: a parallel with one branch; nesting too deep.
Parameters (3)Error: a required parameter is empty. Warning: a parameter the action doesn't have; an action type no installed host serves.
References (7)All warnings: a reference that will never resolve; one that reads a step that runs later; an output the step doesn't return; a trigger field the trigger doesn't carry; an undeclared variable; a reference to a switched-off step; a reference that goes into a shell command unquoted.
Triggers (3)Warning: a trigger nothing emits; a filter on a field the trigger doesn't carry. Tip: the same trigger twice with the same filter.
Loops (3)All warnings: no list to go through; an alias already taken; no alias.
Reliability (2)Warnings: an absurd timeout; an absurd retry.
Security (2)Warnings: a secret typed in plain text; an irreversible step in a workflow that only runs on its own.
Permissions (4)Warnings: a step that goes to the network, writes files or runs a command while that permission is off; a step that goes to a domain not in the list.
Coherence (4)Warnings: exposed to the AI with no description; a required input with no default on an event trigger; a recursive subflow; a subflow that points to nothing.

Running and watching

Every run is written to the history when it ends: each step's result, how long it took, how many attempts it needed and its error. How much is kept is set per workflow in Workflow settings: 1 to 1 000 runs and 1 to 365 days (the defaults are 100 runs and 30 days). Anything that starts a run can also stop it.

Starting and stopping a run

A run starts from a trigger, from ▶ or Run now, from a schedule, from the AI chat, or from a shortcut, the tile or the Share menu. Across all workflows the app runs up to 8 runs at a time and keeps up to 16 waiting for up to 120 seconds; beyond that the run is recorded as cancelled with the reason “the app was already running too many workflows at once”.

You can

  • Tap ▶ on the card of a workflow whose main trigger is Manual or scheduled, or Run now in the menu of any workflow. If it declares required inputs, the Run dialog opens first (“This workflow needs these values before it can run.”) with the defaults filled in.
  • Stop it from the card, the menu, the history, Activity, the run detail or the notification. The run ends as Cancelled.
  • Switch on a workflow that has irreversible steps: a dialog titled “This workflow does something irreversible” lists them (Step n · …) and you choose Enable anyway. It is asked once per workflow and remembered on the device, not synced and not exported.
  • Save a workflow with Available to AI agent on and irreversible steps: Let the AI run this workflow? (Allow the AI), also once. Without that permission the agent's tool refuses to run it and tells the model who to ask.

You can't, and why

  • Be asked about irreversible steps when you press Activate on a template, use Save & enable in the generator, or import a file (an import arrives switched off, and the question comes when you switch it on).Not yet
  • Be warned about overwriting a file: Write file is never counted as irreversible, not even when it overwrites; its overwritten output tells you afterwards. Only a Git push (or a Git operation that comes from a binding) and SQL with write verbs (or SQL that comes from a binding) count.By design

Activity tab

The latest runs of every workflow, live ones first, 50 at a time.

You can

  • Search in the errors: it looks in the run's message and in the message of every step.
  • Filter by status (Completed, Failed, Cancelled), by date (Any date, Today, Last 7 days, Last 30 days) and by workflow (Every workflow, including workflows you have already deleted); Clear removes the filters.
  • Load more adds 50 more, stop a live run, and tap a run to open its detail.
  • Copy the filtered runs as JSON with Export as JSON: it puts the text on the clipboard.
  • Delete history after a confirmation (“The runs disappear. The workflows stay as they are.”), for every workflow or only for the filtered one.

You can't, and why

  • Go back further than the 500 most recent runs: “That is as far back as this screen goes. Narrow the filter to find something older.”By design
  • Export the history to a file: Export as JSON only copies the text.Not yet

Run history of one workflow

Run history on a card lists that workflow's runs, newest first.

You can

  • See each run's status and time, its number of steps, Triggered by … and, for a cancelled one, Cancelled by …; a run still going carries In flight.
  • Stop this run, or open a run for its detail.
  • With nothing yet it says “No runs yet — trigger this workflow to start a history.”

You can't, and why

  • Read every cancellation reason in words: the app translates the previous run was still going, the queue was full and “the app was already running too many workflows at once”; the other reasons (user, timeout, superseded, scope) are shown as the raw word.Not yet

Run detail

Open a run from the history, Activity, a run notification or a deep link.

You can

  • Read the header (status, duration, trigger, who cut it) and every step: result, duration, succeeded on attempt n or n attempts, the error and the output as a JSON tree you can expand and copy. A step that was still running when the run ended says Interrupted; a step removed from the workflow since says This step is no longer in the workflow.
  • Follow Live output of the shell while the run is going, search it (Search the log) and copy it (Copy the log). Only the last 500 lines of each step are kept, and the screen says so when older lines were dropped.
  • Analyse the whole run with AI, or Analyse with AI on one step: it opens the chat with a prompt already written.
  • Copy as JSON copies the run.

You can't, and why

  • Read the shell log of a run that has finished: “The shell log is not kept in the history: it is only visible while the run is going.”By design
  • Find a run that was in flight when the system killed the app: a run is written once, when it ends, and nothing is recovered at start-up, so an interrupted run leaves no row.By design
  • See a stored secret: values are masked as ••• when the run is written, so they are not in the database either. Values shorter than 4 characters can't be masked.By design

Run again, repeat from the failed step, run with inputs

Three buttons at the bottom of the detail, all ending in the Repeat this run dialog.

You can

  • Run again runs the workflow from the start.
  • Repeat from the failed step runs again from the first step that failed, reusing the results of the steps before it (n earlier results are reused.). It shows only when the run ended and has a failed step.
  • Run with these inputs asks for the inputs again before it runs.
  • Read the dialog before you confirm: it says “It runs the workflow as it is now, not as it was when this run happened.”, whether the workflow was edited since, which steps no longer exist, which were added and where it resumes.

You can't, and why

  • Reuse the inputs of the old run: “The inputs of that run are not saved, so the declared defaults are used.” They could be tokens.By design
  • Resume from a step nested inside a block: only a first-level step can be the restart point.By design
  • Repeat a run whose workflow you deleted: “The workflow no longer exists: this run cannot be repeated.”By design

Run notifications

A run that is alive shows a persistent notification with Step n of m and a Stop button. While runs are going PocketCode keeps a foreground service of the special use type, so Android does not stop the app halfway.

You can

  • Follow a run from the notification shade and stop it from there; the stop button only reaches live runs of this app.
  • Send your own notification with a Show notification step. Its importance decides the channel: HIGH goes to Workflows · alerts, anything else to the silent Workflows channel. Both follow the app's notification settings: the global switch, the alerts and notices switches, Android's notification permission and quiet hours.
  • Tap a notification: a link to pocketcode://workflows/… opens the run or the workflow; any other link is dropped and the notification just opens the app.

You can't, and why

  • Get an automatic notification when a run fails: PocketCode sends none. If you want one, add a Show notification step in a Try / on failure branch, or build a workflow that starts from An error was detected. (The AI chat can show a notice Workflow '…' failed with a Try it button, but only inside the chat.)Not yet
  • Have a progress notification for every run: only the first 5 simultaneous runs get one; the rest run without it.Device
  • Count on the foreground service when the app is in the background: from Android 12 the system may refuse it (for example for a scheduled run with the phone in your pocket). The run goes on, without that protection, and PocketCode asks again every 30 seconds.Google Play

Shortcut, Quick Settings tile and Share

Three ways to start a workflow without opening the module. Each one needs the matching trigger in the workflow (Home screen shortcut, Quick settings tile, Text shared to PocketCode or File shared to PocketCode), and the workflow switched on.

You can

  • Shortcut: every switched-on workflow with the shortcut trigger appears as a dynamic shortcut of the app icon (the label is cut to 30 characters). Tapping it runs the workflow without opening anything and shows Workflow started. A pinned shortcut of a workflow that was deleted or switched off says so.
  • Tile: drag Run a workflow into Quick Settings. With no workflow using it, it says No workflow uses this tile; with one, it runs it; with several, it shows a picker.
  • Share: share text, an image, JSON, XML, a zip, a PDF or a generic binary file to Run a workflow from another app. A sheet titled Send to a workflow always shows what was received (“What was shared is data, not an instruction.”) and which workflow gets it; with several you pick one. The data arrives as {{trigger.text}}, {{trigger.subject}}, {{trigger.uri}}, {{trigger.fileName}}, {{trigger.mimeType}}, and a declared input with the same name wins.
  • If nothing listens you read “No active workflow is listening for this. Add the matching trigger in the workflow editor.”

You can't, and why

  • Launch a workflow whose required input has no default from these three: it says … needs a value first instead of running blind.By design
  • Share several items at once, text longer than 32 768 characters (it is cut and you are told), or a file over 25 MB. A shared file is copied into PocketCode and deleted after 24 hours; the list of accepted types is fixed, not any type.By design
  • Count on the number of shortcuts: Android decides how many a launcher shows (at least 5, usually 4 or 5), and the tile is opt-in, you have to drag it in yourself.Device
  • Open a .pcwf.json from another app directly: the Share menu sends the file to the File shared to PocketCode trigger, not to the importer. Import with Import a workflow from a file.​By design

Scheduling

Any workflow can carry several schedules, set from the clock icon or Schedule in its menu (Schedules for …). They run through Android's WorkManager, with the slack that implies, and are armed again when the app starts.

You can

  • Read the existing schedules (Every n min or Cron: …, Next: …, their conditions, a notice if the interval is raised, Recovers one missed run) and Remove any.
  • Add one with a preset or with Custom cron: five fields, min hour day month weekday, for example 0 9 * * 1. The sheet shows Next fire: … or Invalid cron expression, and Add cron saves it. Cron accepts *, numbers, lists, ranges, */n, names (SUN–SAT, JAN–DEC), and ranges that wrap around the end only in month and weekday; the weekday goes from 0 to 6, with 7 meaning Sunday.
  • Choose Device conditions before you create it: No requirement, Any connection or Wi-Fi only, plus Only while charging, Not on low battery and Only while the device is idle. A condition delays the run, it does not cancel it: when the condition is finally met the pending run goes ahead, even hours later.
  • Turn on Run it once when the device comes back under If a run is missed: a run that fell while the device was off runs once at the next start of the app (with a tolerance of 15 minutes), however many were missed. It is off by default, so the missed run is skipped.
  • Rely on the change of hour: the hour that doesn't exist in spring fires at the jump, and the hour that happens twice in autumn fires once (a fine-grained cron loses the second pass of that hour).
  • Count on retries: a scheduled run that fails is tried up to 4 times in total (the first run plus 3 retries) with WorkManager's exponential back-off. If a run is still going when the next one is due, the concurrency policy decides; with Skip the new one the run is recorded as cancelled, the previous run was still going.
  • Read the banner Scheduled workflows need attention above the tabs: it appears when PocketCode's notifications are off, when the Workflows · alerts channel is blocked, or when the app is subject to battery optimisation (“Android may delay scheduled runs. It does not cancel them, they go out later.”). It has Open settings and no dismiss button; it goes away when the cause does.

You can't, and why

  • Get a guarantee under 15 minutes: Android does not run scheduled work more often than every 15 minutes. An interval below that is raised to 15 and the sheet says so (“Asks for every n min, but it runs every 15 min: that is the floor Android allows.”); a cron below it gets “Android does not guarantee that rate in the background”. PocketCode asks for neither the exact-alarm permission nor an exemption from battery optimisation.Google Play
  • Type an interval of your own: only three intervals are offered as presets (every 15 minutes, every hour, every 6 hours); any other rhythm is a cron expression. An interval can't be longer than about 30 days.By design
  • Choose a time zone: there is no selector, and a new schedule reads its cron in the device's zone (each schedule stores a zone, but the screen doesn't expose it).Not yet
  • Edit a schedule or its conditions: remove it and add another.By design
  • Use ?, L, #, a step over a range (1-9/2) or a year field in a cron expression. A cron that never fires (for example the 31st of February) switches the schedule off.By design
  • Be told by the banner about manufacturer battery killers: it only says what Android answers (notifications off, channel blocked, battery optimisation).Device

The presets

PresetWhat it adds
Every 15 minutesAn interval of 15 minutes, the Android floor.
Every hourAn interval of 60 minutes.
Every 6 hoursAn interval of 6 hours.
Daily at 9:00The cron 0 9 * * *.
Mondays at 9:00The cron 0 9 * * 1.

Secrets

Manage secrets (the key icon of the list) is a list of names with no values. You reference one as {{secret.NAME}} in any parameter, so a token never has to be typed into a workflow, where it would be saved as is, travel when you export it and show up in the run history.

You can

  • Add a secret: a Name in capital letters, digits and underscore (if the name can't be used in an expression the screen suggests one, Use …), and a Value. It is the name the steps use, so changing it later breaks them.
  • Change value: workflows that use it pick up the new value on their next run.
  • Delete: a dialog lists the workflows that reference it and warns that the value can't be recovered and that a workflow that loses its secret doesn't fail when saved, it fails on its next run sending an empty value.
  • Read “Stored encrypted on this device, one set per account. Values are never shown again, not even here.”

You can't, and why

  • See a value again after you save it, or save an empty one (“An empty value is not saved. To remove a secret, delete it.”).By design
  • Have a value masked in the run history when it is shorter than 4 characters: it is saved, but the screen warns “Careful: this value is shorter than 4 characters, so it will NOT be masked” and a step that prints it leaves it readable there.By design
  • Open the store after you restore the phone or change the screen lock: “The encrypted store could not be opened on this device… Nothing has been deleted. This usually happens after restoring the phone or changing the screen lock.”Device
  • Sync secrets between devices: they are removed from what is uploaded, and they don't travel in an exported file either.By design

Export, import and links

A workflow travels as a .pcwf.json file. Exporting and importing are free on purpose, and the code says why: they are the only way to take your work out of the app, and a way of getting your data out locked behind a subscription would turn a plan into a lock.

You can

  • Share as file (in a card's menu) opens Share this workflow: the file name, which secret fields are emptied (Your secrets stay on this device), and the reminder that run history, pinned outputs and the on/off switch don't travel. Share opens Android's app picker.
  • Import a workflow from a file (the top button of the list) opens the system file picker. The Import workflow sheet shows the name, Runs when, up to 40 steps, You will have to fill these in for the secrets, and the linter result; Save is blocked if there is an error. “It will be saved switched off. Read it before you turn it on: a workflow can run commands on your device.”
  • Open a link pocketcode://workflows/import?url=https://… from another app: A link wants to import a workflow shows the address (From: …) and a warning, and nothing is downloaded until you press Download (or No thanks).

You can't, and why

  • Open a .pcwf.json from a file manager or another app directly: the app has no file filter for it. Use Import a workflow from a file or the link.By design
  • Import a file bigger than 512 KB, a file that isn't a PocketCode workflow, a damaged one, or one written by a newer version of PocketCode: each gets its own message.By design
  • Use a link that isn't https, is longer than 2 048 characters, has credentials in the address or points at the device itself; a redirect is shown and not followed.By design
  • Share a file without checking it: only parameters declared as secrets are emptied; HTTP headers and commands travel exactly as you typed them, so check the file before you share it if a field holds a key or a token.By design

What is in the file

LeavesThe name, description, triggers, steps, inputs and the run settings (permissions and tags included).
Does not leaveThe id, the dates, the last run's state, the template it came from, the on/off switch, Available to AI agent, pinned outputs, the history and the schedules.
SecretsParameters declared as secrets are emptied and listed. A {{secret.NAME}} reference does travel: it is a name, not the secret.
ArrivesSwitched off and with a new id, after the linter has run. A new action from a newer build is dropped alone; a file with a newer format is rejected whole.

AI: generate, change and the chat

The AI touches workflows in three places: the generator and the change sheet in this module (free), the chat agent that can read, run and, with Pro, write them, and the Analyse with AI buttons of a run.

Generate from prompt and Change with AI

Both live in the module and neither has a plan check. The model is the AI provider you configured in Settings, with your own key.

You can

  • Tap Generate from prompt on the welcome screen (portrait) to open Generate workflow from prompt: write the Prompt, mentioning the trigger (push, save, commit, error, deploy) and the actions (deploy, notify, backup, test, format), and press Generate.
  • Tap Change with AI in a card's menu to open Change “…” with AI: say what you want changed; the rest of the workflow stays as it is and you see what changed before saving.
  • Review the result: the preview, Checks (linter problems), Dry run passed in n ms, Dry run failed: … or “Not tested: … You can test it yourself from the editor.”, Adjusted automatically for what the app repaired, and, when changing, the diff (added, removed, changed, n steps unchanged).
  • Choose Save & enable (only when creating), Open in editor (the way out when the checks block saving) or Discard. A workflow created this way is saved switched on; a change keeps the workflow's id, its on/off state and its creation date.

You can't, and why

  • Count on a dry run for everything the AI makes: it only runs when the app judges it safe, because a dry run executes steps. When a step can't be simulated, the waits add up to more than 10 seconds, a wait is for an event or a subflow can't be inspected, it says Not tested and gives the reason.By design
  • Get a workflow written by a model without an AI provider: with no key set the app falls back to keyword matching and says “Built without a model: no AI key is set, so this came from keyword matching.”Needs network
  • Save a generated workflow that the linter rejects: “Fix these before saving: this workflow is not ready.”By design

The chat agent and workflows

Two different things. A workflow you mark Available to AI agent and keep switched on is announced to the chat as its own tool, workflow__<name>__<last 6 characters of the id>, with a description built from its steps (it warns about irreversible ones) and an input schema built from its declared inputs. And six management tools are always there, with or without exposed workflows.

ToolWhat it doesPlan
workflow__listLists your workflows (up to 25) with triggers, whether they are enabled and how the last run went; it can filter.Free
workflow__getReturns one workflow in full. Secret parameters appear as [secret, not shown]. A workflow longer than 20 000 characters is refused, not cut.Free
workflow__runsThe history of one workflow, newest first (5 by default, up to 20), with the last error and up to 5 failed steps.Free
workflow__runRuns a workflow now. It refuses one that is switched off, validates the inputs and respects the irreversible-steps permission.Free
workflow__createCreates a workflow from a document. It is validated first, and it is born switched off even if the model asks for it on.Pro
workflow__updateChanges fields of an existing workflow.Pro

You can

  • Ask the agent which workflows run when you push, or why last night's backup failed: it reads with workflow__list, workflow__get and workflow__runs, which are free.
  • Ask it to run one with workflow__run: it validates the inputs against the ones the workflow declares, and respects the irreversible-steps permission you gave (Allow the AI).
  • With Pro, ask it to create or change one: workflow__create and workflow__update. The three tools that write go through the agent's confirmation sheet.

You can't, and why

  • Create or change workflows from the chat on Free: the model gets a refusal that says to tell you, and you see a notice (“… needs PocketCode Pro, so that action did not run.”) with an Upgrade button. The plan feature is called Workflows from the chat.​Pro
  • Let the agent change a workflow's retry, timeouts, When condition or retention: the AI can't set them, and an update keeps the ids of the steps, the permissions, the tags and the retention.By design
  • Use Available to AI agent as an access control: it only decides whether a workflow is announced as its own tool. workflow__run can run any workflow that is switched on, by name.By design

Marketplace

The Marketplace has a Workflows asset type, but today a workflow can't be installed from it, and the app has no way to publish one. To share a workflow, use a file or a link (see Export, import and links).

You can

  • Filter the Marketplace by the Workflows kind and read the page of an asset of that kind.
  • Share your own with Share as file, or host a .pcwf.json on an https address and send a pocketcode://workflows/import?url=… link.

You can't, and why

  • Install a workflow from the Marketplace: on the page of a workflow asset the install button is disabled (Requires WASM runtime), the same as for a plugin, even though the engine already knows how to check and install one.Not yet
  • Publish a workflow to the Marketplace: there is no button and the app can't upload anything. The catalogue is published by the team through a pull request that CI validates and signs.By design

Free and Pro

The engine is free. What costs money is narrow, and each item is a limit you can reach from outside this module. Prices are in Plans & pricing.

FeatureFreePro
25 triggers, 15 actions, seven kinds of step, templates, the editor, the linter and step testsYesYes
Scheduling (WorkManager, cron, device conditions, missed-run recovery)YesYes
Encrypted secrets, per-workflow permissions, history and Activity, export and import of .pcwf.jsonYesYes
Available to AI agent, and the chat running your workflows (workflow__run, workflow__list, workflow__get, workflow__runs)YesYes
Generate from prompt and Change with AI in this moduleYes, with your own AI providerYes, with your own AI provider
The AI chat creating or changing workflows (workflow__create, workflow__update)No: the model gets a refusal and you see a notice with UpgradeYes (Workflows from the chat)
The Trigger deploy step while a deploy of the same project is in flight (queued, building or deploying)No: 1 in flight per project (“Upgrade required to trigger another active deploy”)Yes, no cap
Sync of workflow definitions between your devices (Cloud Sync, the Workflows group)NoYes
What is not for sale, and why, in the code's own words: webhooks don't exist (there is no server, endpoint or trigger), exact alarms were ruled out in favour of WorkManager with its slack, and publishing to the Marketplace can't upload anything. History and export are free on purpose: charging for them would take away something that is free today, and export is the only way to get your work out of the app. Cloud Sync moves definitions only; runs, schedules, pinned outputs, irreversible-step permissions and secrets never leave the device.

Keyboard shortcuts

These work only while the editor is open and on a hardware keyboard. They can be changed in Settings.

KeyWhat it does
Ctrl+SSave.
Ctrl+Z / Ctrl+Shift+ZUndo / Redo.
Ctrl+EnterTest now: dry-run the workflow.
Ctrl+DDuplicate the selected step (Ctrl+Shift+D in the IntelliJ preset).
DeleteDelete the selected step.
Ctrl+↑ / Ctrl+↓Move the selected step up or down (Ctrl+Alt+↑ / Ctrl+Alt+↓ in the Atom preset).

The last four act on the selected step: tap the pencil of a card to select it.

Privacy and security

Workflows run on your device; what leaves it is what you point a step at.

  • Where it is stored. Definitions live in a local database on the device, one file per account. With Pro, Cloud Sync can copy the definitions between your devices (the Workflows group); runs, schedules, pinned outputs and secrets are never synced.
  • Secrets. They are kept encrypted on the device, one set per account (Android Keystore key, AES-256-GCM), are never shown again, are not resolved in a dry run, don't travel in an exported file and are masked as ••• when a run is written to the history (a value shorter than 4 characters can't be masked).
  • Irreversible-steps permission. The answer to Enable anyway and Allow the AI is remembered on the device only, once per workflow.
  • What a workflow can do. A workflow can run commands and write files with the permissions you left open; the permissions are not a sandbox, and the domain list does not stop an AI, deploy or git step.
  • What leaves the device. HTTP request, Trigger deploy, Git operation (push and pull) and the AI steps go to the services you configured or the addresses you wrote. An AI step sends its prompt and context to your provider with your own key.
  • Imports. A file or a link always arrives switched off, with a preview and the linter's result; a link must be https, can't carry credentials or point at the device, doesn't follow redirects and downloads nothing until you press Download.
  • What other apps send you. Shared text and files arrive as data, never as instructions, and the app always shows you what was received and which workflow gets it.
  • Exports. Only parameters declared as secrets are emptied; HTTP headers and commands travel as you typed them. Check the file before you share it.

Limitations

The most important limits, each with its reason. Limits specific to a screen are in the section of that screen.

  • The chat can't create or change workflows on Free, and the Trigger deploy step fails on Free while a deploy of that project is already in flight.Pro
  • Definitions only sync between devices with Pro (Cloud Sync).Pro
  • Scheduled runs go through WorkManager: not more often than every 15 minutes, with no exact alarms, and Doze or battery saving can delay them (never cancel them).Google Play
  • Runs in the background rely on a foreground service; from Android 12 the system may refuse it when the app is in the background, and the run then goes on without that protection.Google Play
  • Only the first 5 simultaneous runs get a progress notification; the quick tile is opt-in and Android decides how many shortcuts a launcher shows.Device
  • The secrets store may not open after you restore the phone or change the screen lock; nothing is deleted.Device
  • Project closed and The AI finished its turn never fire: nothing in the app emits them.Not yet
  • On git commit only fires for commits made from Projects, not for those of the editor's Source Control panel or the AI chat.Not yet
  • Schedules have no time zone selector, and there is no automatic notification when a run fails.Not yet
  • Workflows can't be installed from the Marketplace, and the app can't publish one.Not yet
  • A run that was in flight when the system killed the app leaves no row in the history, and the shell log of a finished run isn't kept.By design
  • No graph canvas, N-way switch or free merge, no editing of a schedule, no cron ?, L, #, and only three intervals as presets.By design
  • Up to 6 triggers per workflow, 8 conditions per filter, 8 tags per workflow, 40 steps listed in an import preview and a 512 KB file.By design
  • Engine limits: 8 runs at a time across the app, 16 waiting for up to 120 seconds, 10 queued event runs per workflow, loops of up to 10 000 iterations and 16 at once, subflows 5 levels deep, a Wait for an event of 5 minutes by default, and an error message of a Try / on failure limited to 4 096 characters.By design
  • Step outputs: an HTTP response body up to 128 KiB, the shell's output up to 64 KB, a file read up to 128 KiB, and each step stores at most 32 KiB of output in the history.By design
  • The activity screen shows up to the 500 most recent runs; the history you keep per workflow is 1 to 1 000 runs and 1 to 365 days.By design
  • Deploys go to render, netlify, digitalocean and railway only, and Query database reaches neon, supabase, turso, upstash, cloudflare (D1) and your saved remote PostgreSQL connections.Third party
  • Generate from prompt and Change with AI need an AI provider with a key; without one they fall back to keyword matching.Needs network

Troubleshooting

Real messages of the app, with what they mean.

Nothing in the app emits PROJECT_CLOSED yet, so this workflow will not fire.

The trigger is in the dropdown but nothing emits it. Pick another trigger: Project closed and The AI finished its turn never fire.

No condition: this trigger fires with every event of its type.

It is not an error: the trigger has no filter. Add a condition if you want only some events.

A workflow I switched on never runs

Check that Enabled is on, that its trigger really has an emitter and a matching filter, that it isn't skipped by Skip the new one while another run is going, and that required inputs have defaults (an event, a schedule or a shortcut has nobody to ask).

No active workflow is listening for this. Add the matching trigger in the workflow editor.

You shared something to PocketCode and no switched-on workflow has Text shared to PocketCode or File shared to PocketCode. Add the trigger and switch the workflow on.

… needs a value first

A shortcut, tile or share tried to start a workflow with a required input that has no default. Give the input a default, or run it from the module.

Required with no default: … A scheduled run cannot start — the scheduler has nobody to ask.

A schedule can't ask you for inputs. Give every required input a default value.

Invalid cron expression

A cron has five fields: min hour day month weekday. ?, L, #, a step over a range and a year field are not accepted.

Asks for every 5 min, but it runs every 15 min: that is the floor Android allows.

An interval below 15 minutes is raised to 15. A cron below that rate gets “Android does not guarantee that rate in the background”.

Scheduled workflows need attention

The banner says what Android answered: Notifications are off for PocketCode, “The ‘Workflows · alerts’ channel is blocked”, or “PocketCode is subject to battery optimisation”. Tap Open settings. The banner can't be dismissed; it goes away when the cause does.

permiso denegado (…): … Se cambia en «Permisos», dentro de los ajustes del workflow.

A step was refused by the permissions of the workflow (the message is in Spanish in every language). Open Workflow settings and Permissions and open the network, writing or commands, or add the domain.

Upgrade required to trigger another active deploy

On Free a Trigger deploy step fails while a deploy of the same project is still in flight (queued, building or deploying); the limit is 1. Wait for it to finish, or go Pro.

la consulta modifica datos (…) y el paso no tiene «allowWrites» activado

A Query database step has write verbs and allowWrites is off (the message is in Spanish in every language). Turn allowWrites on only if that is what you want.

That is not a PocketCode workflow file. Pick a .pcwf.json file.

The file isn't a workflow. The other two messages are “This is a workflow file, but it is damaged and cannot be read.” and “This file was written by a newer version of PocketCode (format …). Update the app to open it.”

That address sends you somewhere else: … It was not followed — confirm the new address only if you trust it.

An import link redirected to another address. Confirm the new address only if you trust it.

The encrypted store could not be opened on this device

The secrets store can't be opened after restoring the phone or changing the screen lock. Nothing has been deleted.

Careful: this value is shorter than 4 characters, so it will NOT be masked with ••• in run history. If a step prints it, it stays readable there.

The secret is saved, but if a step prints it, it stays readable in the run history. Use a longer value.

The workflow no longer exists: this run cannot be repeated.

The workflow was deleted. Runs of a deleted workflow can still be read in Activity, but not repeated.

The shell log is not kept in the history: it is only visible while the run is going.

Follow the log from Live output while the run is going, or write what you need into a file with a step.

Fix these before saving: this workflow is not ready.

The generator's checks found an error. Open the workflow in the editor with Open in editor and fix what Problems lists.

Not tested: … You can test it yourself from the editor.

The generator didn't dry-run the workflow because a dry run executes steps and it could not be sure of one of them: a step that can't be simulated (a deploy), waits that add up to more than 10 seconds, a wait for an event, or a subflow it can't look inside. Test it from the editor.