Core Features

AutomationsPro

Run agent sessions on a schedule or when something happens in GitHub, Slack, Linear, Sentry, Notion, Microsoft Teams, or a webhook

Overview

Automations run an agent session against a project when something happens (a review is requested, an issue is filed, a message lands in a channel) or on a schedule. A run that reaches a device produces a live workspace you or a teammate can open, review, and continue.

The Automations list with scheduled agent sessions

Typical uses:

  • Standups: a nightly summary of PRs, issues, and activity
  • Release notes: generate a draft from merged commits
  • Audits: scan for security issues or deprecated APIs each morning
  • Dependency sweeps: check for outdated packages weekly
  • PR reviews: review a pull request as soon as you're requested as a reviewer
  • Bug triage: reproduce a new Sentry issue or a report posted in #bugs

The list shows 7-day run health (successful, failed, and missed runs) and splits into Mine and Team tabs, plus an Archived tab once something is archived. Team automations are read-only; only the owner can edit, pause, run, group, or archive one.

Requirements

  • A Pro plan: Automations are a Pro feature. Creating, running, and resuming one needs a Pro or Enterprise subscription on the organization, from the app, CLI, or SDK. After a downgrade, automations stay and can be edited, paused, or archived, but they stop firing until the organization upgrades.
  • A project, or session mode: automations usually run against a v2 project linked to a GitHub repo. Pick No project and each run creates a session workspace instead.
  • A target device: the device you pick when creating the automation.
  • A connected integration, for event triggers: connect GitHub, Slack, Linear, Sentry, Notion, or Microsoft Teams from Integrations before you add one of its triggers. Microsoft Teams triggers need an Enterprise plan; every other trigger works on Pro.

Create an Automation

Click Automations → New automation and fill in:

  • Title: how the automation appears in the list
  • Prompt: the instructions the agent receives. Supports markdown, @file/path mentions (scoped to the selected project), :emoji: shortcodes, and / slash commands.
  • Device: which host runs the session. Defaults to this device. Pick Cloud to run each session in a new cloud workspace at the machine size you choose, or in an existing cloud workspace.
  • Workspace: New workspace (each run makes its own), Same workspace (the first run makes one and later runs reuse it), or a workspace you pick. With a shared workspace, Session mode chooses Start fresh (a new agent conversation each run) or Continue (the agent picks up where the last run left off).
  • Project: the v2 project the session runs against, or No project for a session per run.
  • Trigger: an event from a connected integration, a webhook, or a schedule. See Triggers.
  • Agent: Claude, Codex, Amp, or anything else you've set up under Settings → Agents.

Triggers

Triggers decide when an automation runs. They live in the Triggers card on the automation's detail page: Add Trigger opens a searchable menu of providers and events, and each trigger reads as a sentence you fill in, like "Review requested from Me in acme/web by Anyone". One automation can have up to 25 triggers and can mix events and schedules. Edits are drafts until you press Save.

Event triggers

An event trigger starts a run when the event arrives. Pick the provider, the event, and the scope it watches:

ProviderEventsScope and filters
GitHubPull request opened, pushed, merged, closed, review requested, or assigned; draft opened; comment added; PR review comment; PR review submitted; review thread resolved or unresolved; issue comment; label change; checks completed; workflow run completed; new push to branch; release published, created, edited, unpublished, or deletedOne repository (required), branches, labels, comment text, and people (Anyone, Me, or specific people)
SlackMessage in channel, reaction added, channel createdChannels (required, except for channel created), message text or new channel name, emoji (required for reaction added), people
LinearIssue created, status changed, or assigned; cycle endedTeams (required), projects, labels, status, assignee
SentryIssue created, resolved, assigned, archived, or unresolved; any issue eventProjects (required), level (Fatal, Error, Warning, Info, Debug)
NotionRows changed, comment added, comment mentions userData sources (required), pages, people
Microsoft TeamsMessage in channel, channel createdTeam (required), channels (required for message in channel), message or channel name text, people

Text filters are plain, case-insensitive "contains" matches against the first 4,096 characters, not regular expressions. Thread replies in Slack don't count as a message in channel.

