From dc94a0a28dca566dd01b212ff074166681526e28 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Tue, 12 May 2026 07:39:56 +0000 Subject: [PATCH] docs(TSP-1227): add documentation for filesystem sync triggers Create a new page for filesystem sync triggers explaining how file writes to project memory or personal files volumes automatically trigger agents, including glob pattern filtering, 100KB content limit, conversation threading behavior, and access controls. Update triggers.mdx overview and docs.json navigation to include the new trigger type. Co-Authored-By: Claude Sonnet 4.6 --- .../agent-triggers/filesystem-sync.mdx | 70 +++++++++++++++++++ build/agents/build-your-agent/triggers.mdx | 7 ++ docs.json | 3 +- 3 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 build/agents/build-your-agent/agent-triggers/filesystem-sync.mdx diff --git a/build/agents/build-your-agent/agent-triggers/filesystem-sync.mdx b/build/agents/build-your-agent/agent-triggers/filesystem-sync.mdx new file mode 100644 index 00000000..5b45c8ae --- /dev/null +++ b/build/agents/build-your-agent/agent-triggers/filesystem-sync.mdx @@ -0,0 +1,70 @@ +--- +title: 'Filesystem sync triggers' +description: 'Trigger an agent automatically when files are written to your project memory or personal files volume' +sidebarTitle: 'Filesystem sync' +--- + +Filesystem sync triggers watch for file writes in your project's shared memory volume or your personal files volume, then automatically send the file's metadata and content to a designated agent. This lets you build agents that react to file activity without polling or manual input. + +## How it works + +When a file is written to a watched volume, the trigger fires and sends the following to your agent as a message: + +- File metadata (name, path, size, last modified time) +- File content, up to 100KB for text files + +If the same file is written to multiple times, each subsequent write continues the same conversation thread rather than opening a new one. This keeps all activity for a single file in a coherent conversation history. + +## Setting up a filesystem sync trigger + +1. Navigate to your agent and click **Triggers** in the sidebar +2. Click **Add trigger** +3. Select **Filesystem sync** from the available options +4. Choose the volume to watch: + - **Shared memory volume** — files stored in your project's shared memory, accessible to all project members + - **Personal files volume** — files stored in your own personal files area +5. Optionally configure glob patterns to filter which files trigger the sync (see [Filtering files with glob patterns](#filtering-files-with-glob-patterns)) +6. Save the trigger + +## Filtering files with glob patterns + +By default, any file write to the watched volume triggers the sync. You can narrow this down using glob patterns. + +- **Include patterns** — only files matching these patterns trigger the sync (e.g., `**/*.pdf` to watch only PDF files) +- **Exclude patterns** — files matching these patterns are ignored even if they also match an include pattern (e.g., `**/tmp/**` to skip temporary files) + +If both include and exclude patterns are configured, a file must match an include pattern and not match any exclude pattern to trigger the sync. + + +| Pattern | Matches | +| --- | --- | +| `**/*.csv` | Any CSV file in any subfolder | +| `reports/**` | All files inside a `reports/` directory | +| `**/tmp/**` | Any file inside a `tmp/` directory | +| `invoices/2025-*.pdf` | PDF files in `invoices/` whose names start with `2025-` | + + +## Access controls + +- **Shared memory volume**: only file writes made by the user who created the sync trigger cause the sync to fire. Writes by other project members do not trigger it. +- **Personal files volume**: only the owner of the personal files volume can create a sync on it, and only their own writes trigger the sync. + +## Frequently asked questions (FAQs) + + + + Each write to the same file appends a new message to the existing conversation thread for that file. This keeps all activity related to a single file in one continuous thread rather than creating separate conversations. + + + Text file content is sent to the agent up to 100KB per file write. Files larger than 100KB will have their content truncated; file metadata is always sent in full regardless of file size. + + + No. Only file writes made by the user who created the sync trigger cause it to fire, even when watching the shared memory volume. + + + No. Each filesystem sync trigger watches one volume. Create a separate trigger for each volume if you need to watch both. + + + Yes. If you configure both include and exclude patterns, a file triggers the sync only when it matches at least one include pattern and does not match any exclude pattern. Exclude patterns always take precedence. + + diff --git a/build/agents/build-your-agent/triggers.mdx b/build/agents/build-your-agent/triggers.mdx index e447e781..d847077f 100644 --- a/build/agents/build-your-agent/triggers.mdx +++ b/build/agents/build-your-agent/triggers.mdx @@ -88,6 +88,12 @@ Connect to custom webhooks, APIs, and SDKs to trigger your Agent programmaticall Use a specific Tool to trigger your Agent. +### Filesystem sync triggers + +Watch for file writes in your project's shared memory volume or personal files volume and send file content to your Agent automatically. + +Trigger your Agent when files are written to a watched volume. + ## Choosing the right trigger | I want to... | Use this trigger | @@ -99,6 +105,7 @@ Connect to custom webhooks, APIs, and SDKs to trigger your Agent programmaticall | Receive data from my own app or website | **Webhook Trigger** | | Trigger my agent from code I control | **SDK & API Triggers** | | Combine data from multiple sources before triggering | **Tools as Triggers** | +| React to files written to a shared or personal volume | **Filesystem Sync Triggers** | ## Frequently asked questions (FAQs) diff --git a/docs.json b/docs.json index 07e9a0fa..7dc8f36f 100644 --- a/docs.json +++ b/docs.json @@ -117,7 +117,8 @@ "build/agents/build-your-agent/agent-triggers/scheduled-triggers", "build/agents/build-your-agent/agent-triggers/custom-webhook", "build/agents/build-your-agent/agent-triggers/sdk-and-api-triggers", - "build/agents/build-your-agent/agent-triggers/tools-as-triggers" + "build/agents/build-your-agent/agent-triggers/tools-as-triggers", + "build/agents/build-your-agent/agent-triggers/filesystem-sync" ] }, {