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
- 主要语言
- Python
- 星标
- 145k
- 派生
- 23.1k
- PR 合并指标
- PR 指标待抓取
描述
# 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.
贡献指南
这个仓库没有索引到贡献指南
调研方向
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.
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- docker, electron, kubernetes, macos, next.js, node.js, typescript
- 领域
- ai-infra-agents, desktop, performance, tooling
- Issue 类型
- 缺陷
- 难度
- 5/5
- 预计耗时
- 一周以上
- 活跃度
- 活跃
- 描述清晰度
- 基本清楚
- 新手友好度
- 28/100