feat: enhance live monitoring with jq filters, dashboard, and tmux fallback#209
Open
timothy-20 wants to merge 5 commits intofrankbria:mainfrom
Open
feat: enhance live monitoring with jq filters, dashboard, and tmux fallback#209timothy-20 wants to merge 5 commits intofrankbria:mainfrom
timothy-20 wants to merge 5 commits intofrankbria:mainfrom
Conversation
Add three-level live output verbosity control for streaming mode: - minimal: text + tool names only (original behavior) - normal: + tool errors, stop reasons, session errors, rate limits - verbose: + thinking content, input fragments, successful tool results Implementation: - build_jq_filter() function replaces inline jq filter - RALPH_LIVE_VERBOSITY config with env > .ralphrc > default priority - --live-verbosity CLI flag with validation - tmux session forwards verbosity setting - Templates and setup.sh updated with new config option - 23 new tests with NDJSON stream fixtures - Fix existing test that broke due to rate_limit_event in jq filter
Add Live Claude Output section to ralph_monitor.sh that displays the last 5 lines from .ralph/live.log with 72-char truncation. Shows guidance message when live.log is absent. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When tmux is not installed, --monitor now falls back to live output mode instead of exiting with an error. Displays install instructions and runs with LIVE_OUTPUT=true. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update test count (568 → 596), add RALPH_LIVE_VERBOSITY config variable, add --live-verbosity CLI option, and update test_cli_modern.bats description with live monitoring tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
W1: Add missing argument guard for --live-verbosity flag, consistent
with --session-expiry pattern.
W2: Remove unreachable exit 0 after main() call in
setup_fallback_monitor().
W3: Add rate_limit_event NDJSON fixture and 3 tests verifying
normal/verbose show warning, minimal does not.
S3: Fix misplaced comment in fixtures.bash — move create_test_project
docstring back above its function definition.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
WalkthroughThis PR introduces live output verbosity control by adding a new RALPH_LIVE_VERBOSITY configuration variable (minimal, normal, verbose) and corresponding --live-verbosity CLI flag. Changes include jq-filter parameterization for streaming output, a tmux fallback monitor path, and expanded test coverage. Changes
Sequence DiagramsequenceDiagram
participant User as User (CLI)
participant Config as Config System
participant Parser as CLI Parser
participant Filter as build_jq_filter()
participant Stream as Streaming Pipeline
participant Monitor as ralph_monitor.sh
User->>Parser: --live-verbosity minimal|normal|verbose
Parser->>Config: Read .ralphrc / env override
Config->>Config: RALPH_LIVE_VERBOSITY = "normal" (default)
Parser->>Filter: build_jq_filter(RALPH_LIVE_VERBOSITY)
Filter-->>Parser: jq filter string (verbosity-aware)
Parser->>Stream: Execute Claude with jq filter
Stream->>Stream: Stream output with filter (exclude/include fields by verbosity)
Stream->>Monitor: Write to LIVE_LOG_FILE
Monitor->>Monitor: Display up to 5 lines of live output
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
setup.sh (1)
55-115:⚠️ Potential issue | 🟠 MajorSet restrictive permissions on
.ralphrcafter generation.
.ralphrcis created in this block, but no permission hardening is applied. This leaves config readable by other users on shared systems.🔐 Proposed fix
if [[ -f "$LIB_DIR/enable_core.sh" ]]; then @@ RALPHRCEOF fi + +# Protect project configuration (may contain sensitive settings) +chmod 600 .ralphrcAs per coding guidelines
Set restrictive permissions (600) on .ralphrc file in setup.sh and ralph_enable.sh to protect sensitive configuration.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@setup.sh` around lines 55 - 115, The .ralphrc file is created without permission hardening; after any creation path (the generate_ralphrc pipeline that writes to .ralphrc and the fallback here-doc block terminated by RALPHRCEOF in setup.sh) add a chmod 600 .ralphrc to restrict it to the owner, and mirror the same change in ralph_enable.sh where .ralphrc may be created or written; ensure both the generate_ralphrc -> sed -> .ralphrc branch and the here-doc block (and any write/tee calls in ralph_enable.sh) are followed by a chmod 600 to enforce restrictive permissions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@ralph_loop.sh`:
- Around line 1909-1913: Update the help string for the -m, --monitor option so
it no longer says "requires tmux"; instead indicate it will start a tmux session
if available and fall back to non-tmux monitoring when tmux is absent (e.g.,
change the "-m, --monitor Start with tmux session and live monitor
(requires tmux)" line to mention fallback behavior). Locate the option text for
"-m, --monitor" and adjust the wording to reflect the new behavior (reference
the "--monitor" / "-m" option and "tmux" in your edit).
- Around line 372-382: The fallback function setup_fallback_monitor() currently
sets LIVE_OUTPUT=true and then directly calls main(), causing main() to run
twice because the script's entry block also calls main(); remove the direct call
to main() from setup_fallback_monitor() and make the function simply set
LIVE_OUTPUT=true and return so the outer entry logic invokes main() exactly once
(ensure no other callers rely on setup_fallback_monitor() to invoke main()).
In `@tests/unit/test_cli_modern.bats`:
- Around line 1269-1276: The test "--live-verbosity rejects invalid values"
currently inspects the parser help text instead of exercising runtime
validation; change it to actually run the CLI with an invalid verbosity value
and assert failure: use the existing local script variable
(script="${BATS_TEST_DIRNAME}/../../ralph_loop.sh") and invoke it via Bats' run
with arguments including --live-verbosity invalid_value (e.g. "super-verbose"),
then assert a non-zero exit status (run exit code != 0) and check that stderr or
output contains an appropriate error message about invalid verbosity (match
"invalid" or the allowed choices minimal|normal|verbose) so the test fails if
runtime rejection regresses.
---
Outside diff comments:
In `@setup.sh`:
- Around line 55-115: The .ralphrc file is created without permission hardening;
after any creation path (the generate_ralphrc pipeline that writes to .ralphrc
and the fallback here-doc block terminated by RALPHRCEOF in setup.sh) add a
chmod 600 .ralphrc to restrict it to the owner, and mirror the same change in
ralph_enable.sh where .ralphrc may be created or written; ensure both the
generate_ralphrc -> sed -> .ralphrc branch and the here-doc block (and any
write/tee calls in ralph_enable.sh) are followed by a chmod 600 to enforce
restrictive permissions.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
CLAUDE.mdlib/enable_core.shralph_loop.shralph_monitor.shsetup.shtemplates/ralphrc.templatetests/helpers/fixtures.bashtests/unit/test_cli_modern.bats
Comment on lines
+372
to
+382
| # Fallback when tmux is not available: run with live output only | ||
| setup_fallback_monitor() { | ||
| echo "tmux is not installed. Falling back to live output mode." | ||
| echo "Install tmux for the full monitoring dashboard:" | ||
| echo " Ubuntu/Debian: sudo apt-get install tmux" | ||
| echo " macOS: brew install tmux" | ||
| echo " CentOS/RHEL: sudo yum install tmux" | ||
| echo "" | ||
| LIVE_OUTPUT=true | ||
| main | ||
| } |
Contributor
There was a problem hiding this comment.
Fallback monitor currently triggers main() twice.
Line 381 calls main inside setup_fallback_monitor(), and main is called again at Line 2089 in the entry block. After a normal loop exit, fallback mode can immediately restart and consume extra API calls.
🐛 Proposed fix
setup_fallback_monitor() {
echo "tmux is not installed. Falling back to live output mode."
@@
echo " CentOS/RHEL: sudo yum install tmux"
echo ""
LIVE_OUTPUT=true
- main
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ralph_loop.sh` around lines 372 - 382, The fallback function
setup_fallback_monitor() currently sets LIVE_OUTPUT=true and then directly calls
main(), causing main() to run twice because the script's entry block also calls
main(); remove the direct call to main() from setup_fallback_monitor() and make
the function simply set LIVE_OUTPUT=true and return so the outer entry logic
invokes main() exactly once (ensure no other callers rely on
setup_fallback_monitor() to invoke main()).
Comment on lines
1909
to
1913
| -m, --monitor Start with tmux session and live monitor (requires tmux) | ||
| -v, --verbose Show detailed progress updates during execution | ||
| -l, --live Show Claude Code output in real-time (auto-switches to JSON output) | ||
| --live-verbosity LEVEL Set live output verbosity: minimal, normal, verbose (default: $RALPH_LIVE_VERBOSITY) | ||
| -t, --timeout MIN Set Claude Code execution timeout in minutes (default: $CLAUDE_TIMEOUT_MINUTES) |
Contributor
There was a problem hiding this comment.
Help text for --monitor is now stale.
--monitor no longer strictly requires tmux because fallback mode exists, but help still says “requires tmux”.
📝 Proposed fix
- -m, --monitor Start with tmux session and live monitor (requires tmux)
+ -m, --monitor Start with tmux monitor (falls back to --live if tmux is unavailable)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ralph_loop.sh` around lines 1909 - 1913, Update the help string for the -m,
--monitor option so it no longer says "requires tmux"; instead indicate it will
start a tmux session if available and fall back to non-tmux monitoring when tmux
is absent (e.g., change the "-m, --monitor Start with tmux session and
live monitor (requires tmux)" line to mention fallback behavior). Locate the
option text for "-m, --monitor" and adjust the wording to reflect the new
behavior (reference the "--monitor" / "-m" option and "tmux" in your edit).
Comment on lines
+1269
to
+1276
| @test "--live-verbosity rejects invalid values" { | ||
| local script="${BATS_TEST_DIRNAME}/../../ralph_loop.sh" | ||
| # The parser checks for minimal|normal|verbose | ||
| run grep -A3 '\-\-live-verbosity)' "$script" | ||
| [[ "$output" == *"minimal"* ]] | ||
| [[ "$output" == *"normal"* ]] | ||
| [[ "$output" == *"verbose"* ]] | ||
| } |
Contributor
There was a problem hiding this comment.
--live-verbosity invalid-value test is structural, not behavioral.
This test currently passes by matching parser text, even if runtime rejection regresses. It should execute the script with an invalid value and assert failure.
🧪 Proposed fix
`@test` "--live-verbosity rejects invalid values" {
- local script="${BATS_TEST_DIRNAME}/../../ralph_loop.sh"
- # The parser checks for minimal|normal|verbose
- run grep -A3 '\-\-live-verbosity)' "$script"
- [[ "$output" == *"minimal"* ]]
- [[ "$output" == *"normal"* ]]
- [[ "$output" == *"verbose"* ]]
+ run bash "${BATS_TEST_DIRNAME}/../../ralph_loop.sh" --live-verbosity invalid
+ assert_failure
+ [[ "$output" == *"--live-verbosity must be"* ]]
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| @test "--live-verbosity rejects invalid values" { | |
| local script="${BATS_TEST_DIRNAME}/../../ralph_loop.sh" | |
| # The parser checks for minimal|normal|verbose | |
| run grep -A3 '\-\-live-verbosity)' "$script" | |
| [[ "$output" == *"minimal"* ]] | |
| [[ "$output" == *"normal"* ]] | |
| [[ "$output" == *"verbose"* ]] | |
| } | |
| `@test` "--live-verbosity rejects invalid values" { | |
| run bash "${BATS_TEST_DIRNAME}/../../ralph_loop.sh" --live-verbosity invalid | |
| assert_failure | |
| [[ "$output" == *"--live-verbosity must be"* ]] | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/unit/test_cli_modern.bats` around lines 1269 - 1276, The test
"--live-verbosity rejects invalid values" currently inspects the parser help
text instead of exercising runtime validation; change it to actually run the CLI
with an invalid verbosity value and assert failure: use the existing local
script variable (script="${BATS_TEST_DIRNAME}/../../ralph_loop.sh") and invoke
it via Bats' run with arguments including --live-verbosity invalid_value (e.g.
"super-verbose"), then assert a non-zero exit status (run exit code != 0) and
check that stderr or output contains an appropriate error message about invalid
verbosity (match "invalid" or the allowed choices minimal|normal|verbose) so the
test fails if runtime rejection regresses.
frankbria
requested changes
Mar 15, 2026
Owner
frankbria
left a comment
frankbria
left a comment
There was a problem hiding this comment.
Good feature — the verbosity-controlled jq filters, dashboard enhancement, and tmux fallback are all well-implemented with thorough tests (31 new).
Must fix before merge:
setup_fallback_monitor()callsmain()directly — this creates a double-invocation risk since the script's entry block at the bottom also callsmain(). Instead, the function should setLIVE_OUTPUT=trueand return, letting the existing entry logic callmain().
Should fix:
-
Help text still says
--monitor"(requires tmux)" but the behavior now falls back gracefully. Update the help text to reflect the new fallback behavior. -
The
--live-verbosity rejects invalid valuestest only greps the source file for validation patterns rather than exercising the CLI with an actual invalid value. Consider a runtime test.
Otherwise the code quality is high — clean separation of build_jq_filter(), proper env-var precedence, and synchronized template/documentation updates.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Enhances Ralph's live monitoring capabilities across three areas:
build_jq_filter()function with 3-level output filtering (minimal/normal/verbose), configurable viaRALPH_LIVE_VERBOSITYenv var,.ralphrc, or--live-verbosityCLI flagralph_monitor.shthat displays the last 5 lines from.ralph/live.logwith 72-char truncation--monitornow gracefully falls back to--livemode when tmux is not installed, instead of exiting with an errorVerbosity levels
minimalnormal(default)verboseChanged files
ralph_loop.shbuild_jq_filter(),setup_fallback_monitor(),check_tmux_available()refactor, CLI flag, env wiringralph_monitor.shlib/enable_core.shRALPH_LIVE_VERBOSITYingenerate_ralphrc()setup.shRALPH_LIVE_VERBOSITYin inline.ralphrctemplates/ralphrc.templateRALPH_LIVE_VERBOSITY="normal"defaulttests/helpers/fixtures.bashtests/unit/test_cli_modern.batsCLAUDE.mdTest plan
npm test)build_jq_filterproduces valid jq for all 3 levels + unknown fallbackrate_limit_eventrendering verified for normal/verbose, excluded from minimallive.logand handles missing file gracefullycheck_tmux_availableusesreturnnotexit--live-verbosityCLI flag validates input and rejects invalid values.ralphrcandsetup.shtemplates includeRALPH_LIVE_VERBOSITYralph --monitorandralph --live --live-verbosity verbose🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
--live-verbosityCLI option to control live output detail level (minimal, normal, verbose).RALPH_LIVE_VERBOSITYconfiguration variable for setting default verbosity preferences.Tests