Live/monitor mode fails with text output format - build_claude_command not called

[SimonHeistermann]

Bug Description

When using CLAUDE_OUTPUT_FORMAT="text" in .ralphrc combined with --live or --monitor flags, Ralph fails with:

stdbuf: unrecognized option '--verbose'

Root Cause

In ralph_loop.sh lines 1047-1057, build_claude_command() is only called when CLAUDE_OUTPUT_FORMAT="json":

if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
    if build_claude_command "$PROMPT_FILE" "$loop_context" "$session_id"; then
        use_modern_cli=true
    fi
else
    log_status "INFO" "Using legacy CLI mode (text output)"
fi
However, when LIVE_OUTPUT=true (lines 1065+), the code still tries to use CLAUDE_CMD_ARGS which is empty/uninitialized for text mode. This results in stdbuf -oL receiving --verbose as its first argument instead of the claude command.

Steps to Reproduce
Set .ralphrc: CLAUDE_OUTPUT_FORMAT="text"
Run: ralph --live or ralph --monitor
Observe error: stdbuf: unrecognized option '--verbose'
Expected Behavior
Either:

Call build_claude_command() for text mode too, OR
Disable live/monitor mode when text format is used, OR
Build LIVE_CMD_ARGS independently for text mode
Environment
Ralph version: v0.11.4
macOS with GNU coreutils
Claude Code CLI: 2.1.32

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#58 - fix(loop): replace non-existent --prompt-file with -p flag [merged]
#125 - feat: Add live streaming output mode with real-time Claude Code visibility [merged]
#130 - fix(wizard): redirect prompts to stderr for clean command substitution [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Plan

Observations

The bug occurs in file:ralph_loop.sh at lines 1049-1059 where build_claude_command() is only invoked when CLAUDE_OUTPUT_FORMAT="json". When text format is used with --live or --monitor flags, the CLAUDE_CMD_ARGS array remains empty. Subsequently, at line 1093-1110, LIVE_CMD_ARGS is built from the empty CLAUDE_CMD_ARGS, resulting in only streaming flags (--verbose --include-partial-messages) being passed to stdbuf, causing it to fail with "unrecognized option '--verbose'".

The build_claude_command() function (lines 948-1007) is already designed to handle both json and text formats—it only conditionally adds --output-format json at lines 966-968, but builds the complete command array with all other flags for both formats.

Approach

The fix is straightforward: call build_claude_command() for both json and text output formats. The function already handles text mode correctly by omitting the --output-format flag while still building the complete command array with all necessary arguments (--allowedTools, --resume, --append-system-prompt, -p). This ensures CLAUDE_CMD_ARGS is properly populated for live mode regardless of output format.

Additionally, add validation to detect when live mode is requested with text format and either warn the user or automatically switch to json format, since stream-json output (required for live mode) is inherently JSON-based.

Implementation Steps

1. Fix Command Building Logic

Location: file:ralph_loop.sh lines 1044-1059

Modify the conditional logic to call build_claude_command() for both json and text formats:

• Remove the if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]] condition
• Always call build_claude_command() to populate CLAUDE_CMD_ARGS
• Set use_modern_cli=true when the function succeeds
• Keep the informational log messages to indicate which mode is being used

2. Add Live Mode Compatibility Check

Location: file:ralph_loop.sh lines 1067-1086

Add validation before entering live mode to ensure compatibility:

• Check if LIVE_OUTPUT=true and CLAUDE_OUTPUT_FORMAT="text"
• If both conditions are true, log a warning that live mode requires JSON output
• Automatically override CLAUDE_OUTPUT_FORMAT to "json" for this execution
• Log the override action so users understand the behavior
• Alternatively, disable live mode and fall back to background mode with a clear warning

3. Update Live Mode Command Building

Location: file:ralph_loop.sh lines 1091-1110

Ensure the live mode command building handles the case properly:

• The existing logic at lines 1093-1110 that builds LIVE_CMD_ARGS from CLAUDE_CMD_ARGS should work correctly once step 1 is implemented
• Add a safety check to verify CLAUDE_CMD_ARGS is not empty before building LIVE_CMD_ARGS
• If empty, log an error and fall back to background mode

4. Update Documentation and Help Text

Location: file:ralph_loop.sh lines 1593-1647

Update the help text to clarify live mode requirements:

• Add a note to the --live flag description (line 1609) indicating it requires JSON output format
• Add a note to the --output-format flag description (line 1616) indicating text format is incompatible with live mode
• Update example at line 1642 to show that --output-format text should not be combined with --live

5. Verify Background Mode Compatibility

Location: file:ralph_loop.sh lines 1186-1213

Ensure background mode still works correctly with text format:

• The existing fallback logic at lines 1202-1213 (legacy stdin piping) should continue to work for text mode
• Verify that when use_modern_cli=false, the legacy mode is used as a fallback
• This ensures backward compatibility for users who prefer text output in background mode

sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant build_claude_command
    participant Claude CLI

    User->>ralph_loop.sh: ralph --live (with text format in .ralphrc)
    ralph_loop.sh->>ralph_loop.sh: Check LIVE_OUTPUT=true
    ralph_loop.sh->>ralph_loop.sh: Check CLAUDE_OUTPUT_FORMAT="text"
    ralph_loop.sh->>ralph_loop.sh: Override to "json" with warning
    ralph_loop.sh->>build_claude_command: Call with prompt, context, session_id
    build_claude_command->>build_claude_command: Build CLAUDE_CMD_ARGS array
    build_claude_command->>build_claude_command: Add --output-format json
    build_claude_command->>build_claude_command: Add other flags
    build_claude_command-->>ralph_loop.sh: Return success
    ralph_loop.sh->>ralph_loop.sh: Build LIVE_CMD_ARGS from CLAUDE_CMD_ARGS
    ralph_loop.sh->>ralph_loop.sh: Replace json with stream-json
    ralph_loop.sh->>ralph_loop.sh: Add --verbose --include-partial-messages
    ralph_loop.sh->>Claude CLI: Execute stdbuf -oL "${LIVE_CMD_ARGS[@]}"
    Claude CLI-->>ralph_loop.sh: Stream output
    ralph_loop.sh-->>User: Display live output

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The bug occurs in `file:ralph_loop.sh` at lines 1049-1059 where `build_claude_command()` is only invoked when `CLAUDE_OUTPUT_FORMAT="json"`. When text format is used with `--live` or `--monitor` flags, the `CLAUDE_CMD_ARGS` array remains empty. Subsequently, at line 1093-1110, `LIVE_CMD_ARGS` is built from the empty `CLAUDE_CMD_ARGS`, resulting in only streaming flags (`--verbose --include-partial-messages`) being passed to `stdbuf`, causing it to fail with "unrecognized option '--verbose'".

The `build_claude_command()` function (lines 948-1007) is already designed to handle both json and text formats—it only conditionally adds `--output-format json` at lines 966-968, but builds the complete command array with all other flags for both formats.

## Approach

The fix is straightforward: call `build_claude_command()` for both json and text output formats. The function already handles text mode correctly by omitting the `--output-format` flag while still building the complete command array with all necessary arguments (`--allowedTools`, `--resume`, `--append-system-prompt`, `-p`). This ensures `CLAUDE_CMD_ARGS` is properly populated for live mode regardless of output format.

Additionally, add validation to detect when live mode is requested with text format and either warn the user or automatically switch to json format, since stream-json output (required for live mode) is inherently JSON-based.

## Implementation Steps

### 1. Fix Command Building Logic

**Location:** `file:ralph_loop.sh` lines 1044-1059

Modify the conditional logic to call `build_claude_command()` for both json and text formats:

- Remove the `if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]` condition
- Always call `build_claude_command()` to populate `CLAUDE_CMD_ARGS`
- Set `use_modern_cli=true` when the function succeeds
- Keep the informational log messages to indicate which mode is being used

### 2. Add Live Mode Compatibility Check

**Location:** `file:ralph_loop.sh` lines 1067-1086

Add validation before entering live mode to ensure compatibility:

- Check if `LIVE_OUTPUT=true` and `CLAUDE_OUTPUT_FORMAT="text"`
- If both conditions are true, log a warning that live mode requires JSON output
- Automatically override `CLAUDE_OUTPUT_FORMAT` to "json" for this execution
- Log the override action so users understand the behavior
- Alternatively, disable live mode and fall back to background mode with a clear warning

### 3. Update Live Mode Command Building

**Location:** `file:ralph_loop.sh` lines 1091-1110

Ensure the live mode command building handles the case properly:

- The existing logic at lines 1093-1110 that builds `LIVE_CMD_ARGS` from `CLAUDE_CMD_ARGS` should work correctly once step 1 is implemented
- Add a safety check to verify `CLAUDE_CMD_ARGS` is not empty before building `LIVE_CMD_ARGS`
- If empty, log an error and fall back to background mode

### 4. Update Documentation and Help Text

**Location:** `file:ralph_loop.sh` lines 1593-1647

Update the help text to clarify live mode requirements:

- Add a note to the `--live` flag description (line 1609) indicating it requires JSON output format
- Add a note to the `--output-format` flag description (line 1616) indicating text format is incompatible with live mode
- Update example at line 1642 to show that `--output-format text` should not be combined with `--live`

### 5. Verify Background Mode Compatibility

**Location:** `file:ralph_loop.sh` lines 1186-1213

Ensure background mode still works correctly with text format:

- The existing fallback logic at lines 1202-1213 (legacy stdin piping) should continue to work for text mode
- Verify that when `use_modern_cli=false`, the legacy mode is used as a fallback
- This ensures backward compatibility for users who prefer text output in background mode

```mermaid
sequenceDiagram
    participant User
    participant ralph_loop.sh
    participant build_claude_command
    participant Claude CLI

    User->>ralph_loop.sh: ralph --live (with text format in .ralphrc)
    ralph_loop.sh->>ralph_loop.sh: Check LIVE_OUTPUT=true
    ralph_loop.sh->>ralph_loop.sh: Check CLAUDE_OUTPUT_FORMAT="text"
    ralph_loop.sh->>ralph_loop.sh: Override to "json" with warning
    ralph_loop.sh->>build_claude_command: Call with prompt, context, session_id
    build_claude_command->>build_claude_command: Build CLAUDE_CMD_ARGS array
    build_claude_command->>build_claude_command: Add --output-format json
    build_claude_command->>build_claude_command: Add other flags
    build_claude_command-->>ralph_loop.sh: Return success
    ralph_loop.sh->>ralph_loop.sh: Build LIVE_CMD_ARGS from CLAUDE_CMD_ARGS
    ralph_loop.sh->>ralph_loop.sh: Replace json with stream-json
    ralph_loop.sh->>ralph_loop.sh: Add --verbose --include-partial-messages
    ralph_loop.sh->>Claude CLI: Execute stdbuf -oL "${LIVE_CMD_ARGS[@]}"
    Claude CLI-->>ralph_loop.sh: Stream output
    ralph_loop.sh-->>User: Display live output
```

---

Execution Information

Branch: main
Commit: abcfa8b

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.