CLAUDE_CODE_RETRY_WATCHDOG_SCOPE

Updated October 23, 2026 by Alex Sorokoletov

CLAUDE_CODE_RETRY_WATCHDOG_SCOPE is a Claude Code environment variable: Read alongside CLAUDE_CODE_RETRY_WATCHDOG. With the watchdog on, the guarded branch runs only when this is not set to capacity; setting it to capacity turns that branch off. New in v2.1.310. Its release history is not tracked here. It is not in the official reference.

How to set it

For one session, export it in the shell that starts Claude Code:

export CLAUDE_CODE_RETRY_WATCHDOG_SCOPE=<value>
claude

To apply it to every session, add it to the env object of a settings file:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG_SCOPE": "<value>"
  }
}

Release notes that mention it

• Claude Code Version Tracker: Undocumented Env Vars, Feature Gates & Models
• claude-code-env-vars-v2-1-310

Related variables

• CLAUDE_CODE_RETRY_WATCHDOG: Tunes the retry watchdog that detects API calls silently looping without progress.
• CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS: Bounds how long unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits for a usage-limit reset.
• CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS: Caps the total time unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits through 429 and 529 responses.
• CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS: Governs how unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) rechecks a usage limit that was lifted before its reset, so a headless run can resume once the limit clears.
• CLAUDE_CODE_RETRY_WATCHDOG_SCOPE1
• CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS: Sets the base delay, in milliseconds, for the backoff when a request comes back overloaded (HTTP 529).
• CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS: Raises the ceiling on the backoff delay when retrying a request that returned a 529 overloaded response.
• CLAUDE_ENABLE_BYTE_WATCHDOG: Activates a byte-level watchdog on API response streams.

Frequently asked questions

All variables, searchable: Claude Code environment variables.