Scheduling Agents

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:

Fires on a schedule (daily, weekly, every 15 minutes, etc.)
Invokes the hypertask CLI (or calls the MCP server directly)
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.

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.

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:

npm install -g hypertask_cli

Verify:

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:

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:

crontab -e

Add:

# 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:

#!/bin/bash
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:

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:

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:

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:

wrangler secret put HYPERTASK_API_TOKEN
wrangler deploy

Example 4 — Vercel cron

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

Add to vercel.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):

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

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.

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.

Scheduling orientation: Agents and next-task queue

In addition to general-purpose agent workflows, you can configure agents to pull from a priority-scored next-task queue and act on their assigned tickets. The priority score reflects task urgency and value, and the queue exposes only claimable rows to prevent conflicts.

To schedule a dedicated next-task queue agent:

Set up an external scheduler (GitHub Actions, cron, Cloudflare Worker, Vercel cron, etc.).
Have the scheduler disable the agent’s ability to create unlimited tasks, and instead provide only a single-purpose command or endpoint for conditional next-task pulls (examples using the hypertask CLI or MCP are included in the other workflow patterns above).
On each run, the scheduler invokes an endpoint that:
- Pulls ranked candidate tasks from the next-task queue for this board,
- Checks that tasks are claimable by this agent (not already assigned),
- If one or more candidate tasks are available, the scheduler creates a conditional task or comment for the agent:
  - With a conditional, the agent can pick up and claim one task from the queue on demand (default is the highest-priority available).
In the MCP or CLI flow, wrap the queue endpoint call to honor the scheduler’s condition. Use a Context (via hypertask_get_user_context) or an explicit owner ID to ensure the agent is authorized to claim the returned tasks. Treat the queue response as authoritative; update or close the created/conditional task as soon as the agent completes the work.

Recommended pattern on the MCP side

On every scheduled run, the scheduler calls a tool like hypertask_next_task_pull with filtering options that ensure the results are claimable by this agent, then applies the scheduler’s schema (e.g., agent_id or team_id). If the tool returns candidates, the routine for that agent creates a temporary task or comment to indicate it is ready to claim before it gets claimed; if the tool returns empty, the scheduler can sleep and retry on the next interval.

When using code:

From the scheduler: call the endpoint; from an agent context: invoke the MCP tool.
After picking a task, the subsequent workflow should mark it as claimed (assign the agent owner) and transition the task to its normal workflow section; once the agent finishes, it can update the task, close the conditional slot, or delete the task as appropriate, then return to the queue endpoint for the next candidate.

Example CLI flow (from a scheduler):

#!/bin/bash
export HYPERTASK_API_TOKEN="xxxx"

hypertask next-task pull \
  --board-id 15 \
  --limit 3 \
  --min-priority urgent,high \
  --exclude-assigned-owners robotic-agent-foo,robotic-agent-bar \
  | jq -r '.tasks[] | "Assign to robotic-agent-foo: " + .title' | while read line; do
    hypertask tasks update \
      --ticket-number "$line" \
      --assign_self true \
      --section "Doing" \
      --description "<p>Next-task from queue (by scheduler).</p>"
  done

This ensures:

Only tasks not already claimed are visible,
Priorities guide which tasks first,
The scheduler’s condition gates behavior,
Agents run from an explicit, manageable queue.