GitHub triggers skip pull request events from forks (opened, pushed, reviews, review comments, threads), and a run never checks out a fork's branch. A top-level comment on a fork's pull request can still fire Comment added, and checks and workflow runs from fork pull requests still fire.

If the provider isn't connected, the trigger shows Requires connection with a Connect button; an expired connection shows Connection expired with a Reconnect button. A few providers need one extra step:

  • Slack: the Orca bot joins the public channels you pick when you save. For a private channel, invite @Orca to it first.
  • Notion: share the pages and data sources the automation should watch with the Orca integration.
  • Microsoft Teams: a tenant administrator grants consent once for the whole tenant.
  • GitHub: a trigger that filters by Me needs your personal GitHub account connected, or it won't fire.

Webhook triggers

A webhook trigger runs the automation when something sends a POST to its URL.

  1. Add a Webhook triggered trigger and save.
  2. Click Generate token, then Copy URL with token (or Copy auth header). The token starts with sset_wh_ and is shown once. Regenerate token asks you to confirm, then replaces it, and the old token stops working immediately.
  3. Send a JSON body to the URL, with the token as a bearer header or as a ?token= query parameter:
curl -X POST "https://api.orca.marcofaul.de/api/automations/webhook/<automationId>" \
  -H "Authorization: Bearer sset_wh_..." \
  -H "Content-Type: application/json" \
  -d '{"service": "checkout", "status": "failed"}'

