Claude Code Background Task Dies at 30 Minutes?

If a Claude Code background Bash task stops at almost exactly 30 minutes and reports exit code 144, first prove that it received SIGTERM. Do not assume the command timed out, restart it repeatedly, or expect nohup to block a termination signal. Preserve the timestamps and task output, rule out Claude Code's documented cleanup conditions, then run work that must outlive the session under a supervisor started outside Claude Code.

This guide addresses a narrow failure reported on macOS in Claude Code issue 84981. The issue remains open, so the exact internal cause is not confirmed. Use the runaway-child guide when a child process survives and consumes memory instead. Use the Remote Control disconnect guide when the session disconnects but the task itself has not shown a signal or exit status.

Confirm the 30-Minute Pattern Before Changing the Job

The August 8 report describes tracked Bash tasks launched with run_in_background: true on Claude Code 2.1.221 for macOS. The reporter captured two SIGTERM events exactly 1,800 seconds apart and saw exit code 144 when the harness classified a terminated task as failed. They also reported that some tasks crossed a timer boundary normally, so even their evidence does not establish that every background command has a universal 30-minute limit.

Claude Code's official interactive-mode documentation says background Bash commands run asynchronously, write output to a file, and receive a task ID. It documents automatic cleanup when Claude Code exits and termination when output exceeds 5 GB. It does not document a 30-minute lifetime.

Treat these observations as separate facts:

Before retrying, capture the version, platform, start time, stop time, task ID, and last output line. Keep secrets, prompts, repository paths, remote hostnames, and process arguments out of any public report.

claude --version
date -u +%Y-%m-%dT%H:%M:%SZ
uname -a

If you can reproduce safely, use a harmless local probe rather than the production job. Save this as /tmp/claude-bg-probe.sh, then ask Claude Code to run it in the background:

#!/bin/sh
trap 'printf "%s SIGTERM\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >&2; exit 144' TERM
printf "%s started\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
while :; do
  sleep 60
  printf "%s alive\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
done

The useful result is not merely "stopped." You want the last heartbeat, the trapped signal, the task status, and the elapsed time. Stop after one controlled reproduction. Do not leave multiple probes running.

Rule Out the Documented Cleanup Paths

Check four boundaries before attributing the signal to an undocumented timer.

1. Session exit: Claude Code documents that it cleans up background tasks when the session exits. Confirm that the original Claude process stayed alive across the task stop.

2. Output size: Verify the task did not produce gigabytes of logs. Redirect noisy application output to a bounded log with rotation rather than flooding the background-task output file.

3. Explicit stop: Check that neither you nor the agent used the task-stop control. Preserve the transcript around the stop time.

4. Host supervision: Check launch agents, CI timeouts, remote-shell idle policies, sleep behavior, and application wrappers. A task polling over SSH can be terminated locally even when the remote process is healthy.

Also compare one foreground run and one background run with the same harmless probe. If only the tracked background run stops, that narrows the boundary. If both stop, investigate the shell, host, remote connection, or command itself before blaming Claude Code.

Do not delete Claude settings, authentication state, task files, or the repository. Those actions destroy evidence and do not explain a signal delivered to a running process.

Update First, but Keep the Reproduction

Record the affected Claude Code version, then allow the supported native installation to update normally. Claude Code's installation documentation says native installs update automatically in the background. After updating, restart Claude Code once and repeat the harmless probe.

A passing probe on a newer version is useful evidence, but it is not proof of a fix unless the upstream issue or release notes identify one. A failing probe should include both version results in the report.

Avoid changing several variables at once. If you update Claude Code, disable an extension, change Remote Control, and rewrite the job simultaneously, you will not know which boundary mattered.

Move Jobs That Must Outlive Claude Code Outside the Session

Claude Code background Bash is designed for work that continues while the current session handles other prompts. It is still session-managed: official documentation says those tasks are cleaned up when Claude Code exits. A deployment, overnight data job, remote poller, or other process that must survive session cleanup belongs under an operating-system supervisor, CI system, or terminal multiplexer started outside Claude Code.

For an interactive job on macOS or Linux, open a normal terminal that is not a Claude Code Bash task and start a named tmux session:

tmux new-session -d -s long-job \
  'cd /absolute/path/to/project && ./scripts/long-job.sh > long-job.log 2>&1'

Inspect it from that same normal terminal:

tmux list-sessions
tmux attach-session -t long-job

Use launchd, systemd, or your CI provider when the job needs restart policy, resource limits, credentials, or durable scheduling. Store credentials in that supervisor's secret mechanism, not in the command line or log file.

Do not rely on nohup alone for this symptom. nohup addresses hangups, while the reported failure is SIGTERM. Likewise, adding & or disown inside the same tracked Bash invocation does not establish that Claude Code has stopped tracking the process tree. The safer boundary is a supervisor launched outside the affected session.

Verify the External Job and Keep Claude Code Read-Only

After moving the job, verify that it crosses the suspected boundary and produces the intended output:

date -u +%Y-%m-%dT%H:%M:%SZ
tail -n 20 long-job.log

Ask Claude Code to inspect the log and process state without restarting, killing, or modifying the job. The recovery is confirmed when:

• the external job runs beyond the prior failure time;

• its log shows expected progress and no repeated restarts;

• ending the Claude Code session does not stop it;

• the task completes or reaches its own explicit timeout; and

• no orphaned child remains after completion.

Once upstream behavior changes, move short development commands back to Claude Code background tasks if that is more convenient. Keep genuinely durable operations under durable supervision.

Monitor the Upstream Issue With Aident Loadout

You can check the public issue without pasting GitHub credentials into a prompt. Start with:

Follow https://aident.ai/SETUP.md

Then ask your agent:

Check Aident Loadout authentication and Vault status. Discover the current read-only GitHub issue Action, inspect its schema, and preflight a lookup for anthropics/claude-code issue 84981. If it is valid and free, execute it and return only state, updated time, labels, comment count, title, and canonical URL. Do not comment, react, edit, close, or create anything.

The Aident Loadout first-task guide explains the account, Vault, discovery, schema, preflight, and execution sequence. The measurable result is a current issue-state record with zero GitHub writes.

Set up Aident Loadout and monitor the Claude Code issue.

Sources

• Claude Code issue 84981: background tasks receive SIGTERM on an exact timer

• Claude Code interactive mode: background Bash commands

• Claude Code commands reference

• Claude Code installation overview

• tmux official getting-started guide

• Claude Code issue 25188: background task cleanup and long-running processes

Refresh this guide when issue 84981 changes state, Anthropic documents a background-task lifetime, or a current Claude Code release changes session cleanup or task supervision.