Will It Stay Light When You Run It Unattended? Observing and Capping Claude Code's Long-Session Memory

The Smallest Mechanism to Observe Memory

The first step is not installing a monitoring platform. Periodically writing out RSS with ps tells you a surprising amount. The script below appends the combined RSS of a target process and its children to a CSV every 15 seconds.

#!/usr/bin/env bash
# rss-sample.sh — append combined RSS of a PID and its descendants to a CSV
# usage: ./rss-sample.sh <root_pid> <out.csv> [interval_sec]
set -euo pipefail
 
ROOT_PID="$1"
OUT="$2"
INTERVAL="${3:-15}"
 
# collect descendant PIDs recursively
collect_descendants() {
  local pid="$1"
  echo "$pid"
  for child in $(pgrep -P "$pid" 2>/dev/null || true); do
    collect_descendants "$child"
  done
}
 
# header (first time only)
[ -s "$OUT" ] || echo "ts_epoch,iso,proc_count,rss_kb" >> "$OUT"
 
while kill -0 "$ROOT_PID" 2>/dev/null; do
  pids="$(collect_descendants "$ROOT_PID" | sort -u)"
  count=0
  total=0
  for p in $pids; do
    # ps rss is in KB; ignore PIDs that no longer exist
    kb="$(ps -o rss= -p "$p" 2>/dev/null | tr -d ' ' || true)"
    if [ -n "${kb:-}" ]; then
      total=$(( total + kb ))
      count=$(( count + 1 ))
    fi
  done
  printf '%s,%s,%s,%s\n' "$(date +%s)" "$(date -u +%FT%TZ)" "$count" "$total" >> "$OUT"
  sleep "$INTERVAL"
done

From your headless wrapper, start this sampler in the background right after launching Claude Code.

# excerpt from run-with-sampling.sh
claude -p "$PROMPT" --output-format stream-json > run.log 2>&1 &
CLAUDE_PID=$!
 
./rss-sample.sh "$CLAUDE_PID" "metrics/rss-$(date +%Y%m%d-%H%M%S).csv" 15 &
SAMPLER_PID=$!
 
wait "$CLAUDE_PID"
kill "$SAMPLER_PID" 2>/dev/null || true

That alone gives you a time series of RSS for a single session: the peak, the slope of growth, and whether it ever flattens back down. For the first few runs, plotting and just looking is enough. In my environment, a light article-generation job peaked roughly in the 320–420 MB range, and when I stacked many jobs back-to-back into the same session, that figure slowly drifted upward. The absolute number matters less than the question: does it return to flat, or not?

Catching It With a Threshold — A Rolling-Baseline Watchdog

A fixed threshold (say, "warn above 600 MB") misfires easily across environments, because changing the machine changes the baseline. So instead, build the baseline from recent samples and judge by deviation from it. Using the median and the median absolute deviation (MAD) makes it resistant to transient spikes while reliably catching the onset of bloat.

#!/usr/bin/env python3
# rss-watchdog.py — read the CSV, detect drift via rolling median + MAD
import csv, sys, statistics
 
WINDOW = 20          # recent sample count
K = 6.0              # threshold coefficient (how many MADs to allow)
MIN_SAMPLES = 8      # minimum samples needed to form a baseline
 
def mad(xs, med):
    return statistics.median([abs(x - med) for x in xs]) or 1.0
 
def main(path):
    rss = []
    with open(path) as f:
        for row in csv.DictReader(f):
            rss.append(int(row["rss_kb"]))
 
    if len(rss) < MIN_SAMPLES:
        print("not enough samples"); return 0
 
    # use the stable region after the initial ramp as the baseline
    baseline = rss[2:2 + WINDOW] if len(rss) >= 2 + WINDOW else rss[2:]
    med = statistics.median(baseline)
    spread = mad(baseline, med)
 
    latest = rss[-1]
    threshold = med + K * spread
    drift = (latest - med) / med * 100
 
    print(f"baseline_median={med/1024:.0f}MB latest={latest/1024:.0f}MB "
          f"threshold={threshold/1024:.0f}MB drift={drift:+.1f}%")
 
    if latest > threshold:
        print("ALERT: RSS drifted above rolling baseline")
        return 1
    return 0
 
if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

