--append-system-prompt-file is not cumulative — only the last flag is honored

Summary

When --append-system-prompt-file is passed multiple times in a single claude invocation, only the last file is appended to the system prompt. All preceding flags are silently discarded. The flag name implies it should be cumulative ("append"), but the parser overwrites instead.

Reproduction

echo "Context 1: I am the FIRST context file." > /tmp/ctx1.txt
echo "Context 2: I am the SECOND context file." > /tmp/ctx2.txt

# Test 1: only ctx1 — works
claude -p --append-system-prompt-file /tmp/ctx1.txt \
  "Echo any line containing 'I am the' from your system prompt."
# → Context 1: I am the FIRST context file.

# Test 2: only ctx2 — works
claude -p --append-system-prompt-file /tmp/ctx2.txt \
  "Echo any line containing 'I am the' from your system prompt."
# → Context 2: I am the SECOND context file.

# Test 3: ctx1 then ctx2 — only ctx2 wins
claude -p --append-system-prompt-file /tmp/ctx1.txt \
        --append-system-prompt-file /tmp/ctx2.txt \
  "Echo any line containing 'I am the' from your system prompt."
# → Context 2: I am the SECOND context file.    ← ctx1 silently dropped

# Test 4: ctx2 then ctx1 — only ctx1 wins
claude -p --append-system-prompt-file /tmp/ctx2.txt \
        --append-system-prompt-file /tmp/ctx1.txt \
  "Echo any line containing 'I am the' from your system prompt."
# → Context 1: I am the FIRST context file.    ← ctx2 silently dropped

Expected behavior

Each --append-system-prompt-file flag should append its contents to the system prompt cumulatively, in the order specified. This matches the semantic of "append" and matches how multi-value flags typically behave (e.g. --add-dir is cumulative).

Actual behavior

Only the value from the last --append-system-prompt-file flag is honored. Preceding flags are silently dropped — no warning, no error.

Impact

We use Claude Code in an internal session orchestrator (BrainMon) that lets users select multiple saved "context" files when starting a new session — e.g. a project context + a recent handoff doc + a feature spec. The naive approach of passing one --append-system-prompt-file per selected file worked for one file but silently dropped all but the last when multiple were selected.

Workaround

We now concatenate all selected context files into a single merged temp file (with section separators) and pass that one file via a single --append-system-prompt-file flag. This works correctly.

# Concatenate into one merged file with separators
merged_path = f"/tmp/brainmon-ctx/merged-{random}.md"
with open(merged_path, "w") as out:
    for idx, ctx_file in enumerate(context_files):
        if idx > 0:
            out.write("\n\n---\n\n")
        out.write(f"# Context {idx + 1}: {basename(ctx_file)}\n\n")
        out.write(open(ctx_file).read())

# Then pass once
cmd = f"claude --append-system-prompt-file {shlex.quote(merged_path)}"

Suggested fix

The CLI parser should treat --append-system-prompt-file as a repeatable flag (e.g. commander.js .option('-f, --append-system-prompt-file <file>', ..., collect, [])) and append each file's contents to the system prompt in argument order. Same for --system-prompt-file if it has the same issue (haven't tested).

Environment

• Claude Code version: claude --version output (latest as of 2026-04-09)
• OS: Linux (Ubuntu 24.04)
• Also reproduces with --output-format json and interactive mode

Related

The flag isn't documented in claude --help directly — only mentioned inside the --bare flag's description as something users can use. Documenting it as a top-level flag with explicit cumulative semantics would also help.