up to $20

Blog

Claude Code routines: what they run, where they stop, and when to use a hosted agent

· by

TL;DR. A Claude Code routine is a saved prompt, one or more GitHub repositories, and a set of connectors that Claude Code runs in the cloud. A routine starts on a schedule, from an HTTP call, or on a GitHub event. Routines are in research preview on the Pro, Max, Team, and Enterprise plans. They use your subscription usage and a daily run cap. Use a routine for repository work that ends in a branch or a pull request. Consider a hosted agent next to it when the work has no repository, needs files that stay between runs, or must bill apart from your Claude plan.

A disclosure first: plori is a hosted AI agent that you can call from Claude Code over MCP. We sell an alternative for some of the work that this post discusses, so read the comparison with that bias in mind. Every statement about routines comes from Anthropic's documentation as we read it on September 24, 2026. We did not run a routine for this post.

What is a Claude Code routine?

Anthropic's routines documentation gives the definition: "A routine is a saved Claude Code configuration: a prompt, one or more repositories, and a set of connectors, packaged once and run automatically." The same page says routines "execute on Anthropic-managed cloud infrastructure, or on your organization's self-hosted environment when routed there."

A note at the top says: "Routines are in research preview. Behavior, limits, and the API surface may change."

A routine has one or more triggers:

  • Schedule. The presets are hourly, daily, weekdays, and weekly. For a custom cron expression, run /schedule update in the CLI. The minimum interval is one hour. A one-off run fires once at a timestamp and then disables itself.
  • API. Each routine gets its own /fire endpoint and bearer token. The request needs the beta header experimental-cc-routine-2026-04-01. An optional text field arrives in a <routine-fire-payload> block that labels it as untrusted data.
  • GitHub event. Pull request and release events can start a run. The Claude GitHub App must be on the repository. During the preview, per-routine and per-account hourly caps apply, and the platform drops events past the cap.

You create a routine at claude.ai/code/routines, in the Desktop app, or with /schedule in the CLI. The prompt form has a model selector, and "Claude uses the selected model on every run."

What happens during a run?

Each run clones the selected repositories and starts from the default branch unless the prompt says otherwise. Claude pushes its changes to branches with the claude/ prefix. Claude Code rejects a push to a protected branch or to a branch that carries another person's work.

A run has no permission-mode picker. It runs shell commands and calls connectors "all without stopping for approval apart from some artifact actions." All your connectors are included by default, and the docs warn that "Claude can use every tool from an included connector, including writes, without asking for permission during a run." Commits, pull requests, and connector actions appear under your own identity.

A green status in the run list has a narrow meaning. In the docs' words, it "does not mean the task in your prompt succeeded." Open the run and read the transcript.

What do routines cost?

The docs say: "Routines draw down subscription usage the same way interactive sessions do." Routines also have "a daily cap on how many runs can start per account." One-off runs do not count against that cap. When you reach the cap or your usage limit, an organization with usage credits can continue on metered overage. Without usage credits, the platform rejects extra runs until the window resets.

The docs do not print the cap. Anthropic's launch post of April 14, 2026 gave it: 5 runs per day on Pro, 15 on Max, and 25 on Team and Enterprise. Check claude.ai/settings/usage for your current number.

What is headless mode, and how is it different from a routine?

Headless mode is the non-interactive CLI. The headless documentation now covers it as the Agent SDK CLI. You pass -p and a prompt, and claude prints the result and exits.

Some flags matter for unattended runs:

  • --bare skips hooks, skills, plugins, MCP servers, and CLAUDE.md. The docs call it "the recommended mode for scripted and SDK calls." Bare mode does not read your subscription login, so it needs an API key or another provider credential.
  • --output-format json returns the result with metadata, including total_cost_usd, which the docs describe as a client-side estimate.
  • --permission-prompts none (v2.1.259 or later) is for runs where nobody can answer a permission prompt, for example a scheduled job. Claude Code denies a request that no rule or hook allows, and the run continues.

A background shell that Claude starts during a -p run "is terminated about five seconds after Claude has returned its final result."

The difference is who supplies the machine and the trigger. A headless run executes where you start it: your terminal, a cron job on your server, or a CI runner. That machine must stay up until the run ends, and you own its schedule and credentials. A routine runs in Anthropic's cloud or your self-hosted environment, on a trigger that your claude.ai account owns. Use headless mode when the task needs local files or already runs in CI. Use a routine when you want a schedule or a webhook without a runner to operate.