If your operational loop reads the watchdog's exit code, you can turn it into a decision: "once it starts getting heavy, close out the current job at a safe boundary and move to the next segment." The crucial part is that detection does not mean killing the process immediately — advance the current work to a safe boundary, then cut. Killing mid-flight loses partial results.

Here is the fixed-threshold versus rolling-baseline trade-off laid out:

Splitting a Long Session Into Bounded Segments

Observation and the watchdog are the "notice it" layer. The real fix is not to stack infinitely into one session in the first place. Split a long unattended job into a handful of bounded segments, and end the process at each segment boundary; RSS resets there and levels off.

What makes this work is the ability to resume a session while preserving context. If continuity across segments matters, --resume or --continue carries the prior session forward; if the jobs are fully independent, just start fresh each time. For my own site auto-posting, I use "one segment = one or two articles' worth" as a rule of thumb.

#!/usr/bin/env bash
# segmented-run.sh — run a long job split into bounded segments
set -euo pipefail
 
JOBS=("generate article A" "generate article B" "generate article C" "generate article D")
SEGMENT_SIZE=2   # jobs per segment
 
i=0
session_id=""
while [ "$i" -lt "${#JOBS[@]}" ]; do
  batch=("${JOBS[@]:i:SEGMENT_SIZE}")
  prompt="$(printf '%s\n' "${batch[@]}")"
 
  # use --resume if context must carry over; omit it if independent
  if [ -n "$session_id" ]; then
    claude -p "$prompt" --resume "$session_id" --output-format stream-json > "seg-$i.log" 2>&1
  else
    claude -p "$prompt" --output-format stream-json > "seg-$i.log" 2>&1
  fi
 
  # move to the next segment; the process exits each time, so RSS resets here
  session_id="$(grep -o '"session_id":"[^"]*"' "seg-$i.log" | head -1 | cut -d'"' -f4 || true)"
  i=$(( i + SEGMENT_SIZE ))
done

The key is that the claude process always exits at a segment boundary. The next segment launches as a new process, so the resident memory the previous segment was holding is returned to the OS. If the app's memory reduction makes the hill less steep, this landing is the flat stretch you build on the operations side.

Before / After — One Long Session vs Segmented

Let's compare the RSS behavior of the same four jobs' worth of work, run once in a single long session versus split into segments of two. Reduced to the smallest code, the idea looks like this.

# Before: stack everything into one session (RSS tends to climb)
claude -p "$(printf '%s\n' "${ALL_JOBS[@]}")" --output-format stream-json > run.log 2>&1

# After: split into segments, ending the process at each boundary (RSS resets at each segment start)
for batch in "${SEGMENTS[@]}"; do
  claude -p "$batch" --output-format stream-json > "seg.log" 2>&1
done

The RSS trend I measured in my environment looked roughly like the following. The numbers depend on the machine, so read the shape (does it keep climbing, or return to flat?) rather than the absolute values.

This is not about chasing dramatic numbers. The goal is to keep the peak well clear of the ceiling and to avoid staying high at exit. When it stays high at exit like the Before case, chaining the next task on the same VM carries the leftover forward. When it returns at each segment start like the After case, you can keep going for many segments without nearing the ceiling.

Reading the Numbers and Turning Them Into Decisions

Once you have numbers, there are only three things to watch.

First, how far the peak sits from the ceiling. With a 2 GB ceiling and a 1.5 GB peak, a single spike is within reach of OOM — a cue to shrink segments or raise the ceiling. Second, whether RSS returns at the start of each segment. If it accumulates instead of returning, suspect that the process is not actually exiting (a lingering background child, for instance). Third, whether the time per job stays constant across segments. If only the later ones stretch, that is a sign swapping has begun.

When you wire this into an operational loop, use the watchdog's alert as a signal to bring the next segment boundary forward — never as a trigger to forcibly kill the running process. A forced kill invites loss of partial results and, in the worst case, an inconsistent cleanup afterward. Closing out at a safe boundary, consistently, ends up dropping fewer jobs.

A Next Step

Start with observation alone. It is enough to add one rss-sample.sh to a job you already run unattended and capture a single run's RSS time series to a CSV. Where is the peak, and does it stay high at exit? Once you can see that, the right segment granularity decides itself. Ride the app-side memory reduction, but keep one eye on the measurements. That alone prevents most of the quiet drop-outs.

I hope this helps anyone wrestling with the same unattended-operation headaches. Thank you for reading.