23 Introducing Routines in Claude Code

23.1 Automation That Actually Works

Most automation tools fail not because they’re hard to configure, but because they’re hard to maintain. You set up a cron job, it works for a week, then something changes — a dependency updates, an API response format shifts, a file moves — and the automation breaks silently. You don’t find out until something goes wrong weeks later.

Routines in Claude Code take a different approach. Instead of brittle scripts that execute exact commands, Routines are agents that execute intent. You describe what you want done, connect the tools the agent needs, and set a schedule. The agent figures out the details — and adapts when things change.

23.2 What Is a Routine?

A Routine is a Claude Code automation that is configured once and then runs on a schedule, via API call, or in response to an event. Each Routine consists of three components:

A prompt — what the agent should do
A repository — the codebase context the agent works in
Connectors — MCP servers and integrations the agent can use

# A Routine definition
name: "nightly-security-scan"
description: "Scan dependencies for known vulnerabilities nightly"
prompt: |
  Check all dependencies for known security vulnerabilities.
  Use the GitHub Advisory Database and npm audit.
  If any high-severity vulnerabilities are found,
  create a GitHub issue with the details and suggested fix.
repository: "myorg/web-app"
connectors:
  - github
  - npm-audit
schedule:
  cron: "0 2 * * *"  # Every night at 2 AM

Routines run on Claude Code’s web infrastructure — not on your local machine. This means:

They run even when your computer is off
They don’t consume your local resources
They scale independently
They’re managed centrally

23.3 Three Trigger Types

Routines can be triggered in three ways:

23.3.1 1. Schedule

The most common trigger. Define a cron expression and the Routine runs automatically at the specified times.

schedule:
  cron: "0 9 * * 1"  # Every Monday at 9 AM

Common scheduling patterns:

Pattern	Cron	Description
Daily morning	`0 9 * * *`	Every day at 9 AM
Weekdays	`0 9 * * 1-5`	Mon-Fri at 9 AM
Weekly	`0 9 * * 1`	Every Monday at 9 AM
Monthly	`0 9 1 * *`	1st of every month at 9 AM
Every 4 hours	`0 /4 * *`	Four times daily
Nightly	`0 2 * * *`	Every night at 2 AM

23.3.2 2. API Call

Routines can be triggered programmatically via an API endpoint. This lets you integrate Claude Code automation into your existing workflows — CI/CD pipelines, webhooks, internal tools.

# Trigger a Routine via API
curl -X POST https://api.claude.ai/code/routines/{routine_id}/run \
  -H "Authorization: Bearer $CLAUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "branch": "feature/new-auth",
      "pr_number": 1234
    }
  }'

23.3.3 3. Event

Routines can respond to events from connected services. When an event matches the Routine’s trigger configuration, the Routine runs automatically.

event_trigger:
  source: "github"
  event: "pull_request.opened"
  filter:
    repository: "myorg/web-app"
    base_branch: "main"

Supported event sources include:

GitHub: PR opened, issue created, push to branch, release published
Slack: Mention in channel, slash command, reaction
Custom webhooks: Any system that can send an HTTP POST

23.4 Creating a Routine

There are two ways to create a Routine:

23.4.1 Via the Web Interface

Navigate to claude.ai/code and click “New Routine.” The web interface provides a form-based editor:

Name and describe your Routine
Write the prompt — what should the agent do?
Select a repository — the codebase context
Add connectors — MCP servers and integrations
Set the trigger — schedule, API, or event
Configure limits — max runtime, max cost, notification preferences

23.4.2 Via the CLI

From within a Claude Code session, type /schedule:

> /schedule

Creating a new Routine...

Name: weekly-dependency-update
Description: Check for outdated dependencies and create update PRs

Prompt: Check package.json and requirements.txt for outdated dependencies.
Create a PR for each major version update with a summary of breaking changes.

Repository: current (myorg/web-app)
Connectors: github
Schedule: Weekly on Monday at 9 AM

