CLAUDE_BG_BACKEND

Updated October 13, 2026 by Alex Sorokoletov

CLAUDE_BG_BACKEND is a Claude Code environment variable: Set to "daemon" to route background work through a daemon backend. The code path is wrapped around EIO/EPIPE handling — pipe/socket IPC with graceful degradation. First evidence of a long-running daemon in the Claude Code architecture. Added between v2.1.108 and v2.1.114 and still present in v2.1.294. 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_BG_BACKEND=<value>
claude

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

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

Release notes that mention it

• Claude Code v2.1.123 — Background Daemons, Agent Fleets, and CoWork Memory
• Claude Code v2.1.114 — Native Binary Launcher, /fewer-permission-prompts, and 20 New Environment Variables
• Claude Code Version Tracker: Undocumented Env Vars, Feature Gates & Models

Related variables

• CLAUDE_AUTO_BACKGROUND_TASKS: Enable automatic background task execution.
• CLAUDE_BG_ISOLATION: Isolation mode for background agent processes — controls how separated the daemon's process space is from the foreground session.
• CLAUDE_BG_RENDEZVOUS_SOCK: Socket path for the IPC channel between a foreground Claude session and the background daemon.
• CLAUDE_BG_SOURCE: Tags where a background job originated: CLI, SDK, Remote Control, another agent.
• CLAUDE_BG_STARTUP_WEDGE_MS: Startup jitter for background sessions.
• CLAUDE_BG_TCC_DISCLAIMED: macOS TCC (Transparency, Consent, and Control) permission disclaimer state for background sessions.
• CLAUDE_BRIDGE_REATTACH_SEQ: Sequence number for the bridge reconnection protocol.
• CLAUDE_BRIDGE_REATTACH_SESSION: Session identity used during bridge reconnection.

Frequently asked questions

All variables, searchable: Claude Code environment variables.