# Scheduling Agents

Run Hypertask agents on a schedule using any external scheduler — GitHub Actions, crontab, Cloudflare Workers, or Vercel cron.

import { Aside, Tabs, TabItem, Steps } from '@astrojs/starlight/components';

Hypertask does not ship a built-in cron UI. It does not need one. Hypertask exposes a CLI and an MCP server, so any scheduler that can run a command on a schedule can trigger an agent run.

This guide shows four common ways to schedule a recurring agent run. Pick the one that matches where your stack already lives.

## What "scheduled agent run" means

A scheduled agent run is any workflow that:

<Steps>

1. Fires on a schedule (daily, weekly, every 15 minutes, etc.)
2. Invokes the `hypertask` CLI (or calls the MCP server directly)
3. Asks the agent to do something against your board — triage inbox, post a daily standup, summarise last week's shipped tickets, auto-close stale bugs, etc.

</Steps>

The agent runs, writes its result as a comment or a new task, and the scheduler moves on. No Hypertask-side cron engine is needed.

<Aside type="tip">
If you can write a one-liner shell command that does what you want, you can schedule it.
</Aside>

## Prerequisites

You need:

- The `hypertask` CLI installed on the machine (or runner) that will execute the schedule
- A Hypertask API token — export as `HYPERTASK_API_TOKEN`
- A project ID to act on

Install the CLI:

```bash
npm install -g hypertask_cli
```

Verify:

```bash
hypertask tasks list --project <your-project-id>
```

## Example 1 — GitHub Actions

Best for teams already on GitHub. Free for public repos, generous free tier for private.

Create `.github/workflows/daily-standup.yml`:

```yaml
name: Daily standup agent

on:
  schedule:
    - cron: '0 8 * * 1-5'   # 08:00 UTC, weekdays
  workflow_dispatch:         # allow manual runs

jobs:
  standup:
    runs-on: ubuntu-latest
    steps:
      - name: Install Hypertask CLI
        run: npm install -g hypertask_cli

      - name: Run standup agent
        env:
          HYPERTASK_API_TOKEN: ${{ secrets.HYPERTASK_API_TOKEN }}
        run: |
          hypertask tasks create \
            --project 15 \
            --title "Daily standup $(date -u +%Y-%m-%d)" \
            --description "<p>Auto-generated by GitHub Actions. HyperAI, please summarise yesterday's shipped tickets.</p>"
```

Store the API token as a repository secret named `HYPERTASK_API_TOKEN`.

## Example 2 — crontab on a Linux server

Best if you already have a VPS or home server running 24/7.

Edit your crontab:

```bash
crontab -e
```

Add:

```cron
# Triage inbox every 15 minutes
*/15 * * * * /usr/bin/env HYPERTASK_API_TOKEN=xxxx hypertask tasks create --project 15 --title "Inbox triage" --description "HyperAI please scan the inbox and classify."

# Weekly summary Mondays at 09:00
0 9 * * 1 /usr/bin/env HYPERTASK_API_TOKEN=xxxx hypertask tasks create --project 15 --title "Weekly summary" --description "HyperAI please summarise last week's wins."
```

Use a wrapper script instead of inline commands when they get longer than one line:

```bash
#!/bin/bash
# /home/you/hypertask-cron/weekly-summary.sh
export HYPERTASK_API_TOKEN="xxxx"
hypertask tasks create \
  --project 15 \
  --title "Weekly summary $(date -u +%Y-W%V)" \
  --description "HyperAI please summarise last week's shipped tickets and flag any that are overdue."
```

Then in cron:

```cron
0 9 * * 1 /home/you/hypertask-cron/weekly-summary.sh
```

## Example 3 — Cloudflare Workers cron

Best if you want zero-infra, run-anywhere scheduling and already use Cloudflare. Free tier covers 100k invocations per day.

Create `wrangler.toml`:

```toml
name = "hypertask-scheduler"
main = "src/index.ts"
compatibility_date = "2026-04-01"

[triggers]
crons = ["0 8 * * 1-5"]   # 08:00 UTC weekdays
```

Create `src/index.ts`:

```ts
export default {
  async scheduled(_event: ScheduledEvent, env: Env) {
    const today = new Date().toISOString().slice(0, 10);

    await fetch('https://app.hypertask.ai/api/tasks', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${env.HYPERTASK_API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        projectId: 15,
        title: `Daily standup ${today}`,
        description: '<p>Auto-generated by Cloudflare Workers.</p>',
      }),
    });
  },
};

interface Env {
  HYPERTASK_API_TOKEN: string;
}
```

Deploy:

```bash
wrangler secret put HYPERTASK_API_TOKEN
wrangler deploy
```

<Aside type="note">
Cloudflare Workers cron runs on Cloudflare's infrastructure, so you do not ship the Hypertask CLI to the worker. Call the HTTP endpoint directly or use the MCP server.
</Aside>

## Example 4 — Vercel cron

Best if your app already runs on Vercel. Free tier covers 2 cron jobs.

Add to `vercel.json`:

```json
{
  "crons": [
    {
      "path": "/api/hypertask-standup",
      "schedule": "0 8 * * 1-5"
    }
  ]
}
```

Create `pages/api/hypertask-standup.ts` (or `app/api/hypertask-standup/route.ts` for App Router):

```ts
export default async function handler(req, res) {
  if (req.headers.authorization !== `Bearer ${process.env.CRON_SECRET}`) {
    return res.status(401).end();
  }

  const today = new Date().toISOString().slice(0, 10);

  await fetch('https://app.hypertask.ai/api/tasks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HYPERTASK_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      projectId: 15,
      title: `Daily standup ${today}`,
      description: '<p>Auto-generated by Vercel cron.</p>',
    }),
  });

  res.status(200).json({ ok: true });
}
```

Set `HYPERTASK_API_TOKEN` and `CRON_SECRET` in the Vercel project environment variables.

## Common patterns

<Tabs>

<TabItem label="Daily standup">

Fire at 08:00 weekdays. Ask the agent to summarise what shipped yesterday and what is blocked. Posted as a new task in a "Standups" section.

</TabItem>

<TabItem label="Inbox triage">

Fire every 15 minutes. Ask the agent to classify new inbox items (bug, feature, question, noise) and auto-archive noise.

</TabItem>

<TabItem label="Stale ticket cleanup">

Fire weekly Sundays. Ask the agent to move any Backlog ticket untouched for 60 days into an "Archive" section.

</TabItem>

<TabItem label="Weekly win recap">

Fire Mondays at 09:00. Ask the agent to summarise last week's shipped tickets into a single "Weekly wins" task, for use in team updates or marketing.

</TabItem>

</Tabs>

## Choosing a scheduler

| Scheduler | Use when |
|---|---|
| GitHub Actions | You already use GitHub and want CI-grade reliability. |
| crontab | You have a VPS or home server running 24/7 and like full control. |
| Cloudflare Workers | You want zero-infra scheduling at the edge. |
| Vercel cron | Your app already runs on Vercel and you want crons living next to your routes. |

## What about a native cron UI in Hypertask?

Not planned for now. Every workflow above is a few lines of config away, and the external-scheduler approach gives you logs, retries, alerts, and secret management for free. If you have a use case the external pattern does not cover, open an issue on the GitHub repo so we can see the gap.