Sign in Subscribe
news

Claude Code Routines

Sebastien Dubois

Sebastien Dubois

— 11 min read

Canonical version: Claude Code Routines.

A routine is a saved Claude Code configuration: a prompt, one or more GitHub repositories, a cloud environment and a set of connectors. You package it once, attach one or more triggers, and it runs on its own on Anthropic-managed cloud infrastructure (or on your organization's self-hosted environment when routed there). Your laptop can be closed. Anthropic launched routines in research preview on 2026-04-14, and the docs still warn that behavior, limits and the API surface may change.

Routines absorbed the earlier Claude Code Web Scheduled Tasks. At launch, tasks created with /schedule became scheduled routines, and the old web-scheduled-tasks docs URL now serves the routines page.

Before routines, automating Claude Code meant running your own cron jobs, infrastructure and MCP servers (Anthropic's framing in the launch post). Now it's a prompt plus a trigger, and each run shows up as a normal session you can open and pick up.

Availability

  • Pro, Max, Team and Enterprise plans. Routines need cloud sessions (Claude Code Web), so an organization policy that disables cloud sessions also blocks them.
  • /schedule needs a claude.ai subscription login. It's hidden when you're signed in with a Console API key, a cloud provider (Amazon Bedrock, Google Cloud, Microsoft Foundry), or when ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or apiKeyHelper is set. It's also unavailable inside a cloud session.
  • Team and Enterprise Owners can switch routines off for every member. Existing routines stop and nobody can create new ones. Since v2.1.280 (2026-09-22) the toggle lives under Admin settings → Capabilities → Remote sessions.
  • Routines belong to your individual claude.ai account. They aren't shared with teammates, they count against your usage, and everything they do through GitHub or connectors appears as you (your GitHub user on commits and PRs, your Slack and Linear accounts, etc.).

Create a routine

Three surfaces write to the same cloud account, so a routine created in one shows up in the others immediately:

  • Web: claude.ai/code/routines → New routine. Name it, write the prompt (with a model selector), pick repositories, environment, triggers and connectors, then Create. Run now starts a test run right away.
  • Desktop app: Code tab → Routines → New routine → Cloud. Choosing Local creates a Desktop scheduled task instead, which runs on your machine.
  • CLI: /schedule (alias /routines) walks you through the same fields conversationally. Pass a description directly: /schedule daily PR review at 9am, or a one-off like /schedule in 2 weeks, open a cleanup PR that removes the feature flag. If Claude answers that you need to authenticate, no routine was created.

The prompt is the part that matters. The run is autonomous, so the prompt must be self-contained and say what to do and what success looks like. Since v2.1.213 the fired prompt is the session's assigned task. Before that it arrived framed as an untrusted background notification, and Claude could refuse to act on it.

Triggers

A routine can combine any number of triggers. One PR review routine can run nightly, get called by a deploy script and react to every new PR.

Schedule

  • Presets: hourly, daily, weekdays, weekly. Times are entered in your local zone and converted to UTC.
  • Custom intervals (every 2 hours, first of the month): pick the closest preset, then set a cron expression with /schedule update. Minimum interval: 1 hour; anything more frequent is rejected.
  • A run set exactly on the hour can start several minutes late. Pick 9:07 instead of 9:00 if timing matters.
  • One-off runs fire once at a timestamp, then the routine auto-disables and shows Ran. From the CLI, describe the time in plain language (/schedule tomorrow at 9am, summarize yesterday's merged PRs) and Claude confirms the absolute timestamp.

API

  • Each routine gets its own /fire endpoint and bearer token, added from the web only (the CLI can't create or revoke tokens). The token is shown once; Regenerate or Revoke it from the same modal.
  • POST with an optional text field for run-specific context (an alert body, a failing log). It's a freeform string, never parsed: JSON arrives as a literal string. The response returns the new session ID and URL.
  • Requires the experimental-cc-routine-2026-04-01 beta header. Breaking changes ship behind new dated headers; the two previous versions keep working during migration.
  • The text arrives wrapped in a <routine-fire-payload> block labeled as untrusted data. Claude won't follow instructions inside it unless the routine's own prompt says to, so write the prompt to reference the payload explicitly ("Investigate the alert described in the routine-fire-payload block"). That's the protection against a leaked token. Run now text gets the same wrapping.
  • The endpoint is for claude.ai users only and isn't part of the Claude Platform API.

GitHub

  • Needs the Claude GitHub App installed on the repository. /web-setup grants clone access but doesn't install the app or enable webhooks.
  • Supported events: pull request (opened, closed, assigned, labeled, synchronized, etc.) and release (created, published, edited, deleted). Pick one action, like pull_request.opened, or all actions of the category.
  • PR filters: author, title, body, base branch, head branch, labels, is draft, is merged. Operators: equals, contains, starts with, is one of, is not one of, matches regex. All conditions must match. matches regex tests the whole field, so write .*hotfix.* to match a substring.
  • Every matching event starts a new, independent session; two PR updates give two sessions.
  • Per-routine and per-account hourly caps apply. Events beyond the cap are dropped until the window resets.
  • Added from the web, or from the CLI since v2.1.225 (/schedule add a GitHub trigger to my nightly review for pull requests opened in acme/webapp).

Execution Model

  • Each run is a full Claude Code cloud session with no permission-mode picker. It runs shell commands, uses skills committed to the cloned repository and calls connectors without asking for approval. The exception is artifacts: a run republishes an existing artifact silently only when it's yours, not public, and the publish adds nothing beyond the page; a first publish still asks.
  • Each selected repository is cloned fresh on every run, from the default branch unless the prompt says otherwise. Claude pushes to claude/-prefixed branches unless the prompt directs it elsewhere. To restrict pushes, use GitHub branch protection rules or rulesets; they're checked against the GitHub access you connected, so a rule that access can bypass won't stop a run.
  • The cloud environment sets network access, environment variables and a setup script (its result is cached). The Default environment uses Trusted access: only the default allowlist of package registries, cloud APIs and common dev domains. Other hosts fail with 403 and x-deny-reason: host_not_allowed; switch the environment to Custom or Full if the routine must reach your own services. Environment variables are visible to anyone who uses the environment, so on Pro and Max store API keys as API credentials instead.
  • Connectors are the claude.ai connectors on your account, and all of them are included by default. Claude can use every tool of an included connector, writes included, without asking. Remove the ones the routine doesn't need. MCP servers added locally with claude mcp add don't appear; add them at claude.ai/customize/connectors or commit a .mcp.json in a single-repo routine. Connector traffic goes through Anthropic's servers, so it needs no allowlist change.
  • Each run shows up as a session next to your others: open it to review changes, create a PR or continue the conversation.
  • If your GitHub connection is missing or expired, the routine skips runs for up to 72 hours and resumes when you reconnect. After 72 hours it turns itself off.
  • Organizations with IP allowlisting enabled see Anthropic-hosted runs fail with an authentication error until support exempts Anthropic-hosted services. A routine routed to a self-hosted environment calls the API from your own network.

A green run is not a successful task. Green only means the session started and exited without an infrastructure error. Blocked network requests, missing connector tools and task failures only show up in the transcript. Since v2.1.227 you can ask /schedule why did my nightly review do nothing this morning? and Claude reads the run logs for you.

Use Cases

  • Nightly backlog grooming (triage, label, assign issues, post a summary to Slack).
  • Alert triage (monitoring tool POSTs the alert body; routine correlates with recent commits and opens a draft fix PR).
  • Bespoke code review on pull_request.opened with a team-specific checklist.
  • Deploy verification called by CD pipeline after each prod release.
  • Weekly docs-drift scanner that opens update PRs against the docs repo.
  • Library port: merged PR in SDK-A triggers a matching PR in SDK-B.
  • Feedback resolution: a docs feedback widget posts the report, Claude drafts the change against the repo.
  • Keeping a published artifact current: give the routine an artifact you already published and let each run refresh it.

Routines vs Other Scheduling

Routines (cloud) Desktop scheduled tasks /loop (CLI)
Runs on Anthropic cloud (or self-hosted environment) Your machine Your machine
Machine on? No Yes (app open, machine awake) Yes
Open session? No No Yes
Survives restarts Yes Yes Restored on --resume, with exceptions
Local files No (fresh clone) Yes Yes
MCP claude.ai connectors per routine Config files and connectors Inherits from session
Permission prompts None (autonomous) Configurable per task Inherits from session
Triggers Schedule + API + GitHub Schedule Interval in an open session
Minimum interval 1 hour 1 minute 1 minute

How it differs from the neighbors:

  • Claude Code Hooks react to lifecycle events (PreToolUse, Stop, SessionStart…) inside a session that's already running, on the machine running it. They shape a session; they never start one. A routine starts a brand-new session from outside, with nobody at the keyboard.
  • cron runs a command on a machine you own, down to the minute. A routine runs a whole agent session on someone else's machine, at most hourly, without your local files.
  • GitHub Actions (the Claude Code GitHub Action) runs in your CI from a workflow file and can react to any GitHub event, including a schedule. With a plain prompt, Claude gets no shell or GitHub API access until you grant the tools. GitHub only runs scheduled workflows from the default branch and disables them in public repos after 60 days without activity. Routines need no workflow file and run with your claude.ai identity, but only react to PR and release events.
  • /loop and the cron tools (Claude Code Tasks) are session-scoped: they fire only while that session is open and idle, and recurring tasks expire after 7 days.
  • /goal keeps one session working until a condition holds. A routine decides when a session starts; /goal decides when it may stop.
  • Claude Code Channels push events into a session that's already running. A routine's API trigger creates a new session per call.
  • Claude Code Agent View manages background sessions on your own machine that you dispatch by hand.
  • Claude Code Projects: when you ask a project for scheduled work, Claude creates a routine that runs as threads in that project and shows up on its Routines tab. Routines created outside a project keep working on their own.
  • Claude Managed Agents is the Claude Platform equivalent for your own agents: scheduled deployments give them the same run-on-a-schedule behavior. The side-by-side with the Agent SDK is in its comparison table.

Limits

  • No separate price: runs draw down your subscription usage like interactive sessions (see claude.ai/settings/usage).
  • Hourly caps, separate from subscription usage and with no overage:
    • Scheduled runs, one-off runs included: 100 per hour per account. Extra runs wait.
    • Run now, API fires and re-arming a one-off: 30 per hour per routine, shared. Beyond that the action fails until the window resets.
    • Run now (and re-arming a one-off): 100 per hour per account. API fires: another 100 per hour per account, counted separately.
    • GitHub events: per-routine and per-account hourly caps; extra events are dropped.
  • When you hit your subscription usage limit, organizations with usage credits turned on continue on metered overage. Without credits, runs are rejected until the usage window resets.
  • A paused subscription puts routines on hold. Once it's active again you turn them back on yourself.

CLI Surface

  • /schedule (alias /routines) → guided creation of scheduled and one-off routines.
  • /schedule list → list routines.
  • /schedule update → edit a routine (including custom cron and connectors).
  • /schedule run → trigger immediately.
  • /schedule add a GitHub trigger to … → attach a GitHub trigger (v2.1.225+, app installed first).
  • /schedule why did … ? → run history and log analysis (v2.1.227+).
  • API tokens: web only.
  • /web-setup grants repo cloning access but does NOT install the Claude GitHub App required for GitHub triggers.

What changed since launch

The launch post (2026-04-14) and today's docs disagree on two points. The docs win, but the history explains older articles:

  • Caps: at launch, routines had daily caps (Pro 5, Max 15, Team and Enterprise 25 runs per day, more with extra usage). The current docs list only the hourly caps above.
  • GitHub sessions: the launch post said Claude opens one session per PR and keeps feeding it updates (comments, CI failures). The docs now say sessions are never reused across events.
  • Earlier versions of this note listed more GitHub event types (pushes, issues, workflows, check runs, etc.), a fork-origin filter and an "Allow unrestricted branch pushes" option. None of these appear in the current docs.

Why This Matters

Routines collapse three previously separate workflows (scheduled cloud task, GitHub Action style automation, webhook-triggered agent) into a single reusable session definition. This makes it practical to treat Claude Code as a first-class automation substrate alongside CI/CD, moving from "AI helps me code" toward "AI agents run on infrastructure and act as team members". The tradeoff is loss of local-file access and full autonomy with no human in the loop per run; the prompt must be self-sufficient and the scope of repositories, env, and connectors must be tight.

Alternative to No-Code Automation Platforms

Routines are a serious alternative to n8n, Zapier, and similar workflow platforms. The triggers map directly: cron schedules, webhooks (API), and third-party events (GitHub today, more connectors over time through MCP). The key difference is what sits between trigger and action. In n8n or Zapier, you hand-wire a deterministic graph of nodes and branches. In a Routine, the "node" is a full Claude Code session with reasoning, tool use, code execution, git, and MCP connectors. The cost of expressing a new workflow drops from "design a DAG" to "write a prompt", and the ceiling rises from "map fields between APIs" to "investigate, decide, and ship a PR".

Enabling Always-On Agents (Heartbeat Pattern)

Beyond simple automation, Routines provide the missing substrate for long-running AI agents like OpenClaw and other AI Agents. A scheduled trigger running every hour (or an API trigger fired from a recurring heartbeat) acts as the agent's pulse: each firing is a chance for the agent to wake up, read its own state (vault notes, issues, memory), decide what to do next, act, and go back to sleep. This is the concrete substrate behind Agentic loops, and it depends on AI Agent Memory surviving across firings (via the repo, connectors, or an external store). What was previously a research pattern ("agent with a goal and a loop") becomes a deployable reality: the repository and connectors carry state across runs (each run starts from a fresh clone; only the environment's setup is cached), the heartbeat (cron-scheduled, see cron) gives the agent a sense of time and persistence, and the API trigger lets external systems interrupt or inject context. That combination is what makes an agent "feel alive" instead of being a single-shot chatbot. Routines are arguably the cleanest public implementation of this pattern today, with Claude Managed Agents and its Claude Managed Agents Events surface covering the higher-end, multi-session, fully-managed case. See also Distinction between AI Agents and Automation Workflows for why "a Routine" sits on the agent side of the line even when its trigger looks like a Zap.

References

About Sébastien

Ready to get to the next level?

Found this valuable? Share it with someone who needs it.

Join 6,000+ readers. Get practical systems for knowledge & AI. Free.

Subscribe ✨

Free: Knowledge System Checklist

A clear roadmap to building your own knowledge system. Subscribe and get it straight to your inbox.

6,000+ readers. No spam. Unsubscribe anytime.

Subscribe