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

Offen
#92,829 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area:agents area:desktop bug perf:memory platform:macos
Vorherrschende Sprache
Python
Sterne
145k
Forks
23.1k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

# 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.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
docker, electron, kubernetes, macos, next.js, node.js, typescript
Bereich
ai-infra-agents, desktop, performance, tooling
Issue-Typ
Bug
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
28/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.