The body must be a JSON object or array of at most 1 MiB; an empty body counts as {}. Each token can make 300 requests per minute. Responses: 200 when the delivery is accepted (the reply's runs field says how many runs it started; 0 means none did, for example on a plan without automations), 400 if the automation is paused or the body isn't JSON, 401 for a missing or invalid token, 413 for a body that's too large, 429 past the rate limit. Every request is a new event: webhook triggers have no filters and no de-duplication.

What the agent receives

The event's details come before your prompt: the provider, event type, title, URL, and actor, plus the event payload (capped at 24,000 characters). For a webhook it is the JSON body you sent. So a prompt like "Review this pull request and leave comments" knows which pull request to use. When a pull request event runs in a project linked to that repository, the run's workspace checks out the pull request's branch, and reuses that pull request's workspace if one exists. If the device can't fetch the pull request, the run starts on a fresh branch.

Guides

Schedules

Schedules are RFC 5545 RRules. The picker has presets for Hourly, Daily, and Weekly. Custom opens with an editable weekdays rule. Times use your timezone at creation, and each schedule shows its next run. Invalid rules, rules with no upcoming runs, and one-shot rules (COUNT/UNTIL) are rejected before saving.

Examples:

  • FREQ=DAILY;BYHOUR=9;BYMINUTE=0: every day at 9:00 AM
  • FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0: weekdays at 9:00 AM
  • FREQ=WEEKLY;BYDAY=FR;BYHOUR=17;BYMINUTE=0: every Friday at 5:00 PM

Runs

Each time an automation fires, a run is recorded on the detail page's Run History tab with a status:

  • created: the workspace was created on the target device (a run's success state)
  • creating: the handoff is in flight
  • missed: no device was online to take the run. It isn't retried
  • failed: the handoff broke. The error shows inline under the run, selectable for copying

The schedule advances to the next occurrence either way.

In "new workspace" mode, each run that starts gets a fresh workspace from the project's repo (or a session workspace when the automation has no project). Pull request events can reuse that pull request's workspace; see What the agent receives. Open it from the run row.

Pause, Run Now, Archive

From the automation's detail page (Settings tab):

  • Pause: flip the Active switch. Runs are kept, and each schedule row on a paused automation still shows when it would next run, so schedule edits are previewable.
  • Run now: dispatches immediately. The run appears under Run History within seconds.
  • Archive: in the ⋯ overflow menu. The automation stops firing and moves to the Archived tab; its run history is kept. Click Undo in the notification, or Restore on the Archived tab, to bring it back. A restored automation comes back paused, except through Undo, which also resumes it.
  • Delete permanently: only for an archived automation, from its ⋯ menu on the Archived tab or its detail page. This removes the automation and its run history and can't be undone.

Groups

Groups keep a long list in order. Right-click a row (or open its ⋯ menu) and pick Move to group. Pick a group, or choose New group… to name a new one. You can also just type: it filters the groups, and a name that matches none becomes Create group. The detail page's ⋯ menu has the same submenu, and its breadcrumb shows the group.

Once any of your automations has a group, the list shows a section for each group, sorted by name, with No group last. Click a section header to collapse it, or hover it and click + to create an automation already in that group. Search and sorting apply inside each section.

You can also drag a row onto another group's section to move it there, or onto No group to ungroup it. Drag one of several selected rows to move them all.

To remove a group, right-click its header and choose Delete group…; its automations move to No group and are not deleted.

A group only organizes the list. It does not change where runs go: the workspace tags under Settings do that.

Select Several

On the Mine tab, ⌘-click a row (Ctrl-click on Windows and Linux) to start selecting. Every row then shows a checkbox, and a bar at the bottom of the list can Move to group, Pause, Resume, or Archive everything selected. On the Archived tab, the same selection can Restore or Delete permanently.

  • ⌘-click adds or removes one row. With a row focused, X does the same.
  • Shift-click selects every row between the last one you picked and this one.
  • ⌘-click a group header selects the whole group, and ⌘A selects every row on screen.
  • Esc clears the selection, and the checkboxes go away with it.

Retry Failed Runs

On the Mine tab, Retry all appears in the header when any of your automations' latest run failed, and re-dispatches all of them. The Failed stat card filters to failing automations. Hover a row you own for Run now to re-dispatch one.

Limits

  • At-least-once delivery: a run may dispatch more than once in rare cases. Write prompts that are safe to re-run.
  • No agent-outcome tracking: a successful run means its workspace was created; the detail page doesn't show whether the agent's work succeeded. Open the workspace to see what happened.
  • Offline hosts miss the run: if the target device is offline, the run is recorded as missed. Keep the device online to catch every event.
  • Watch for loops: an agent's own activity can match its trigger, for example a review comment on a PR that a "Comment added" trigger watches. Use the trigger's people filter so the agent's own activity doesn't start new runs. Slack triggers already ignore the Orca bot's own messages and reactions.
  • One prompt per automation: for different prompts, create more automations.

CLI

orca automations list
orca automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project <projectId> --prompt-file prompt.md --agent claude

# Omit --project and --workspace for session mode (a session workspace per run)
orca automations create --name "Scratch triage" --rrule "FREQ=DAILY;BYHOUR=8;BYMINUTE=0" --prompt "…"

# Each run's workspace carries the automation's tags and groups into the matching
# sidebar folders. Default tag: "automation". Runs collect in an "automation"
# folder per project. --tag (repeatable) files them elsewhere; clearing the tags
# in the editor opts out of grouping.
orca automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project <projectId> --prompt "…" --tag audits

# Groups organize the automations list; they don't affect where runs go.
orca automations update <automationId> --group "Nightly jobs"
orca automations list --group "nightly jobs"
orca automations update <automationId> --clear-group

# Event triggers: pass the trigger set as a JSON array with --triggers or --triggers-file.
# trigger-options lists the ids a provider's filters accept (channels, repos, teams, ...).
orca automations trigger-options --group slack
orca automations create --name "Triage #bugs" --project <projectId> --prompt-file triage.md \
  --triggers '[{"config":{"kind":"slack","event":"reaction_added","channels":{"mode":"list","ids":["C123"]},"emoji":{"mode":"list","ids":["bug"]},"actor":{"mode":"any"}}}]'

# update --triggers replaces the whole set: include each existing trigger's id to keep it.

orca automations update <id> --session   # switch an existing automation to session mode
orca automations get <id>
orca automations run <id>
orca automations pause <id>
orca automations resume <id>
orca automations archive <id>     # stops it and hides it; runs stay
orca automations list --archived
orca automations unarchive <id>   # restores it, paused
orca automations delete <id>      # permanently deletes an archived automation

On this page