CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

When set, this env var disables:

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

An environment variable that disables all background task execution and the Ctrl+B background shortcut in Claude Code.

How it works

Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 before launching Claude Code to suppress two mechanisms: auto-backgrounding of long-running tasks and the manual Ctrl+B keyboard shortcut. Both become inert; tasks run foreground-only.

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
claude

Test findings

Tested 2026-01-16 on version 2.1.4 features (running on 2.1.9). Status: code review only, not runtime-tested. The test identified why interactive verification is difficult: Ctrl+B requires a live terminal, auto-backgrounding depends on task duration and unobservable internal conditions, and testing would require explicit before/after comparison in the running CLI. No runtime confirmation exists.

Why it matters

Non-interactive environments (CI/CD pipelines, scripted invocation via claude -p, resource-constrained systems) have no use for background task management. This flag provides opt-out control for environments where backgrounding is irrelevant or undesired, and for debugging scenarios where foreground-only execution aids visibility.

Caveats

Status is code review only. Actual runtime behavior—whether Ctrl+B truly becomes inert, whether tasks in fact run foreground-only, whether both mechanisms are fully suppressed—remains unverified by test execution. Manual verification steps exist in test results but have not been performed. Authority: implementation review, not empirical observation.

Evidence & receipt

file2.1.4/tests/01-disable-background-tasks/TEST-RESULTS.md

◇ ed25519 receipt

idprimitive_f48ff5a3bd6910a7deea221d

alged25519

pubkey9b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd

sig

6c6354ed8aadabc128006b47b4d9b9567ab4093f4985674ec4a05f6882c82213ed7c0b7c2b760d517915aa4304eef181ae260e96b3cb179a8580f63aed7fea01

Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.

Connected

instance-of Scheduler / IPC Class
introduces (in) 2.1.4 Test (2.1.4) Release
verifies (in) CLAUDE_CODE_DISABLE_BACKGROUND_TASKS — runtime test Test

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

Primitive

Kind	Primitive
Introduced	Claude Code 2.1.4
Class	Scheduler / IPC
Epistemic	inconclusive · runtime-test
Evidence	1 ref
Receipt	ed25519 · verifiable

Hands-on runtime test · Claude Code 2.1.4

Cite this page

Hunter, R. "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS." The Runtime Atlas. Content-addressed entity primitive_f48ff5a3bd6910a7deea221d, ed25519-signed (integrity, not third-party timestamp). https://ryanhunter.io/atlas/e/2-1-4-disable-background-tasks

@misc{atlas-2-1-4-disable-background-tasks,
  title  = {CLAUDE_CODE_DISABLE_BACKGROUND_TASKS},
  author = {Hunter, Ryan},
  note   = {The Runtime Atlas; entity primitive_f48ff5a3bd6910a7deea221d; ed25519-signed for integrity},
  url    = {https://ryanhunter.io/atlas/e/2-1-4-disable-background-tasks}
}