How to Run the Same Claude Code Agent on a Schedule and on Demand

A practical field guide from Automation Ace.

Short answer: to run the same Claude Code agent on a schedule and on demand, create one cloud scheduled task (formerly a routine) and attach several triggers to it: a schedule for the recurring run, an API trigger so alerts, CI, or Zapier, Make, and n8n can start it, and Run now for manual runs. Write one prompt that checks whether a routine-fire-payload block is present: if it is, handle that specific request; if not, do the full scheduled sweep. Make the work safe to repeat so overlapping runs update the same pull request instead of opening duplicates.

Scheduled tasks were in research preview at the time of writing, and limits and behavior may change; see the Claude Code documentation for the current details.

Short answer

1. One task: same repo, environment, connectors, and prompt.
2. Several triggers: schedule + API (+ GitHub events, if useful).
3. One prompt with two modes: payload present or not.
4. Idempotent output: find and update existing PRs or issues.
5. Keep the last-run state somewhere durable, updated by scheduled runs.
6. Watch the shared hourly limits and review History.

Why one task with several triggers

• One definition to maintain: the prompt, repos, environment, and connectors live in one place.
• Consistent behavior: a 2 AM run and a run started from a deploy follow the same rules.
• Faster response: the schedule is a safety net; the API trigger lets urgent cases skip the wait.
• One History: every run, however it started, appears on the same task page.

For when scheduled vs event-driven work makes sense in general, see event-driven vs scheduled vs request-response automations.

The triggers a task can have

Step 1: Create the task with a schedule

• From the web: at claude.ai/code/routines, create a task, pick the repository, cloud environment, model, and connectors, and choose a Schedule trigger with a preset frequency.
• From the CLI: run /schedule and describe it, for example /schedule nightly docs drift check at 2:15am. Claude asks follow-up questions and saves the task to your account. (/routines is an alias.)
• Custom cadence: after creating the task, choose Custom in the edit dialog and enter a cron expression, or use /schedule update.

Step 2: Write one prompt for both kinds of run

Scheduled runs start with no payload. API and Run now calls can include text, which Claude Code wraps in a <routine-fire-payload> block marked as untrusted. Claude only acts on it if your saved prompt says to, so make both modes explicit:

You maintain the docs for the api-server repository.

HOW THIS RUN STARTED
- If a routine-fire-payload block is present, this is an on-demand run.
  It names a pull request, a branch, or an API area. Check only that scope.
- If no payload is present, this is the scheduled nightly run. Check every
  pull request merged since the time in .claude/state/docs-last-run.txt
  (or the last 24 hours if the file is missing).

WHAT TO DO IN BOTH CASES
1. Find documentation that references changed endpoints, parameters, or
   behavior.
2. Before opening anything, search for an open pull request labeled
   "docs-drift" that covers the same files. If one exists, push to it
   instead of opening a new one.
3. Open or update a pull request labeled "docs-drift" with the fixes and
   a summary of what changed and why.
4. On scheduled runs only, update .claude/state/docs-last-run.txt in that
   pull request with the current UTC time.

RULES
- Never merge pull requests or edit files outside /docs and .claude/state.
- If nothing needs changing, say so in one line and stop.

The payload can narrow the work, but the prompt decides what on-demand runs are allowed to do. That keeps a leaked token or a strange message from widening the task. For prompt and spec design, see how to build your first AI agent.

Step 3: Add an API trigger for on-demand runs

1. Open the task, choose Edit, click + in the Trigger row, and select API. API triggers are added on the web, not from the CLI.
2. Copy the Fire URL and generate the token (shown once).
3. Call it from your tools with a short text describing the scope, for example {"text": "Check docs for PR #482 only"}.

Full request details, response fields, and error codes: how to trigger Claude Code agents via API.

Step 4: Add Run now, GitHub, and automation callers

• Run now: already available on the task page; you can include text to test the on-demand path.
• GitHub events: add a GitHub trigger for pull request, issue, or release events with filters such as base branch, labels, or draft status. The Claude GitHub App must be installed on the repo.
• CI and deploys: call the Fire URL from a failed job or a post-deploy step.
• Business tools: let Zapier, Make, or n8n call it when a ticket, form, or message arrives; see triggering Claude Code from Zapier, Make, or n8n.
• From the terminal: /schedule run starts a run immediately.

Schedule tips and cron examples

• Runs scheduled exactly on the hour can start several minutes late; pick a few minutes past.
• Presets take your local time; a bare five-field cron is UTC unless it starts with CRON_TZ=.
• Need a cadence tied to business events rather than the clock? Schedule the call in your automation platform instead; see custom schedule intervals in Zapier.

Avoiding overlap and duplicate work

Each trigger starts a separate session, and the fire endpoint has no idempotency key, so the protection has to live in the prompt and in your callers. See why a webhook fires twice and preventing two automations from updating the same record.

Limits and usage

• Scheduled runs: up to 100 per hour per account at the time of writing; extra runs wait.
• On-demand: API fires, Run now, and one-off re-runs share 30 per hour per task; API fires are also capped at 100 per hour per account.
• Usage: every run draws on the same Claude Code subscription usage as interactive sessions. If you hit your limit, runs are rejected unless usage credits are on.
• Paused tasks: turning a task off stops its schedule, and API calls to a paused task return an error.

Budgeting agent runs in general: what it costs to run an AI agent.

Monitoring both kinds of run

• History on the task page lists every run as Succeeded, Failed, or Cancelled. Those describe how the session ended, not whether the work was right, so open runs and read them.
• Waiting runs: a run can stop for a permission prompt; open it to answer.
• Ask the CLI: /schedule why did my nightly review do nothing this morning? summarizes recent runs (on recent CLI versions).
• Turn on notifications for push, email, or Slack on the task's Notifications tab; see notifications for Claude Code scheduled tasks.
• Post outcomes to Slack or an issue from the prompt, so missing runs are noticed.
• Review a sample of scheduled and on-demand runs weekly; see testing and monitoring AI agents.

Example tasks

Other ways to schedule Claude Code

Other platforms are moving the same way; OpenAI workspace agents in ChatGPT, for example, were documented with an API trigger endpoint. For the general pattern, see how to trigger an AI agent from an API or webhook, and for platform choices, where to build AI agents.

Frequently asked questions

Can one Claude Code routine run on a schedule and on demand?

Yes. A Claude Code scheduled task, formerly called a routine, can have several triggers at once: a schedule, an API trigger, and GitHub events, plus a Run now button. Every run uses the same prompt, repositories, environment, and connectors.

How do I write a prompt that works for both scheduled and API-triggered runs?

Tell the prompt to check for a routine-fire-payload block. If it is present, handle the specific request it describes; if not, do the full scheduled job. Define in the prompt what on-demand runs may do, because the payload is treated as untrusted.

How do I add a schedule to a Claude Code task?

Choose a schedule preset when you create the task at claude.ai/code/routines or with /schedule in the CLI. For other cadences, choose Custom in the edit dialog and enter a cron expression; five-field cron is UTC unless it starts with CRON_TZ=, and more often than hourly is rejected.

How do I stop scheduled and on-demand Claude Code runs from duplicating work?

Have the prompt search for an existing branch, pull request, or issue and update it, store last-run state somewhere durable and update it only on scheduled runs, and deduplicate events in your callers, since each trigger starts a separate session.

What are the limits for Claude Code scheduled tasks?

At the time of writing, scheduled runs are limited to 100 per hour per account, API fires, Run now, and one-off re-runs share 30 per hour per task, and API fires are capped at 100 per hour per account. Runs also use your Claude Code subscription usage.