Documentation Index
Fetch the complete documentation index at: https://mintlify.com/lvndry/jazz/llms.txt
Use this file to discover all available pages before exploring further.
What are workflows?
Workflows are scheduled, automated agent tasks. They’re Markdown files that describe what an agent should do, when it should run, and how much autonomy it gets. Think of workflows as cron jobs for AI agents—recurring tasks that run automatically without your intervention.Why workflows?
Some tasks should happen regularly without you having to remember:- Email cleanup: Archive newsletters and promotions every hour
- News digests: Compile tech news every morning
- Weather briefings: Get weather + outfit recommendations before you start the day
- Market analysis: Daily stock/crypto analysis with signals
- Code reviews: Automated PR reviews in CI/CD
- Standup prep: Summarize your work each morning
Built-in workflows
Jazz ships with production-ready workflows:| Workflow | Schedule | Purpose |
|---|---|---|
| email-cleanup | Hourly | Archive newsletters, organize promotions, flag important messages |
| tech-digest | Daily 8 AM | Scan AI/tech news sources and compile a personalized digest |
| weather-briefing | Every morning | Weather forecast + outfit recommendations for your location |
| market-analysis | Daily | Stock/crypto analysis with buy/sell signals |
Workflow structure
Every workflow is aWORKFLOW.md file with YAML frontmatter:
Frontmatter options
name (required)
name (required)
Unique identifier for the workflow.
description (required)
description (required)
Human-readable description of what the workflow does.
schedule (optional)
schedule (optional)
Cron expression for when to run. If omitted, workflow is manual-only.See cron syntax for expressions.
agent (optional)
agent (optional)
Which agent to use. Defaults to
default.autoApprove (optional)
autoApprove (optional)
Auto-approval policy for unattended execution:See Auto-approval for details.
false- Always ask (workflow will pause)read-only- Auto-approve reading files, searching, web requestslow-risk- Also auto-approve archiving email, creating calendar eventshigh-risk- Also auto-approve file changes, shell commands, git pushtrue- Auto-approve everything
skills (optional)
skills (optional)
Skills to preload for this workflow.
maxIterations (optional)
maxIterations (optional)
Maximum agent iterations. Defaults to 50.
catchUpOnStartup (optional)
catchUpOnStartup (optional)
Whether to run missed workflows when Jazz starts. Defaults to
false.maxCatchUpAge (optional)
maxCatchUpAge (optional)
Max age (seconds) for catch-up runs. Defaults to 86400 (24 hours).
Creating workflows
Manual creation
Create a directory andWORKFLOW.md file:
WORKFLOW.md with frontmatter and instructions.
Using the create-workflow skill
Running workflows
List workflows
Run manually
Schedule
- Registers the workflow with your system scheduler (cron on Linux, launchd on macOS)
- Creates a scheduled job using the
schedulefrom frontmatter - The workflow runs automatically at the specified times
Scheduled workflows run even when your terminal is closed. They’re managed by the system scheduler.
Unschedule
Example workflows
Email cleanup (hourly)
Fromworkflows/email-cleanup/WORKFLOW.md:
Tech digest (daily)
Fromworkflows/tech-digest/WORKFLOW.md:
- Runs at 8 AM daily
- Uses the
deep-researchskill for multi-source research - Auto-approves all actions (safe for read-only research)
- Catches up on startup if the system was off at 8 AM
- Saves results to organized markdown files
Workflow discovery
Workflows are discovered from multiple sources with priority:- Local (highest):
./workflows/in your project - Global:
~/.jazz/workflows/ - Built-in (lowest): Shipped with Jazz
Catch-up mechanism
If your machine was asleep when a workflow was scheduled:- The 7 AM run was missed
- Less than 2 hours old → runs automatically
- More than 2 hours old → skips (too stale)
Auto-approval policies
Workflows run unattended, so auto-approval is critical:Policy levels
| Policy | What’s auto-approved |
|---|---|
false | Nothing—always asks (workflow pauses) |
read-only | Reading files, searching, web requests |
low-risk | + Archiving email, creating calendar events |
high-risk | + File changes, shell commands, git push |
true | Everything |
Policy selection guide
Research workflows:true or read-only
low-risk
read-only or manual approval
high-risk or manual approval
Workflow service API
For programmatic access:CI/CD integration
Run workflows in your CI/CD pipelines:--output raw: Disables interactive UI (suitable for CI)--auto-approve: Runs without prompts (uses workflow’s autoApprove policy)
Best practices
Start conservative
Begin withread-only approval:
Clear instructions
Be specific about what the agent should do:Safety guards
Add explicit safety rules:Iteration limits
Set appropriate limits:Test locally
Always test workflows manually first:Use skills
Preload relevant skills for consistency:Troubleshooting
Workflow doesn’t run
- Check schedule syntax: Use crontab.guru to verify
- Verify scheduling:
jazz workflow listshould show “Scheduled: Yes” - Check system scheduler:
- Linux:
crontab -l - macOS:
launchctl list | grep jazz
- Linux:
Workflow pauses
If a workflow stops and waits:- It needs approval for a tool
- Increase
autoApprovelevel or add specific tools to allow-list - Review workflow instructions—they might request unsafe operations
Workflow fails
- Check logs: Workflow output is logged
- Run manually:
jazz workflow run <name>to see errors interactively - Verify agent: Ensure the specified agent exists
- Check iteration limit: Increase
maxIterationsif needed
Missed runs
If workflows don’t catch up:- Check
catchUpOnStartup: truein frontmatter - Check
maxCatchUpAgeisn’t too restrictive - Verify system time is correct
Next steps
Agents
Configure agents for workflow execution
Skills
Add expertise to your workflows
Auto-approval
Fine-tune workflow autonomy
CI/CD Guide
Run workflows in automation pipelines