anthropics / anthropics/claude-code

Desktop app: multi-agent Workflow run white-screens the app and starves an 8 GB machine; in-flight subagent work is lost

Aperta
#92,829 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area:agents area:desktop bug perf:memory platform:macos
Lingua principale
Python
Stelle
145k
Fork
23.1k
Metriche di merge delle PR
Metriche PR in attesa

Descrizione

# Bug report — Claude Code desktop: multi-agent Workflow run freezes the app (white screen) and starves the machine on 8 GB RAM

## Environment
- Claude Code **desktop app** (Code tab), macOS `Darwin 25.4.0`
- Hardware: `Mac15,5` — **8 CPU cores, 8 GB RAM** (no swap headroom to spare)
- Session: single interactive session, no `--print`, no cron
- Also running (typical dev machine): Chrome, Docker Desktop (started by a subagent for a container-based test), a remote-desktop app

## What happened
1. I ran the **Workflow tool** with 6 work items. Each item is a pipeline: 1 implementation subagent → 2 review subagents in parallel → conditional fix + re-review. Worst case ≈ 24 subagents over the run; concurrency is capped by the runtime at `min(16, cpus - 2)` = **6 concurrent subagents** on this machine.
2. Subagents do real work: `git worktree add`, `npm`/`npx jest` suites (hundreds of tests), `tsc --noEmit` on a large Next.js app, `kubectl` reads, and — for one item — `docker run nginx` for a container-based verification.
3. Roughly 10–15 minutes in, the **Claude Code window went white and stopped responding**. The whole machine became unusable (heavy swapping). I had to force-quit and reopen the app.
4. Earlier in the same session, another workflow had completed: **22 subagents, ~4.1 M subagent tokens, 786 tool calls, ~63 minutes**. That one survived, but the machine was already under pressure.

## Impact
- The background workflow was killed with **no completion record**; the app reported "no completion record was found … it may have been running when the previous process exited".
- **Work from 4 of 6 in-flight subagents was lost.** Only the 2 subagents that had already finished (and pushed their branches to git) survived, because `journal.jsonl` records a result **only when an agent completes**. Everything an in-flight agent had done (file edits inside its worktree were partially there, but its reasoning/state was gone) had to be redone.
- Resume worked (`resumeFromRunId`), but re-running the 4 lost agents cost the full token spend again.

## Why I think it happens
Concurrency is derived from **CPU count only** (`min(16, cpus - 2)`). On a 16-core / 8 GB machine that formula allows up to 14 concurrent subagents; here it allowed 6 — but each subagent can hold a Node/jest/tsc process tree worth several hundred MB, and one was running a Docker container. Free memory dropped to ~60 MB (measured after the crash: `Pages free: 3738` × 16 KB). The Electron renderer appears to be a victim of that pressure rather than the cause — it turns white and never recovers.

## What would prevent recurrence (in rough priority order)
1. **Gate subagent concurrency on available memory, not just CPU count.** Something like "don't start another subagent while free+inactive memory is under N GB", with N scaled to the machine. A 16-core / 8 GB laptop and a 16-core / 64 GB workstation should not get the same fan-out.
2. **Expose `maxConcurrency` (or a memory budget) as a Workflow tool input**, so the caller can self-limit when it knows the subagents are heavy (jest/tsc/docker) rather than token-only.
3. **Checkpoint in-flight subagents, not just completed ones.** Writing partial agent state (or at least "started + last tool result") to `journal.jsonl` would make a crash lose minutes instead of a full agent run.
4. **Make the renderer survive memory pressure** — or at least fail visibly (an error state you can reload) instead of a permanent white window that requires force-quitting the app.
5. **Warn at workflow launch on low-memory machines**: "this workflow may run up to N concurrent subagents; this machine has 8 GB RAM" is enough for the caller to reduce the plan.

## Workaround I applied
Restructured the script to process the work items in **waves of 2** (max ~4 concurrent subagents instead of 6) and made every subagent's setup step idempotent, so a resume picks up existing worktrees/branches instead of failing on `git worktree add -b`.

No confidential project details are included in this report; it is about the harness behaviour only.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Start from the Workflow tool and desktop Code tab behavior described in the report, especially concurrency derived from CPU count and completion-only writes to journal.jsonl. Reproduce with a memory-heavy multi-agent workflow on an 8 GB macOS machine if possible. Done would require an agreed design and implementation for memory-aware concurrency, user limits, checkpointing, or renderer failure handling.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
docker, electron, kubernetes, macos, next.js, node.js, typescript
Ambito
ai-infra-agents, desktop, performance, tooling
Tipo di issue
Bug
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
28/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.