flow-start-recording
Start a new flow recording to capture a reusable sequence of device interactions for later replay, resetting any existing flow file to an empty state.
Instructions
Start recording a new flow, resetting .argent/flows/.yaml to an empty flow and replacing any existing one.
Use when you want to capture a reusable sequence of device interactions for later replay.
Returns { message, flowFile, savedTo } and optionally { restarted, discardedSteps } if a live recording of the same flow was discarded.
Whether this server writes that file depends on where your project is: co-located, it creates it and fails if the .argent/flows/ directory cannot be created or the file cannot be written; against a remote tool-server it writes nothing and savedTo is a directive your client applies (a null savedTo back means it did not).
Several flows can be recorded at once — each keyed by the name + project_root
that every subsequent recording tool repeats — and one recording's steps never
land in another's file. Steps still run LIVE, so give each concurrent recording
its own device and pick a name unique to your task.
After starting, use flow-add-step to append tool calls — each step is executed
LIVE so you can verify it works before it gets recorded. Read each step's
message: an await-ui-element whose condition never held is still recorded (it
returns success:false rather than failing), and a check that passes live can
still fail once polished into an await:/assert: directive, which resolves
against a different tree. flow-add-step warns about both when you record the
wait DIRECTLY. A wait nested inside a recorded run-sequence gets neither warning
— that tool reports its own shape — so for those, read toolResult. For a self-contained
e2e flow, record a restart-app of the app under test as the FIRST step (captured
as the flow's launch step); for a reusable fragment, skip that and pass
executionPrerequisite instead. Use flow-add-echo to add labels. Call
flow-finish-recording when done.
If a recorded step turns out to be wrong, edit the .yaml file directly to remove or reorder steps - after flow-finish-recording, not during the recording. Against a remote client the in-memory copy is authoritative and every write serializes it over your edit; in host mode the recorder re-reads the file before each append, so a mid-recording edit renumbers the steps and costs the finish the cross-tree verdicts anchored to them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for this flow (e.g. "settings-explore") — letters, digits, underscore and hyphen only. | |
| project_root | Yes | Absolute path to the project root directory (the directory that contains or should contain `.argent/flows/`). The flow file is created at `<project_root>/.argent/flows/<name>.yaml`. | |
| executionPrerequisite | No | Fragments only: the app/device state assumed on entry (e.g. "Settings app open on General page"). For a self-contained e2e flow, omit this and record a `restart-app` as the first step instead — it is captured as the flow's `launch` step. restart-app has no chromium support, so a chromium flow records as a fragment; add the `launch: { chromium: <app path> }` line to the YAML afterward, deleting the executionPrerequisite line if you passed one — a flow that starts with a launch must not declare it. |