E2BIG when launching Claude on Linux — --agents JSON exceeds 128KB per-argument kernel limit

[TickTockBent]

Description

il spin fails with spawn E2BIG on Linux when launching Claude because the total command-line arguments to claude exceed the kernel's ARG_MAX limit (2MB on Linux).

The launchClaude() function in src/utils/claude.ts passes the system prompt, MCP configs, agents JSON, and allowed tools list as CLI arguments via --append-system-prompt, --mcp-config, --agents, and --allowed-tools. When the system prompt is large (which is common with iloom's template system), the combined argument + environment size exceeds execve()'s limit.

Reproduction

1. Set up a project with iloom on Linux
2. Run il start <issue-number> or il spin from a worktree
3. Observe spawn E2BIG error when Claude is launched

❌ Failed to spin up loom: Claude CLI error: Command failed with E2BIG: claude --model opus --permission-mode bypassPermissions --add-dir /path/to/worktree --add-dir /tmp --append-system-prompt <massive system prompt>...

This reproduces regardless of terminal backend (tested with tmux and direct invocation).

Root Cause

Linux execve() enforces ARG_MAX (typically 2MB) as the combined limit for arguments + environment. The system prompt alone can be very large, and combined with MCP configs, agents JSON, and tool lists, the total easily exceeds this limit.

On macOS, ARG_MAX is 1MB but the effective limit is stack_size/4 which is typically much larger (~16MB), so this issue may not manifest there.

Possible Solutions

1. Write system prompt to a temp file: Use --append-system-prompt-file <path> (if Claude CLI supports it) instead of inline
2. Pass large args via stdin: Pipe the configuration to Claude as JSON on stdin instead of CLI args
3. Use environment variables: Store the system prompt in an env var (though this counts toward the same limit)
4. Write a wrapper script: Generate a temp script with the full command and execute that

Environment

• Linux 6.8.0-90-generic (Ubuntu)
• iloom-cli v0.10.2
• Node.js v22.12.0
• ARG_MAX: 2097152

Related

• PR feat: add Linux, WSL, and tmux terminal backends #796 (Linux terminal backend support) — this issue was discovered while testing Linux terminal backends
• Issue il start fails on Linux: terminal window launching not supported #795 (Linux support tracking)

[TickTockBent]

Correction: Per-Argument Limit, Not ARG_MAX

Further investigation reveals this is not the total ARG_MAX limit (2MB) but a per-argument limit of ~128KB imposed by the Linux kernel.

Evidence

# 500KB across 500 small args: OK
subprocess.run(['echo'] + ['x' * 1000] * 500)  # ✅ works fine

# 200KB as a single argument: E2BIG  
subprocess.run(['echo', 'x' * 200000])  # ❌ Argument list too long

# Binary search finds the breakpoint at ~131KB per argument

Why This Matters

The --agents flag passes the entire agents configuration as a single JSON argument — all 8-9 agent definitions including their full prompt text (215KB total). This single argument exceeds the ~128KB per-argument kernel limit, triggering E2BIG.

The --append-system-prompt flag passes the rendered system prompt as another single argument (~80KB), which is under the limit but dangerously close.

The Architectural Issue

Stuffing 215KB of agent prompts into a single CLI argument is... a bold choice. The --mcp-config flag already supports file paths ("Load MCP servers from JSON files or strings"), so the pattern for file-based input exists in the codebase — it just wasn't applied to --agents or --append-system-prompt, which are the two flags most likely to carry large payloads.

Suggested Fix

The fix is straightforward since the limit is per-argument, not total:

1. --agents (the actual offender at 215KB): Support file path input, same as --mcp-config already does. Detect if the value is a file path vs inline JSON and read accordingly.
2. --append-system-prompt (80KB, currently OK but fragile): Same treatment — accept a file path as an alternative to inline text.

Alternatively, iloom could work around this by writing large args to temp files and passing file paths, if the Claude CLI flags are updated to support it.

Environment Details

• Linux 6.8.0-90-generic (Ubuntu)
• getconf ARG_MAX reports 2097152 (2MB) — misleading, the per-arg limit is ~128KB
• ulimit -s is 8192 (8MB stack), so stack/4 = 2MB — this is the TOTAL limit, not per-arg

[TickTockBent]

Upstream Blocker: Claude Code lacks --agents-file flag

The --agents flag only accepts inline JSON strings — it does not support file paths (tested: passing a file path is silently ignored, the agents don't load).

Since the agents JSON is the primary offender at 215KB (well over the 128KB per-argument kernel limit), and there's no file-based alternative, this is blocked on Claude Code adding file-based input for --agents.

Filed upstream: anthropics/claude-code#29060

What already works (but doesn't help here)

• --append-system-prompt-file ./file.txt — file-based system prompt ✅ (but the system prompt is only 80KB, under the limit)
• --mcp-config — accepts file paths ✅
• --settings <file> — accepts file paths, but the settings schema has no agents key

What's needed

An --agents-file <path> flag (or --agents auto-detecting file paths like --mcp-config does) so the 215KB agents JSON can be read from disk instead of being crammed into a single CLI argument that the Linux kernel summarily rejects.

Workaround potential

iloom could work around this by stripping agent prompts from the JSON and embedding them in the system prompt via --append-system-prompt-file, but that would fundamentally change how agents work (losing structured agent metadata like model, tools, color). Not a clean path.

[TickTockBent]

Agent Payload Breakdown: The 215KB is All Prompt Bloat

Did a deep dive into how iloom constructs the --agents JSON. MCP configs and system prompts are not bundled into it — they're passed via separate flags (--mcp-config, --append-system-prompt). The --agents payload is purely agent definitions loaded from templates/agents/*.md via AgentManager.formatForCli() → JSON.stringify(agents).

Here's what's actually in those 215KB:

Agent Template	Size
iloom-issue-analyze-and-plan.md	~37KB
iloom-issue-analyzer.md	~32KB
iloom-issue-planner.md	~28KB
iloom-code-reviewer.md	~26KB
iloom-issue-enhancer.md	~24KB
iloom-issue-implementer.md	~21KB
iloom-issue-complexity-evaluator.md	~20KB
iloom-artifact-reviewer.md	~12KB
JSON overhead + metadata	~15KB
Total	~215KB

Every agent template is a verbose markdown file with detailed behavioral instructions. They're all loaded for every workflow regardless of which agents are actually needed for the current task. The formatForCli() method does zero filtering or transformation — it dumps the entire agent registry as one JSON string into argv.

Possible iloom-side mitigations (independent of upstream --agents-file)

1. Lazy agent loading: Only include agents actually referenced by the current workflow instead of the full registry. A typical workflow uses 2-3 agents, not all 8. This alone would likely bring the payload under 128KB.
2. Prompt compression: Several agent prompts contain repeated boilerplate (formatting rules, tool usage guidelines, etc.) that could be factored into the system prompt instead.
3. File-based passthrough: Write the agents JSON to a temp file and pass the path — blocked on upstream (Feature request: --agents-file flag to read agents JSON from a file anthropics/claude-code#29060) but would solve it permanently.

[acreeger]

@TickTockBent recent work I've done has given me some ideas of how to handle this. Unfortunately, we can't extract the common instructions for the agents into the system prompt because the agent definition is the system prompt for the sub agents when they're with the Agent definition.

Instead, I'm gonna explore rendering the agents to a sub folder of the worktree (as I do in Swarm mode), then trying using the --agent flag to load the agent in the main Claude shell. I'm not sure when that flag was added, but that should do the trick. The MCP conflict can come from JSON file.