What does a routine need? A docs-drift example

The routines docs list a docs-drift use case: "A schedule trigger runs weekly. The routine scans merged PRs since the last run, flags documentation that references changed APIs, and opens update PRs against the docs repository for an editor to review." The setup has six steps:

  1. Write a self-contained prompt. State what to scan, what to change, and what a successful run produces. Select the model.
  2. Add the code repository and the docs repository. Make sure your account has GitHub access to both. If the GitHub connection expires, the routine skips runs. After 72 hours without a connection, the routine turns off.
  3. Select an environment. The Default environment allows only a list of trusted domains. Edit its network access if the routine must reach your own services. On Pro and Max, store API keys as API credentials, not as environment variables.
  4. Select the weekly schedule preset. For a different interval, run /schedule update and set a cron expression of one hour or longer.
  5. Remove every connector that the task does not use. For example, keep Slack only if the routine posts a summary there.
  6. After each run, open the session. Read the transcript and review the pull requests on the claude/ branches.

What are the limits of Claude Code routines?

From the docs:

  • The shortest schedule interval is one hour.
  • Each account has a daily run cap in addition to subscription usage limits.
  • During the preview, GitHub events have hourly caps.
  • Routines work on GitHub repositories. Each run clones them again and starts a new session. The environment caches its setup script, but the docs do not describe a working directory that stays from one run to the next.
  • Routines belong to one claude.ai account. They "are not shared with teammates," and Team or Enterprise Owners can disable them for all members.
  • /schedule requires a claude.ai subscription login. It is not available with a Console API key or a cloud-provider login such as Amazon Bedrock.

When does a hosted plori agent fit next to a routine?

plori is a cloud AI agent with its own persistent environment. It does not run Claude Code. Four differences matter for recurring or long work:

  1. The task does not need a repository. A plori agent takes a task in chat or over MCP and works in its own shell with network access. Delegated work can be a data backfill or a scrape of a few thousand pages. A command that runs longer than ten seconds moves to a background task, with a limit of one hour per task and five tasks per agent.
  2. The bill is separate from your Claude plan. plori bills usage in credits: model usage at cost and compute per active minute. An idle agent sleeps and stops compute billing. With your own model key, model calls bill to your provider. Native Anthropic keys are not supported yet, so Claude models go through OpenRouter. Rates are on pricing.
  3. Files and notes stay between runs. Each agent keeps a persistent disk and memory notes that it reads at the start of every turn. Sleep does not keep running processes or RAM.
  4. Claude Code can call it. The plori MCP server gives Claude Code tools such as create_agent, invoke_agent, get_run_result, and schedule_run.

plori has limits of its own. A scheduled run fires once. For repeated fixed steps, the agent can build a workflow that fires on a schedule or a webhook. Each plan limits how many runs can be in flight at once. A plori agent cannot reach your localhost, and it does not drive a browser.

A routine is the better choice when the task starts from a repository and ends in a pull request. It is also the better choice when you already pay for a Claude plan and stay under its limits, or when the task needs the connectors on your claude.ai account. Our comparison page gives the same advice: "Try the cloud features of your existing product first. Add plori when its task workflow, saved files, and MCP delegation fit work you need to do."

How do you use Claude Code and plori together?

  1. Open Claude Code in an interactive terminal session. Paste this prompt:

    Set up https://plori.ai/SKILL.md

  2. Complete the sign-in. If the client supports pairing, Claude shows a short code. Open https://plori.ai/device, enter the code, and approve the connection.

  3. Ask Claude to list your plori agents. This call uses list_agents and spends no credits.

  4. Give Claude one long task to delegate, for example: "Create a plori agent named release-notes and ask it to summarize the changelogs of our main dependencies." This step starts a run, and the run spends credits.

  5. Read the result. invoke_agent waits for the reply by default. For a longer run, ask Claude to call get_run_result until the run finishes.

The full walkthrough is in Connect Claude Code to plori. Pairing does not work under claude -p, so connect from an interactive session. A routine does not see MCP servers that you added locally with claude mcp add. It uses the connectors on your claude.ai account or, for a routine with one repository, a committed .mcp.json. We have not tested plori as a routine connector.