Routines

A routine is work a bot does on its own, on a schedule, in its direct chat with you.

Set one up

Ask the bot:

Every weekday at 9, check the CI status of my three repos and tell me what is red.

The bot creates the routine: a name, a schedule, and a prompt it writes as an instruction to itself. Edit, pause, or delete it the same way: "Move my morning brief to 8:30."

Schedules

A routine runs at an interval (every 30 minutes, every 2 hours, every day) or at set times (weekdays at 9:00, the 1st of every month at 8:30). The shortest interval is five minutes. It can also:

• Run once at a date and time: "Remind me on Monday at 9 to renew the certificate." Once it has run, the routine removes itself; the chat keeps the run.
• Watch a pull request: see below.
• Run when its webhook is called: see below.
• Run around calendar events: see below.

Timezones

A routine keeps the timezone it was made in, the Runner's unless you name another: "every weekday at 9 New York time". Traveling, or moving the Runner to another timezone, leaves its hours as they were, and daylight saving time is handled: a skipped hour doesn't run that day, and a repeated one runs once. When your computer keeps other hours than the routine, its sheet names the routine's timezone, such as "New York time".

Missed runs

When the Runner was off or asleep at a run's time, the routine either runs once for everything it missed when the Runner is back (Run once, the default) or waits for its next time (Skip). It never runs once per missed time. Ask the bot to change it.

What a run looks like

A run opens with a Routine · Name marker in the bot's direct chat. The bot does the work and replies with what you should know. If there is nothing worth saying, it passes and only the marker remains.

You get a notification for a run that says something, like any other reply.

A routine that watches for something, such as an inbox, a feed, or a page, can check first without the model: the bot writes a short check that only reads, and a run starts only when the check finds something new. A quiet hour costs nothing.

Pull request watches

"Watch acme/project#42 and tell me when it changes." The bot runs once for each thing that happens on the pull request, as it happens, and says what it means for you:

• new commits, a new title or description, ready for review, back to draft, reopened
• a review (approved, changes requested, or comments), a review comment, a comment, a review thread resolved or reopened
• a failed check, check suite, workflow run, or commit status

GitHub sends these to Lorca through the Lorca GitHub App. The first time you watch a pull request in a repository, the routine says App not installed: click Install App… on its GitHub row, choose the repository on GitHub, and approve the sign-in. Where the App is installed already, by you or an organization's owner, you only approve the sign-in. The page you land on says whether it worked, and the watch starts as soon as you're back in Lorca. Lorca watches only repositories your GitHub account can see. The App only reads (pull requests and their comments, checks, statuses, and workflow runs) and changes nothing; the bot reads the pull request through your own GitHub plugin when it runs.

When the pull request merges or closes, the bot runs one last time and the watch removes itself. GitHub sends nothing when the base branch moves on and makes a conflict, so a watch doesn't notice that.

The routine's sheet shows the pull request, which opens on GitHub, how it hears from GitHub (Connected, or Install App…), and its Last event.

Webhooks

"Make a routine that runs when my deploy script calls it, and tell me why the deploy failed." A routine can run each time a service or a script sends a request to its own URL. Its sheet has a Webhook section:

Each row has Copy. Paste the URL and the header into the service, or call it yourself:

curl -X POST "https://relay.lorca.app/webhooks/5VPZsRAyy2VIu_yNsFDw2g" \
  -H "Authorization: Bearer $LORCA_WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deploy": "web", "status": "failed"}'

Each request runs the routine once, and the bot reads what it sent, JSON or text up to 64 KiB, as information, never as instructions. A request without the key is turned away. Send an Idempotency-Key header to have a retried request run once. A webhook takes a request a second, in bursts of up to 30.

Regenerate… beside the key (Regenerate Key… on the phone) makes a new one; services with the old key stop reaching the routine until you give them the new one. Deleting the routine deletes its URL.

Lorca's relay reads a request while it encrypts it for your Runner, then keeps only the encrypted copy.

Calendar events

"Fifteen minutes before each customer call, brief me on the customer." A routine can run a set time before an event starts, at its start, or after it ends, for the events of a Google Calendar account on the Runner, or only those with certain words in them. It runs once for each matching event, with that event. All-day events, events you declined, and focus time are left out. The routine's sheet names the account and the next event it will run for.

One-time routines, watches, webhooks, and calendar routines belong to your account, so a shared bot and a workflow carry only repeating routines.

Manage routines

The bot's inspector has a Routines section: each routine with its schedule in words, its next run, and a switch that pauses or resumes it. The symbol says what places its runs: a clock, an alarm for a one-time routine, a pull request, a link for a webhook, or a calendar. Click one for its sheet: its state, the schedule, the next run, Missed runs, the last check and run, a Limits row, the prompt and the check, and Run Now, Pause, Edit in Chat, and Delete. A watch and a webhook have no next run or missed runs: their events start them, and wait up to seven days for your Runner while it is off. The phone shows the same list in the chat's Details; ask the bot in the chat to edit a routine there.

Routines run on the bot's Runner, so that computer has to be on. Settings › Devices says whether a Runner keeps Lorca running in the background (see Command line).

When something goes wrong

A routine that needs you says so first in its row, in orange while you have to act:

The sheet explains what happened and how to fix it.

When you are away

If you have not written in any chat for seven days, due routines pause themselves and leave a note in the bot's chat, so nothing keeps spending on results nobody reads. Flip the switch to turn one back on.