[CLI] specstory run claude busy-waits at 20-50% CPU per instance when child process is idle (waiting for user input)

[mickaelperrin]

Summary

When using specstory run claude with multiple concurrent sessions, the specstory parent process consumes 20–50% CPU per instance even when the wrapped claude child process is completely idle (waiting for user input at the prompt).

This appears to be a busy-wait / active polling loop in specstory's I/O monitoring of the child process, rather than using blocking I/O primitives (select/poll/epoll/kqueue).

Environment

• specstory version: 1.12.0
• OS: Darwin arm64 (macOS)
• claude version: 2.1.83 (Claude Code)
• invocation: specstory run claude -c /path/to/claude --settings /path/to/settings.json --silent --no-version-check --local-time-zone

Reproduction

1. Open multiple terminal sessions (20+) each running specstory run claude
2. Leave all sessions idle at the Claude prompt (waiting for user input)
3. Observe CPU usage with ps aux | grep specstory

Observed Behavior

With 21 concurrent sessions all idle (claude children waiting for input):

#	specstory CPU%	specstory state	claude child CPU%	claude child state
1	46.0	R+	0.0	S+
2	42.4	R+	0.0	S+
3	31.2	R+	0.0	S+
4	22.8	R+	0.0	S+
5	35.1	R+	0.0	S+
6	37.9	R+	0.0	S+
7	30.2	R+	0.0	S+
8	34.1	R+	0.0	S+
9	34.8	R+	0.0	S+
10	38.2	R+	0.0	S+
11	51.9	R+	0.0	S+
12	23.4	R+	0.0	S+
13	20.1	R+	0.0	S+
14	37.8	R+	0.0	S+
15	25.7	R+	0.0	S+
16	41.9	R+	0.0	S+
17	30.1	R+	0.0	S+
18	40.4	R+	0.0	S+
19	46.0	R+	0.0	S+
20	42.4	R+	0.0	S+
21	35.1	R+	0.0	S+

Totals:

• specstory total CPU: ~746%
• claude children total CPU: ~2.9%
• All specstory processes: R+ (running, foreground) — actively consuming CPU
• All claude children: S+ (sleeping, foreground) — idle, waiting for input

Expected Behavior

When the child process is idle (waiting at its input prompt), specstory should block on I/O (using select, poll, epoll, or kqueue) consuming ~0% CPU, exactly like the child itself does.

Impact

• Machine unusable with 20+ concurrent sessions (fans spinning, battery drain)
• ~750% wasted CPU from idle monitoring
• No workaround available — the specstory CLI has no --poll-interval or --no-poll flags
• Disabling specstory entirely (NO_SPECSTORY=1) is the only current workaround, but loses transcript history

Suggested Fix

Replace the busy-wait polling loop with a proper blocking I/O wait (kqueue on macOS / epoll on Linux) when monitoring the child process's stdout/stderr. The specstory process should only wake up when there is actual data to read from the child.

[m2ux]

Same issue for me. Specstory is effectively unusable for me until this is fixed.

[belucid]

@mickaelperrin specstory run doesn't actually monitor the child process' stdout/err. That's not how it works. It simply runs Claude then watches the file system for Claude Code JSONL entries, using fsnotify.

SpecStory starting Claude is just a nicety, but not required. What happens if you run specstory watch in the project, and then run Claude separately?

[mickaelperrin]

I will try it and will provide feedback. Thanks for the answer

[mickaelperrin]

@belucid Thanks for the clarification about fsnotify.

I've now switched to specstory watch running separately (background process, Claude launched independently). I ran several tests to narrow down the root cause.

Test 1: specstory watch (separate from Claude)

Same behavior as specstory run:

specstory watch claude --output-dir .../intents/history --silent --no-version-check --local-time-zone

27 instances, each consuming 21-31% CPU in R+ (running) state. Total: ~655% CPU.

Test 2: --no-cloud-sync flag

Added --no-cloud-sync to all instances. Initially the new processes started at 0% CPU (S+), but after a few minutes the busy-wait returned at 19-21% CPU per process. Cloud sync is not the cause.

Key finding: file count correlation

Tested across 4 different projects, same version (1.12.0), same flags (including --no-cloud-sync):

Project	Files in output-dir	Processes	CPU per process	State
Project A	~2850	10	19-21%	R+ (running)
Project B	39	2	0.0%	S+ (sleeping)
Project C	17	1	0.0%	S+ (sleeping)
Project D	4	1	0.0%	S+ (sleeping)

100% of processes watching a directory with ~2850 files are busy-waiting. 100% of processes watching directories with 4-39 files are idle at 0% CPU.

The busy-wait also appears progressively — new processes start at 0% and ramp up over a few minutes.

Summary of eliminated causes

Hypothesis	Tested	Result
specstory run vs specstory watch	✅	Same behaviour with both
Cloud sync (--no-cloud-sync)	✅	No effect — busy-wait returns
File count in output-dir	✅ Confirmed across 4 projects	4-39 files → 0% CPU; ~2850 files → 19-21% CPU