Claude Code routines: every limit, cap and gotcha

Claude Code routines are a research preview, and the limits that govern them are spread across several documentation pages. This is all of them in one place, with the practical consequence of each spelled out.

Everything below was checked against Anthropic’s documentation on 5 October 2026. Behaviour changes; the date is here so you can judge how stale this is.

Run limits are hourly, not daily

This is the one most people get wrong, because “daily quota” is the intuitive mental model and it is simply not how this works. Each way of starting a run has its own hourly cap, and they count separately.

None of these has overage. Three things follow:

• The 30/hour per-routine cap is shared. Testing a routine by hammering Run now eats the exact allowance your production API trigger needs. Test on a copy.
• Scheduled runs wait; API fires fail. Over the limit, a scheduled run is simply deferred, but an API fire returns an error. Whatever calls your endpoint needs to handle a rejection — log it and alert, do not retry in a tight loop.
• Dropped GitHub events are silent. There is no queue and no retry. Nothing tells you an event was discarded. If a routine must not miss events, pair the trigger with a low-frequency scheduled sweep that reconciles against the repository.

Separately from all of this, routines draw down your subscription usage the same way interactive sessions do. The prompt input carries a model selector, and Claude uses the selected model on every run — picking a smaller model for a routine that formats and files, rather than one that reasons, is the cheapest saving available.

Scheduling gotchas

• Never schedule on the hour. A run set for 9:00 can start several minutes late. Anthropic’s own advice is to pick a few minutes past, e.g. 9:07. Stagger your routines across the hour while you are at it, so they don’t all contend at once.
• The minimum interval is one hour. Custom cron expressions that run more frequently are rejected. For a custom interval, pick the closest preset in the form, then use /schedule update in the CLI to set the cron expression.
• Times convert automatically. You enter a local time; it runs at that wall-clock time regardless of where the infrastructure sits.
• One-off runs auto-disable. After firing, the routine turns itself off and the UI marks it Ran. To run it again, edit it and set a new time. One-off runs count against the same hourly limit as other scheduled runs.
• A routine with no schedule has no next run time. An API-only or GitHub-only routine shows none, which means silence from a broken caller is indistinguishable from silence from a healthy system. Give every event-driven routine a low-frequency schedule as well — not to do the work twice, but so that the absence of events is something you can see.

GitHub trigger gotchas

• Every event is a separate session. Claude Code does not reuse sessions across events. A contributor who pushes five times to an open PR fires your routine five times. Filter at the trigger (exclude drafts; prefer pull_request.opened over all actions) and deduplicate in the prompt, keyed on the head commit SHA rather than the PR number.
• matches regex tests the entire field value, not a substring. To match any title containing hotfix you must write .*hotfix.*. Without the surrounding .* it matches only a title that is exactly hotfix. When you want substring matching, use contains and avoid the trap entirely.
• /web-setup does not install the GitHub App. It grants repository access for cloning. It does not enable webhook delivery. These are separate things and assuming otherwise is a common dead end — install the app from the Claude GitHub App page.
• An expired GitHub connection skips runs for up to 72 hours. Reconnect inside that window and the routine resumes on its own. After 72 hours it switches off, and you have to turn it back on by hand after reconnecting.
• Claude pushes to claude/-prefixed branches unless your prompt says otherwise. Branch protection rules are evaluated against the GitHub access you connected.

The API trigger’s payload is untrusted by design

The optional text field on a /fire call does not arrive as a bare instruction. It is wrapped in a <routine-fire-payload> block that labels it as untrusted data and tells Claude not to follow instructions inside it unless the routine’s own prompt says to. The same wrapping applies to text typed into Run now.

Two consequences, and people hit both:

1. If you want the routine to act on the payload, say so explicitly. A prompt that never mentions the payload treats it as inert context, and your carefully-passed alert body does nothing at all.
2. Anyone holding the bearer token can send text. The wrapper exists so that a leaked token produces untrusted data in a labelled box rather than direct instructions to your routine. Your prompt’s extraction rules are the second half of that protection — write them narrowly, name the fields you will read, and refuse everything else.

Also worth knowing: the payload is freeform and is not parsed. Send JSON and the routine receives the literal string, which is fine as long as your prompt says “parse the JSON in the payload block” rather than assuming structure. And the token is shown once when you generate it and cannot be retrieved later — put it straight into the calling system’s secret store.

The /fire endpoint ships under the dated beta header experimental-cc-routine-2026-04-01. Breaking changes ship behind new dated headers, with the two most recent previous versions still working, so you get a migration window — but pin the header you tested against and treat a change to it as a code change.

Connectors and network access

• Every connected connector is included by default on a new routine, and Claude can use every tool from an included connector — including writes — without asking during a run. Trim the list before the first run.
• Local CLI MCP servers don’t appear. Servers added with claude mcp add live on your machine, not your claude.ai account. Add them at claude.ai/customize/connectors, or declare one in a committed .mcp.json.
• The Default environment uses Trusted network access, allowing only Anthropic’s default allowlist. A request to a host outside it fails with 403 and x-deny-reason: host_not_allowed. Connector traffic routes through Anthropic’s servers, so connectors work without allowlist changes.
• Environment variables are visible to anyone using the environment. On Pro and Max, store keys as API credentials instead.

Diagnosing a run that did nothing

Two things worth having in your pocket.

First, the one that matters most: a green status means the session started and exited without an infrastructure error. It does not mean your task succeeded. Blocked network requests, missing connector tools and task-level failures all surface inside the run transcript, not in the status indicator. Open the run.

Second, from Claude Code v2.1.227 or later you can just ask: /schedule why did my nightly review do nothing this morning? Claude lists the recent runs with their status and reads the log to explain what happened — tool errors, permission denials, the final result.

If /schedule itself is missing, the usual cause is authentication: it requires a claude.ai subscription login, and an ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in your shell takes precedence over it. Remove those first. It is also unavailable inside a cloud session, and an Owner can disable routines organisation-wide.

Related

Why your Claude Code routine reported success and did nothing — the eight-point pass that catches silent failure before you schedule anything.

How to harden the Briefing routine template — the same method applied end to end, with the complete prompt.

Cloud routines vs local scheduled tasks — which of the three scheduling options to use, and what each one does to you if you pick wrong.

The Routines Runbook is 32 ready-made routines built this way from the start, plus hardened replacements for all eight of Anthropic’s free templates and the fourteen guardrail patterns behind them. See what is in it, or take the free 5-routine starter.

Verified against Anthropic’s Routines documentation on 5 October 2026. Routines are a research preview; limits and the API surface may change. Not affiliated with Anthropic.