Familiar logo
Familiar usefamiliar.com
Documentation / Fleet

Tutorial: Automate with Triggers

Learn to automate agent tasks with file watchers, schedules, webhooks, and git hooks.

What You'll Build

Automated workflows that run agents without manual intervention:

  • File watcher that processes new downloads
  • Scheduled daily summary
  • Webhook integration with GitHub
  • Git hook for pre-commit checks

Time: 20-30 minutes

Prerequisites

  • Fleet installed with an AI provider configured
  • For webhooks: Fleet Gateway connected (Settings → Remote)

Part 1: File Watcher Automation

Create a trigger that processes files when they appear in a directory.

Step 1: Create the Trigger

Ask an agent to create a file watcher:

Create a file watcher trigger called "download-processor" that watches
~/Downloads for new PDF and CSV files

The agent creates:

name: download-processor
type: file_watcher
watch_paths:
  - ~/Downloads/*.pdf
  - ~/Downloads/*.csv

Step 2: Create a Processing Agent

Create a new agent named "File Processor" with this system prompt:

You are a file processor. When triggered with a new file:

1. Read and analyze the file contents
2. Summarize the key information
3. Move the file to the appropriate folder:
   - Invoices → ~/Documents/Invoices/
   - Reports → ~/Documents/Reports/
   - Data files → ~/Documents/Data/
4. Create a summary note in ~/Documents/processed-log.md

Set permissions to Read/Write since it needs to move files.

Step 3: Bind the Trigger

Add the trigger binding to your agent's configuration:

triggers:
  - trigger: download-processor
    enabled: true

Or ask the agent:

Subscribe to the download-processor trigger

Step 4: Test It

Drop a PDF into your Downloads folder and watch the agent automatically process it.

Part 2: Scheduled Tasks

Create a daily summary that runs automatically.

Step 1: Create the Schedule Trigger

Create a schedule trigger called "daily-summary" that runs at 9 AM every weekday

The agent creates:

name: daily-summary
type: schedule
cron: "0 9 * * 1-5"

Step 2: Create a Summary Agent

Create an agent named "Daily Summarizer":

You are a daily summarizer. Each morning:

1. Read ~/Documents/notes/ for any notes from yesterday
2. Check ~/projects/ for recent git commits
3. Summarize what was accomplished
4. Write a summary to ~/Documents/daily-summaries/YYYY-MM-DD.md

Step 3: Configure for Non-Interactive Use

Since scheduled triggers run without user interaction, configure permissions upfront:

permissions:
  execution_tier: read_write
  directories:
    - path: ~/Documents
      access: readwrite
    - path: ~/projects
      access: read
  rules:
    - "Bash(git log*)"
    - "Bash(git diff*)"

Step 4: Bind and Verify

Add the trigger binding:

triggers:
  - trigger: daily-summary
    enabled: true

Test with Run Now in Settings → Triggers.

Part 3: Webhook Integration

Connect Fleet to external services like GitHub.

Step 1: Connect Fleet Gateway

  1. Go to Settings → Remote
  2. Click Connect to Fleet Gateway
  3. Sign in to create your connection

Step 2: Create a Webhook

Create a webhook trigger called "github-pr" for GitHub pull request events

Fleet returns a URL like:

https://fleet-gateway.fly.dev/t/abc123xyz

Step 3: Configure GitHub

  1. Go to your GitHub repository → Settings → Webhooks
  2. Click Add webhook
  3. Paste the Fleet webhook URL
  4. Select Pull requests under events
  5. Save

Step 4: Create a PR Review Agent

Create an agent named "PR Reviewer":

You are a PR reviewer. When a pull request is opened:

1. Get the PR details from GitHub
2. Review the changed files
3. Check for issues (security, bugs, style)
4. Post a review comment with findings

Step 5: Bind with Parameter Mapping

triggers:
  - trigger: webhook:github-pr
    params:
      action: "{{body.action}}"
      pr_number: "{{body.pull_request.number}}"
      repo: "{{body.repository.full_name}}"
      branch: "{{body.pull_request.head.ref}}"
    enabled: true

Configure MCP for GitHub access:

mcp_servers:
  - github

secrets:
  - GITHUB_TOKEN

Part 4: Git Hook Automation

Run agents as part of your git workflow.

Step 1: Create a Git Hook Trigger

Create a pre-commit git hook trigger for ~/projects/my-app

The agent creates:

name: pre-commit-check
type: git_hook
git_hook_type: pre-commit
repo_paths:
  - ~/projects/my-app
pass_context: true

Step 2: Create a Pre-Commit Agent

Create an agent named "Commit Checker":

You are a pre-commit checker. Before each commit:

1. Review the staged changes
2. Check for:
   - Debugging code (console.log, debugger, print statements)
   - Hardcoded secrets or API keys
   - TODO comments that should be addressed
   - Obvious bugs or typos
3. If issues found, explain them and exit with code 1 to block the commit
4. If all looks good, exit with code 0 to allow the commit

Step 3: Configure for Blocking Behavior

Pre-commit hooks are blocking — they can prevent commits. The agent's exit code determines the outcome:

  • Exit 0: Allow commit
  • Exit 1: Block commit

The agent is interactive (user is at terminal), so it can ask clarifying questions.

Step 4: Bind the Trigger

triggers:
  - trigger: pre-commit-check
    enabled: true

Step 5: Test It

Make a change in your repository and commit:

git add -A
git commit -m "Test commit"

The agent will review your changes before the commit is created.

Combining Triggers

Agents can subscribe to multiple triggers:

triggers:
  # Run on schedule
  - trigger: daily-check
    enabled: true

  # Run on file changes
  - trigger: config-watcher
    enabled: true

  # Run on webhook
  - trigger: webhook:deploy-notification
    enabled: true

Managing Active Triggers

View Trigger Status

Go to Settings → Triggers to see:

  • All active triggers
  • Run history
  • Error logs
  • Last run time

Disable Temporarily

Toggle triggers off without deleting them:

triggers:
  - trigger: daily-summary
    enabled: false  # Disabled

Test Triggers

Use Run Now in Settings → Triggers to test any trigger without waiting for its event.

Troubleshooting

Trigger Not Firing

  1. Check if trigger is enabled
  2. Verify file patterns match (for file watchers)
  3. Check cron expression (for schedules)
  4. Verify webhook URL is correct (for webhooks)

Agent Not Responding

  1. Check agent has appropriate permissions
  2. Verify secrets are configured (for non-interactive triggers)
  3. Check run history for errors

Webhook Not Receiving Events

  1. Verify Fleet Gateway connection
  2. Check external service webhook configuration
  3. Look for delivery errors in the external service

Best Practices

Start Simple

Begin with one trigger and verify it works before adding complexity.

Use Appropriate Permissions

Non-interactive triggers need pre-approved permissions:

permissions:
  execution_tier: read_write
  rules:
    - "Bash(npm test)"
    - "Bash(git:*)"

Add Logging

Have agents log their actions for debugging:

After completing any task, append a log entry to ~/.fleet/automation.log
with the timestamp, trigger name, and summary of actions taken.

Handle Failures Gracefully

If you encounter an error:
1. Log the error details
2. Attempt recovery if possible
3. Continue with remaining tasks
4. Report failures in your summary

Next Steps