Routines

Routines are server-side automation hooks that spawn the orchestrator with a specific issue context — even when your desktop app is closed. Unlike Heartbeats (which require the app to be open), Routines fire from Agenties cloud automation via schedule, API call, or GitHub webhook.

Routine types

Type	Trigger	Use case
`schedule`	Cron expression handled by Agenties cloud automation	Daily summaries, dependency checks, end-of-week reports — fires even when app is closed
`api`	HTTP POST to a unique fireUrl	CI/CD integration, custom tooling, external automations
`github`	GitHub webhook (issues, PRs, comments)	Auto-assign issues from GitHub to the orchestrator, respond to PR comments

Routine structure

TypeScript

interface Routine {
  id: string;                    // "rt_<nanoid>"
  name: string;
  type: "schedule" | "api" | "github";
  enabled: boolean;

  // Schedule type
  cronExpr?: string;             // e.g. "0 8 * * 1-5"

  // API and GitHub types
  fireUrl?: string;              // Unique webhook URL generated by Agenties
  fireToken?: string;            // Bearer token for authentication

  // All types
  issueTitle?: string;           // Pre-fill issue title when firing
  issueBody?: string;            // Pre-fill issue body / context
  model?: string;                // Override model for this routine's orchestrator turn
  effort?: string;               // Override effort

  createdAt: string;
  lastFiredAt?: string;
  lastSessionUrl?: string;       // URL to the last spawned session
}

API routines

API routines generate a unique fireUrl and fireToken. Any HTTP client can trigger the routine by posting to this URL:

bash

curl -X POST https://agenties.app/api/routines/rt_abc123/fire \
  -H "Authorization: Bearer <fireToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "issueTitle": "Deploy new release",
    "issueBody": "Triggered by CI after passing all checks. Tag: v2.1.4",
    "context": { "tag": "v2.1.4", "commitSha": "abc123" }
  }'

Agenties creates an issue from the provided title and body, then sends it to the Agenties desktop app (if online) or queues it for delivery when the app next connects.

Response

JSON

{
  "ok": true,
  "routineId": "rt_abc123",
  "issueId": "issue_789",
  "sessionUrl": "agenties://project/proj_xyz/session/sess_123"
}

The sessionUrl can be used to deep-link into the Agenties app and view the spawned session.

GitHub routines

GitHub routines connect a GitHub repository webhook to a routine's fireUrl. Supported webhook events:

GitHub event	When it fires	What gets injected
issues.opened	New issue created	Issue title, body, labels, and URL
issue_comment.created	Comment mentioning @agenties	Comment body and parent issue context
pull_request.opened	New PR created	PR title, description, diff URL, and reviewer request
pull_request_review.submitted	Review requested changes	Review comments and diff context

Setup

1.Create a GitHub routine in Agenties → Routines tab.

2.Copy the generated fireUrl.

3.In your GitHub repository: Settings → Webhooks → Add webhook.

4.Paste the fireUrl as the Payload URL. Set Content type to application/json.

5.Select the events you want to trigger the routine.

6.Copy the fireToken into the Secret field.

Note:GitHub webhook signatures are verified using the fireToken as the HMAC-SHA256 secret. Agenties rejects any webhook that fails signature validation.

Manual fire

Every routine can be fired manually from the Routines tab by clicking the Fire nowbutton. You can optionally provide a custom issue title and body to override the routine's defaults. This is useful for testing routines before hooking them up to GitHub or a CI system.

How the orchestrator receives routine fires

When Agenties receives a routine fire, it:

Flow

1. Creates an issue in the project's issue tracker with the injected context
2. Sends a realtime WebSocket event to the project channel (project:<projectId>)
3. The Agenties desktop app receives the event and triggers an orchestrator turn
4. The orchestrator reads the new issue and begins delegating work
5. The sessionUrl returned by the fire endpoint deep-links to this turn

If the desktop app is offline when the routine fires, the issue is queued by Agenties and delivered the next time the app connects and syncs.

← PreviousHeartbeats Next →Issues