Skip to content

Hand files to a workflow

Each project has a drop box: the folder .agents/dropbox/ in the project. A file that arrives there raises the event dropbox.file_added, and a workflow in that project can run on it. This guide sets up a workflow that reviews every PDF or Markdown file dropped into dropbox/review/, and leaves every other file alone.

Before you start

  • A project. The drop box is a folder in it, wherever the project lives: a project on a server has its drop box on that server.
  • Workflows in that project are approved and on. See Set up a workflow.

Steps

  1. Write the workflow, in .agents/workflows/review-drops.md:
---
name: Review what lands in the drop box
on:
  - dropbox.file_added
agent: new
---

If the event's folder is not review, or its extension is not pdf or md, stop: it is
not yours. Otherwise read the dropped file and review it, then move it out of
.agents/dropbox/, to reviewed/ at the project's top.

An arrival can't be narrowed in on:, so the workflow runs for every file and the prompt says which to take. The event tells the agent folder, where the file is inside the drop box (review for .agents/dropbox/review/, empty at its top), and extension, in lower case without the dot.

  1. Put a file into .agents/dropbox/review/, from Finder, a script, cp or scp. Make the folder if it is not there.

On the Mac, you can also drag files from Finder onto the project's row in the sidebar, or onto any of its sessions' rows. They go into the top of the project's drop box, never into a session's worktree, so a prompt that takes only review leaves them. To put them in a folder such as review, right click the project's row, choose Put Files in Drop Box…, type the folder, then drag the files onto the sheet or press Choose Files…. A file sent from the Mac can be up to 25 MB; copy a bigger one into the folder in Finder. A folder dragged onto the list is added as a project, as before.

On the iPhone or iPad, touch and hold the project in the list, choose Put Files in Drop Box…, type a folder such as review if you want one, then Choose Files….

On the web page, open the project's menu (right click, or the menu key) and choose Put Files in Drop Box…, type a folder if you want one, choose files and press Put in Drop Box. You can also drag files onto a project's or a session's row, which puts them at the drop box's top.

From the phone or the web page, a file can be up to 900 KB, the most that crosses the link in one go.

  1. Once the file has stopped changing for a moment, the workflow starts an agent. Its prompt ends with the event, including path, the file's full path, so the agent knows which file to read.

What happens to the file

The app never moves or deletes a dropped file. The workflow's prompt says what to do with it: leave it, move it or delete it.

  • A file dropped under a name already there replaces it, and fires again. So does a file changed where it lies, which an agent editing it would do. Have the agent move a file out of the drop box before it changes it.
  • Moving a file to another folder in the drop box is an arrival there, and runs the workflow again. Have the agent move a file it is done with out of .agents/dropbox/.
  • Files already in the drop box when the app starts do nothing. Only new arrivals fire.
  • A file still being written fires once, after it stops changing.
  • Names starting with a dot are passed over, so a copy's temporary file and Finder's .DS_Store never fire.
  • There is no size or rate limit, and .gitignore does not apply. Whether to commit dropped files is up to the project: add .agents/dropbox/ to its .gitignore to keep them out of git.

See also