> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowdeck.studio/llms.txt > Use this file to discover all available pages before exploring further. # Loops > Run an agent task on a schedule, or whenever you need it A loop is a saved agent task that FlowDeck runs for you: a nightly code review, a weekly dependency check, a test sweep after every morning's merges. Each run starts from a clean checkout of a branch you choose, works on its own, and leaves a short summary you can review later or pick up as a normal chat. You can manage loops two ways, and they edit the same loops: * **In the app.** Use the **Loops** section in the sidebar to create, edit, run, and review loops. See [Create a loop](#create-a-loop). * **From chat.** Ask the agent in any project chat to create, change, pause, or run a loop for you. See [Manage loops from chat](#manage-loops-from-chat). ## Create a loop Each project in the sidebar has a **Loops** section. Choose **+** in its header to open the editor, fill in the fields, and choose **Create Loop**. ![The loop editor: instructions, agent, schedule, time zone, and memory](https://mintcdn.com/flowdeck/oePHnRKfLfp2qoRD/images/macos/loops-editor.png?fit=max\&auto=format\&n=oePHnRKfLfp2qoRD\&q=85\&s=adcfcc5d1fde671c96b6a808bceca7a3) The loop editor: instructions, agent, schedule, time zone, and memory | Field | What it does | | - | - | | **Name** | How the loop appears in the sidebar. | | **Instructions** | What the agent should do on every run. | | Agent, model, effort | Chosen from the controls under the instructions, the same way as in chat. New loops start with your default agent. | | Permission | **Allow Edits** or **Skip Permissions**. New loops start with Skip Permissions when that is your default permission in Settings, and Allow Edits otherwise. | | **Frequency** | When the loop runs. See [Schedules](#schedules). | | **Memory** | Lets the loop learn from each run so later runs improve. On by default. See [Memory and self-improvement](#memory-and-self-improvement). | **Show Advanced Settings** reveals two more options: * **Source Branch**: the branch every run starts from. Defaults to `main`. The list shows local branches first and adds remote ones as they arrive. * **Destination**: where build, run, and test commands go during a run. Pick your Mac, a device, an existing simulator, or a new simulator. With an existing simulator, all simulator work runs there and the loop never deletes it. With a new simulator, FlowDeck creates one for each run when needed and removes it when the run ends. To change a loop later, choose **Edit Loop** from the pencil button in the loop's header or from the options menu on its sidebar row. ## Manage loops from chat You do not need to open the editor. Describe the recurring work in a project chat and the agent creates the loop for you. For example: * "Every weekday at 9:00 Madrid time, review the commits merged to main since the last run. Flag risky changes and missing tests, and don't edit any files." * "Check our package manifests for outdated dependencies every Monday morning and summarize what changed upstream." * "Run the unit tests every hour and tell me when something starts failing." The agent looks at the loops the project already has before it creates one, so it reuses an existing loop instead of making a duplicate. It writes the instructions as a complete, standalone task, because every run starts without your conversation. When the schedule or time zone is unclear it asks you. Once the loop exists, it tells you the loop's name and its next run, and the loop appears in the sidebar right away. Ask for a one-off task in plain chat instead. A loop is for work that repeats. ### What the agent can do | Ask for | What happens | | - | - | | Create a loop | Creates it with the schedule, time zone, agent, model, effort, branch, destination, and memory setting you describe. Anything you leave out uses the same defaults as the editor. | | Rename or reschedule | Changes only the fields you name. A new schedule replaces the whole schedule. | | Pause or resume | Turns the loop's **Active** switch off or on. Resuming picks up from the next scheduled time. | | Run now | Starts one run immediately without changing the schedule. It reports an error if the loop is already running or too many loops are running. | | Delete | Removes the loop, its run history, memory, and worktree. The agent deletes only when you ask, and names the loop first. | Loops you create or change in chat are the same loops you see in the app. Edit them in the editor, watch their runs, and read their memory exactly as you would any other. ### Permissions and limits * **Chat-created loops start with Allow Edits.** A loop that skips permissions removes the safety sandbox, so an agent can create one only when your chat is itself running in Skip Permissions. From any other chat, ask for Allow Edits, or open the editor and choose Skip Permissions yourself. * **Skip Permissions loops are locked from other chats.** Unless your chat also skips permissions, an agent can rename or reschedule such a loop but cannot change its instructions, agent, model, effort, or source branch. * **A project holds up to 50 loops** when an agent creates them. A name is one line of at most 100 characters and instructions are at most 20,000 characters. * **"Don't edit files" is an instruction, not a lock.** A chat-created loop runs with Allow Edits, and there is no read-only permission, so a request to leave files alone only goes into the loop's instructions. If a loop must never change anything, say so clearly and review its first runs. * **Deleting from chat never removes a simulator.** To also delete the simulator a loop created, use **Delete Loop** in the app. * Only the agent in a regular project chat can manage loops. Scheduled runs, follow-up chats on a run, and Plan chats cannot. If a request fails, the agent reads the error, fixes the field it names, and tries once more. When an agent, model, effort, or destination is unknown it picks from the valid choices rather than guessing. ## Schedules | Frequency | Runs | | - | - | | **Manual** | Only when you choose **Run Now**. | | **Hourly** | Every hour. | | **Daily** | Every day at the time you set. | | **Weekdays** | Monday to Friday at the time you set. | | **Weekly** | On the day and time you set. | | **Monthly** | On the day of the month you pick under **Starts on**, at the time you set. In shorter months it runs on the last day instead. | | **Custom** | Every *n* minutes, hours, days, or months. | Daily, weekday, weekly, and monthly schedules use the **Time Zone** you pick, so a loop set for 9:00 in New York keeps running at 9:00 New York time when you travel. Custom schedules can run at most every 5 minutes. If you enter a shorter interval, the editor says so next to **Create Loop**. Loops run only while FlowDeck is open. If FlowDeck was closed or your Mac was asleep when a run was due, that run is not made up later; the loop waits for its next scheduled time. ## Watch and review runs Select a loop to see its schedule, its run history, and the selected run's output. The header has the **Active** switch, **Run Now**, **Edit Loop**, **Memory**, and **Delete Loop**. ![A loop's page: the schedule and toggle, the next scheduled run, and Run Now](https://mintcdn.com/flowdeck/oePHnRKfLfp2qoRD/images/macos/loops-schedule.png?fit=max\&auto=format\&n=oePHnRKfLfp2qoRD\&q=85\&s=510ce25c98f5be719504df42f4a7695c) A loop's page: the schedule and toggle, the next scheduled run, and Run Now * **Run Now** starts a run immediately, whatever the schedule. While a run is going, the button becomes **Stop Run**. * The **Active** switch pauses and resumes a scheduled loop. Resuming picks up from the next scheduled time. Manual loops have no switch. * History lists the next scheduled run under **Upcoming**, then past runs with their status, whether they were manual or scheduled, and how long they took. Each loop keeps its 25 most recent runs. When a run finishes, the agent ends with a short **Run summary** of what it did, what it found, how it validated the work, and anything that blocked it. That summary is shown first; choose **View full output** to see the whole conversation, or **Copy summary** to copy it. A failed run shows why it failed above the summary. ### Continue a run as a chat Every run keeps its chat, so you can ask follow-up questions or request more work on any finished run. Follow-ups work like any other chat: the agent asks for permission as usual, and your answers never change the loop's saved instructions or other runs. If a run is still going, you can continue once it finishes. Follow-ups run in the loop's workspace. When the next run starts, the loop's open chats close first, so a follow-up never edits files while a run is using them. Older runs show a note that the workspace now holds a newer run's files. You can also reach a loop from Open Quickly (**⌘K**) by searching for its name. While a loop is open the top bar shows no controls: a loop has no build target, console, simulator or inspector. To review what a run changed, use Continue in New Session and open the changes from that session. ### Continue in New Session **Continue in New Session** turns any finished run into a normal session. The new session starts from the files that run left, with its edits shown as uncommitted changes. The run's conversation appears in the new chat and the agent knows what it says, so you can keep asking about it. The button is available while the loop has no run in progress. If the run's files are no longer available, FlowDeck asks before starting from the loop's source branch without them. If a session was already started from the run and still exists, FlowDeck asks whether to open it or start another. A run's details show the branch it started from and the branches of any sessions continued from it. ## How a run works Every run is a fresh, unattended agent conversation: * **Its own workspace.** Each loop has a private worktree. Before each run, FlowDeck fetches and resets it to the source branch. Before resetting, FlowDeck saves what the previous run left, including uncommitted changes, and keeps it as long as that run is in history. Files left behind by a cleanup that failed are removed the next time FlowDeck starts. If the fetch fails, the run starts from the last fetched or local copy of the branch. Your own sessions and their files are never touched. * **No one to ask.** A run cannot wait for you. If the agent asks a question, needs a permission you have not granted, or wants a plan approved, the run fails and keeps whatever output it produced. Write instructions the agent can complete on its own, and choose the permission level it needs. * **The settings you saved.** A run uses exactly the agent, model, effort, and permission saved with the loop. If one of them is unavailable, for example a signed-out provider or a removed model, the run fails rather than switching to something else. * **Completed means the agent finished.** A completed run means the agent finished its turn. Check the summary to see whether the work itself succeeded. Every agent available in FlowDeck can run loops. ### Limits Loops run without supervision, so FlowDeck keeps them from running away: * A run stops after **two hours** of awake time. Time your Mac spends asleep does not count. Partial output is kept. * A run fails if the agent goes silent for **10 minutes** while no tool is running. * At most **three** loops run at once. A scheduled run that would exceed that is recorded as skipped. **Run Now** reports that too many loops are running. * If a scheduled run comes due while the previous run of the same loop is still going, the new one is skipped. * After **three failed runs in a row**, the loop pauses itself and explains why. Fix the cause, then turn **Active** back on. If you quit FlowDeck while a run is going, FlowDeck stops it and saves it as interrupted. Interrupted runs never restart on their own. ## Memory and self-improvement With **Memory** on, a loop improves from run to run. Each run: * reads the loop's memory before it starts, and applies what earlier runs decided and learned; * records each durable decision or finding as it works, such as a project fact, a pitfall and its fix, or an approach that worked or failed; * reviews the notes before it finishes, merging duplicates and removing anything obsolete or wrong. A follow-up chat works the same way. When you give an instruction meant for future runs, or a conversation settles a decision, the agent writes it into memory. Memory belongs to one loop. It never changes the loop's instructions, and it is deleted with the loop. Agents are told never to record secrets, credentials, tokens, or personal data. A problem reading or saving memory never fails a run. ### Read and edit memory Choose the **Memory** button in the loop's header to open it. Edits you save are kept until a later run or a verified fact replaces them. FlowDeck keeps the version before the last change, whether you or the agent made it. **Restore Previous Version** brings that version back. ### Turn memory off The **Memory** switch in that window turns self-improvement off for the loop. While it is off, runs do not read or write memory, so each run starts without earlier notes. The memory is kept, and turning the switch back on resumes from it. ## Delete a loop Choose **Delete Loop** from the loop's header or its options menu. Deleting stops any active run and permanently removes the loop, its memory, run history, and its private worktree and branch. Your project files are kept. If the loop created a simulator, you can also choose **Also delete this loop's simulator**. If FlowDeck cannot remove the worktree or simulator, the loop is still deleted and FlowDeck tells you what was left behind. ## Troubleshooting | Message | What to do | | - | - | | **Paused after several failed runs in a row.** | Open a failed run to see why, fix the cause, then turn **Active** back on. | | **Permission denied.** or **User input required.** | The agent needed something a run cannot provide. Raise the permission level or make the instructions self-contained. | | **Sign in to the saved provider before running this loop.** | Sign in to that agent's CLI in your terminal, then run the loop again. | | **Authentication required** under a failed run | The loop's saved agent is not signed in. Edit the loop and choose an agent you are signed in to, or sign in to that agent first. | | **The saved model is unavailable.** | Edit the loop and choose an available model. | | **The source branch was not found locally or on origin.** | Edit the loop and choose a branch that exists. | | **The attached simulator no longer exists.** | Edit the loop and choose another destination. | | **This project is unavailable.** | The project was moved or removed. Add it back to FlowDeck. | | Warning icon next to **Loops** in the sidebar | Some saved loop data could not be read. Healthy loops keep running; hover the icon for details. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.