Create this Routine? [Y/n]

Tip

Start with the CLI /schedule command for quick prototyping — it pre-fills the repository and connectors from your current session. Once the Routine is working, refine it in the web interface where you have more configuration options.

23.5 Example Routines

23.5.1 Dependency Update Checker

name: "dep-update-checker"
prompt: |
  Check all dependencies in package.json and requirements.txt.
  For each outdated package:
  1. Check the changelog for breaking changes
  2. Create a branch with the update
  3. Run the test suite
  4. If tests pass, create a PR with a summary
  5. If tests fail, create an issue describing the failures
schedule:
  cron: "0 9 * * 1"  # Weekly Monday
connectors: [github]

23.5.2 PR Triage

name: "pr-triage"
prompt: |
  Review all open PRs in the repository.
  For each PR:
  1. Check if it's stale (no activity for 7 days)
  2. Verify CI status
  3. Check for merge conflicts
  4. Label appropriately: "stale", "conflicts", "needs-review"
  5. Post a summary comment
event_trigger:
  source: "github"
  event: "schedule.daily"
connectors: [github]

23.5.3 Documentation Generator

name: "doc-generator"
prompt: |
  Scan the codebase for undocumented public APIs.
  For each undocumented API:
  1. Read the implementation
  2. Generate documentation
  3. Create a PR with the documentation
  Tag the PR author for review.
schedule:
  cron: "0 9 * * 1"  # Weekly
connectors: [github]

23.5.4 Incident Response

name: "incident-responder"
prompt: |
  An incident has been declared. Investigate:
  1. Check recent deployments for the affected service
  2. Review error logs in Datadog
  3. Identify potential root causes
  4. Post a summary to the #incidents Slack channel
  5. Create a rollback PR if a deployment caused the issue
event_trigger:
  source: "pagerduty"
  event: "incident.triggered"
connectors: [github, slack, datadog]

23.6 Daily Limits and Usage

Routines draw down your subscription’s usage. Each plan has daily limits on the number of Routine runs:

Plan	Daily Routine Limit
Pro	5
Max	15
Team	25
Enterprise	25 (custom negotiable)

When you hit the daily limit, Routines are queued and run the next day (for scheduled Routines) or return a 429 error (for API-triggered Routines).

Note

Routines consume the same usage budget as interactive Claude Code sessions. A complex Routine that runs for 10 minutes might consume the same amount of usage as a 10-minute interactive session. Monitor your usage in Settings → Usage.

23.6.1 Cost Considerations

Because Routines run on web infrastructure and can run for extended periods, it’s important to understand the cost model:

Token usage: Each Routine run consumes input and output tokens
Compute time: Longer-running Routines consume more compute
Connector calls: Each MCP tool call may have its own costs

Typical costs per Routine type:

Routine Type	Typical Duration	Estimated Cost
Dependency check	2-5 min	Low
PR triage	3-8 min	Low-Medium
Code review	15-25 min	Medium
Incident response	10-30 min	Medium-High
Full test suite	5-15 min	Medium

23.7 Monitoring and Management

23.7.1 The Routines Dashboard

The web interface at claude.ai/code provides a dashboard for managing your Routines:

┌─────────────────────────────────────────────────────────────┐
│  ROUTINES                                   [+ New Routine] │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ● nightly-security-scan        Active    Runs: 45          │
│    Schedule: Daily at 2 AM      Success: 98%                │
│    Last run: 2026-08-02 02:00   Avg: 3 min                  │
│                                                             │
│  ● weekly-dep-update            Active    Runs: 12          │
│    Schedule: Monday 9 AM        Success: 100%               │
│    Last run: 2026-08-01 09:00   Avg: 7 min                  │
│                                                             │
│  ○ pr-triage                    Paused    Runs: 234         │
│    Event: PR opened             Success: 95%                │
│    Last run: 2026-08-02 14:23   Avg: 2 min                  │
│                                                             │
│  ● incident-responder           Active    Runs: 8           │
│    Event: PagerDuty             Success: 100%               │
│    Last run: 2026-07-28 03:15   Avg: 18 min                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

