Add verbose diagnostics to doctor command with stderr/stdout capture by subsy · Pull Request #254 · subsy/ralph-tui

subsy · 2026-02-02T21:17:00Z

Summary

Enhanced the doctor command with a new --verbose flag that displays captured stderr/stdout output from preflight checks, making it easier to diagnose agent configuration issues.

Key Changes

Added --verbose / -v flag to the doctor command for detailed diagnostic output
- Shows captured stderr and stdout from failed preflight checks
- Limits output to 20 lines per stream with indication of truncation
- Only displays when preflight check fails
Extended AgentPreflightResult type to include diagnostic data:
- exitCode: Exit code from preflight execution
- stderr: Captured stderr output
- stdout: Captured stdout output
Enhanced preflight check execution in BaseAgentPlugin:
- Now captures both stdout and stderr separately
- Includes exit code in error responses
- Builds detailed error messages combining base error with exit code and stderr snippet
- Returns captured output in all failure scenarios
Improved error reporting in human-readable output:
- Displays exit code when available
- Shows verbose diagnostics section for failed checks when --verbose flag is used
- Adds helpful tip suggesting --verbose flag when doctor fails (unless already in verbose mode)
Updated help documentation with new --verbose option and example usage

Implementation Details

The verbose output is only shown when:

The --verbose flag is explicitly passed
The preflight check has failed

Stderr/stdout output is truncated to 20 lines each to prevent overwhelming output, with a count of remaining lines displayed if truncation occurs. This balances diagnostic usefulness with readability.

https://claude.ai/code/session_01Wfm5Lc1tQX45EVeKsdEf8w

Summary by CodeRabbit

New Features
- Added --verbose (or -v) flag to the doctor command to show expanded diagnostics (captured stdout/stderr shown when enabled).
Improvements
- Preflight failures now display exit codes and captured diagnostic output (stdout/stderr, truncated to a readable length).
- Help/usage updated to include verbose examples.
- Non-verbose failures include a tip to rerun with --verbose for more details.

- Add stderr and exit code capture to preflight checks - Add --verbose flag to show detailed stdout/stderr on failure - Include exit code in error messages when non-zero - Show tip about --verbose when doctor fails - Extend AgentPreflightResult type with exitCode, stderr, stdout fields This helps diagnose Windows/Bun installation issues where the agent fails silently without useful error output. Refs: #238 https://claude.ai/code/session_01Wfm5Lc1tQX45EVeKsdEf8w

vercel · 2026-02-02T21:17:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ralph-tui	Ready	Preview, Comment	Feb 3, 2026 0:46am

coderabbitai · 2026-02-02T21:17:17Z

Walkthrough

The PR adds a verbose mode to the doctor command and extends agent preflight results to include stdout, stderr and exit codes, propagating those diagnostics through preflight execution and human-readable output.

Changes

Cohort / File(s)	Summary
Doctor CLI & output `src/commands/doctor.ts`	Added `--verbose` / `-v` flag, updated usage/examples and help text. `printHumanResult` now accepts `verbose` and prints captured `stderr`/`stdout` (up to 20 lines) and exit code when verbose; non-verbose failures now suggest `--verbose`.
Agent preflight implementation `src/plugins/agents/base.ts`	Preflight runner now captures both `stdout` and `stderr`, uses `stdout` to detect successful preflight, and populates result with `stdout` on success. Failure paths build richer error details (including truncated stderr excerpt) and attach `stdout`, `stderr` and `exitCode`.
Agent types `src/plugins/agents/types.ts`	`AgentPreflightResult` extended with optional `stdout?: string`, `stderr?: string`, and `exitCode?: number`.

Sequence Diagram(s)

sequenceDiagram
    rect rgba(30,144,255,0.5)
    participant User
    end
    rect rgba(34,139,34,0.5)
    participant CLI as Doctor CLI
    end
    rect rgba(255,165,0,0.5)
    participant Agent as BaseAgentPlugin
    end
    rect rgba(128,0,128,0.5)
    participant Proc as External Runner
    end

    User->>CLI: run `doctor --verbose`
    CLI->>Agent: call preflight()
    Agent->>Proc: execute minimal test prompt
    Proc-->>Agent: return stdout, stderr, exitCode
    Agent-->>CLI: AgentPreflightResult { success|failure, stdout, stderr, exitCode }
    CLI->>CLI: call printHumanResult(result, verbose=true)
    CLI-->>User: print human-readable diagnostics (includes truncated stdout/stderr and exit code)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

feat(agents): add preflight system and doctor command #130 – Related change that also modifies agent preflight result shape and surfaces stdout/stderr/exitCode in doctor output.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarises the main changes: adding verbose diagnostics to the doctor command with stderr/stdout capture, which is the core focus of this pull request.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch claude/investigate-issue-238-uLRKw

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-02-03T11:28:54Z

Codecov Report

❌ Patch coverage is 48.61111% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.49%. Comparing base (83bc7c5) to head (8b8b32c).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/commands/doctor.ts	18.42%	31 Missing ⚠️
src/plugins/agents/base.ts	82.35%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #254      +/-   ##
==========================================
- Coverage   45.51%   45.49%   -0.02%     
==========================================
  Files          91       91              
  Lines       27378    27442      +64     
==========================================
+ Hits        12460    12486      +26     
- Misses      14918    14956      +38

Files with missing lines	Coverage Δ
src/plugins/agents/base.ts	`64.74% <82.35%> (+0.52%)`	⬆️
src/commands/doctor.ts	`67.72% <18.42%> (-11.08%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…uLRKw Add verbose diagnostics to doctor command with stderr/stdout capture

Merge branch 'main' into claude/investigate-issue-238-uLRKw

b79c0ef

Merge branch 'main' into claude/investigate-issue-238-uLRKw

8b8b32c

vercel bot deployed to Preview February 3, 2026 12:46 View deployment

subsy merged commit 7268090 into main Feb 3, 2026
9 checks passed

subsy deleted the claude/investigate-issue-238-uLRKw branch February 3, 2026 12:50

sakaman pushed a commit to sakaman/ralph-tui that referenced this pull request Feb 15, 2026

Merge pull request subsy#254 from subsy/claude/investigate-issue-238-…

8a7f988

…uLRKw Add verbose diagnostics to doctor command with stderr/stdout capture

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add verbose diagnostics to doctor command with stderr/stdout capture#254

Add verbose diagnostics to doctor command with stderr/stdout capture#254
subsy merged 3 commits intomainfrom
claude/investigate-issue-238-uLRKw

subsy commented Feb 2, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Feb 2, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Feb 2, 2026 •

edited

Loading

Uh oh!

codecov bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

subsy commented Feb 2, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Implementation Details

Summary by CodeRabbit

Uh oh!

vercel bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Uh oh!

codecov bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

subsy commented Feb 2, 2026 •

edited by coderabbitai bot

Loading

vercel bot commented Feb 2, 2026 •

edited

Loading

coderabbitai bot commented Feb 2, 2026 •

edited

Loading

codecov bot commented Feb 3, 2026 •

edited

Loading