Run an agent on a schedule

Wake up to triaged issues, test results, or a dependency update. Run an agent once or on repeat, or have a script run first before an agent.

Download for macOS
Hand this to your agent
Ask me about each of these, one at a time, with a suggested default:
- Job (what each run does; a script can check first and start an agent only when there's work)
- When (e.g. weekdays at 9am, with your timezone)
- Results (one thread for reports, or a new worktree each run for code changes)
- Notifications (yes or no)
Skip any I've answered. Then sum up the plan in three bullets and wait for my go. My answers override the steps below.
If a wait times out, wait again, up to three times.

Set up a bb automation for this project and test it once.
Guide: https://getbb.app/guides/run-an-agent-on-a-schedule

Default Job: morning issue triage on weekdays at 9am, with reports in one thread. Ask for my timezone. Pass --project $BB_PROJECT_ID to every bb automation command. If a step fails, stop and tell me the error.

1. Read `bb automation create --help`. Turn on the Automations plugin if `bb plugin list` shows it's off. For an agent job, pick a model from `bb provider models <provider> --json`.
2. If `bb automation list` already has this job, reuse it and skip to step 4.
3. Create it paused: `bb automation create --name '<name>' --disabled` with `--cron '<expression>' --timezone <IANA zone>` or `--at <ISO time>`, plus either:
   - Agent: `--prompt '<prompt>' --provider <provider> --model <model> --permission-mode auto`. For reports in one thread, start that thread with `bb thread spawn` and add `--target-thread <its ID>`. For code changes, add `--new-environment worktree` and tell it not to push.
   - Script: `--script-file <path>`. It starts an agent with `"$BB_CLI" thread spawn` only when there's work, and prints nothing otherwise.
4. Test it with `bb automation run <id>`, then read the run's thread or output. If it doesn't do the job, leave it paused and tell me why.
5. Turn it on with `bb automation resume <id>`, asking me first for a one-time job. If Notifications is yes, send `bb push-notifications test web` and ask me to confirm it arrived.

Reply with the automation ID, schedule, next run, and what the test produced.

Steps

  1. 1Open Automations
  2. 2Describe the job
  3. 3Run it now, then turn it on
  4. 4Get notified when it finishes
1

Open Automations

Every scheduled job lives in one list, with its next run and an on/off switch.

  1. Choose Automations in the sidebar.
  2. Choose New automation. A new thread opens with the sentence started for you. Or start from a template in Browse.
2

Describe the job

Describe what to do, when, and where the results go. Your agent sets it up.

Does the job need a site you're signed in to, like Linear or your analytics? Import your browser logins into bb first.

Check with a script first, and wake an agent only when there's work

Ask for a script instead, like “every 15 minutes, check main for a failed CI run, and if there is one, start a Codex thread to fix it.” Scripts run without a model, so frequent checks use none of your plan. Quiet runs show as skipped.

Run it once, later

Ask for a single run, like “tomorrow at 9am, draft release notes from this week's pull requests.” It shows as One time in Automations.

Send one message later

Type the message, open the arrow next to the send button, and choose Send later… to pick when it goes to this thread.

3

Run it now, then turn it on

You don't have to wait until morning to find out whether it works.

  1. Open the automation and choose Run now.
  2. Under Runs, open the run and read the report.
  3. Once it's right, switch the automation on. To change what it does, choose Edit prompt.
4

Get notified when it finishes

Open the report from a notification, or come back to the thread later.

  1. Open Settings → Push notifications.
  2. Turn on Web notifications or Desktop notifications, and choose Allow notifications.
  3. For your phone, keep Mobile notifications on and pair the bb app in Settings → Mobile. See Work from anywhere.
  4. Check that a notification arrives the next time a run finishes.

Troubleshooting

My automation didn't run
  1. Open it in Automations and check that its switch is on and the next run time is right.
  2. Check that bb and the computer running the agent were awake at that time. Scheduling doesn't wake a sleeping computer; a missed run happens once when it's back.
  3. Choose Run now. If that works, the schedule or the computer was the problem.
My automation turned itself off
  1. Open its latest runs. Three failures in a row pause an automation.
  2. It also pauses if the thread it posts to was archived, deleted, or stuck on a failed turn.
  3. Fix the cause, choose Run now to check it, then switch it back on.
A run failed
  1. Open the run under Runs and read its error.
  2. If the agent hit its usage limit, schedule heavy jobs overnight or use a script to skip runs with nothing to do.
  3. If the agent isn't signed in on that computer, sign in once, then choose Run now.
I get a new thread every morning

That's the default. Ask your agent to post every run to one thread, like “send the morning triage to this thread.” Keep that thread for reports only.

Every script run shows as skipped

A script that exits without printing anything counts as skipped. Have it print a short result when there's something to report. A script that exits with an error or times out shows as failed; open the run to read its output.

The notification never arrived
  1. Web and desktop notifications need an open bb tab or app window.
  2. Check the browser's notification permission and your device's Focus settings.
  3. For notifications with the app closed, pair the bb mobile app in Settings → Mobile.

FAQ

What can I automate?
  • Triage new issues every morning and post a summary.
  • Run the test suite nightly and fix what broke.
  • Update dependencies weekly and open a pull request.
  • Watch CI and start an agent when main goes red.
  • Write release notes from the week's merged pull requests.
What's the difference between an agent and a script?

An agent automation sends a prompt to the agent and model you pick, and uses your plan each run. A script runs on the bb server with no model, so it's free to run often, and it can start agent threads when it finds work.

Which agents work?

Claude Code, Codex, and Pi are built in. Cursor, opencode, and other agents that support the Agent Client Protocol, like Grok Build and Hermes Agent, work once they're installed.

How do I change an automation later?

Open it in Automations. Choose Edit prompt for an agent automation, or Edit with chat for a script. To change the schedule, ask your agent, like “move the morning triage to 8am.”

Can an automation change code or open pull requests?

Yes. Ask for a new worktree on every run, so each run gets its own branch, and say in the prompt whether it should push, open a pull request, or leave the change for you.

Have the report ready by morning

Free and open source. Use the agents and machines you already have.

Download for macOSApple Silicon · Also for Linux (Alpha)bb runs on macOS, Windows, and LinuxWindows (Alpha), Intel Macs & remote machines