For each Routine, you can see:

Status: Active, paused, or error
Run count: Total times the Routine has executed
Success rate: Percentage of runs that completed without error
Last run: When it last executed
Average duration: Typical execution time

23.7.2 Run History

Click any Routine to see its full run history. Each run shows:

Start and end time
Duration
Status (success, failure, timeout)
Full session log
Actions taken (files changed, PRs created, messages sent)
Cost

23.7.3 Failure Handling

When a Routine fails, the system:

Notifies you via email or Slack (depending on configuration)
Logs the full error context in the run history
Retries up to 3 times with exponential backoff (for scheduled Routines)
Pauses the Routine after 5 consecutive failures (to prevent runaway costs)

23.8 Best Practices

23.8.1 Start Simple

Don’t build a complex, multi-step Routine on day one. Start with a simple task, verify it works reliably, then add complexity.

23.8.2 Write Clear Prompts

The prompt is the most important part of a Routine. It should be specific, unambiguous, and include success criteria.

# Bad prompt
prompt: "Keep the codebase healthy"

# Good prompt
prompt: |
  1. Run `npm audit` and identify high-severity vulnerabilities
  2. For each vulnerability, check if a fix is available
  3. If a fix exists, create a PR with the update
  4. If no fix exists, create a GitHub issue documenting the vulnerability
  5. Post a summary to the #engineering Slack channel

23.8.3 Set Reasonable Limits

Every Routine should have a maximum runtime and cost limit. This prevents runaway execution if something goes wrong.

limits:
  max_runtime: 1800      # 30 minutes
  max_cost: 5.00         # $5 USD
  max_tool_calls: 100    # Maximum MCP tool invocations

23.8.4 Monitor Early, Trust Later

When you first create a Routine, monitor it closely for the first few runs. Check the session logs, verify the results, and adjust the prompt as needed. Once it’s running reliably for a week, you can trust it to run autonomously.

23.8.5 Debugging Failed Routines

When a Routine fails repeatedly, the session log is your primary debugging tool. Common failure patterns include:

Failure Pattern	Likely Cause	Fix
Tool call timeout	External service is slow or down	Increase timeout, add retry logic
Permission denied	Connector credentials expired	Re-authorize the connector
Ambiguous result	Prompt is too vague	Add specific success criteria
Infinite loop	Agent keeps retrying the same failed action	Add `max_tool_calls` limit
Context overflow	Repository is too large	Narrow the scope or use `.claudeignore`

# Example: Adding .claudeignore to reduce context for large repos
# .claudeignore
node_modules/
*.pyc
dist/
build/
.env
*.log
vendor/

Note

The most common Routine failure is not a technical error — it’s a prompt that’s too ambiguous. “Keep the codebase healthy” doesn’t give the agent enough direction. “Run npm audit, fix high-severity vulnerabilities, and create PRs for each fix” is specific and actionable. The time you spend writing a clear prompt pays off in reliable execution.

23.9 Key Takeaways

Routines are Claude Code automations configured once (prompt + repository + connectors) that run on schedule, via API, or in response to events.
They run on Claude Code’s web infrastructure — not your local machine — so they execute even when your computer is off.
Three trigger types: scheduled (cron), API call, and event-driven (GitHub, Slack, PagerDuty, webhooks).
Daily limits apply: Pro = 5, Max = 15, Team/Enterprise = 25 runs per day.
Create Routines at claude.ai/code or with the /schedule command in the CLI.
Routines draw down your subscription usage — monitor costs and set limits on runtime and tool calls.
Start simple, write clear prompts, set limits, and monitor early before trusting a Routine to run autonomously.
The dashboard at claude.ai/code provides full visibility into run history, success rates, and costs.