Skip to content

feat: Auto-detect terminal width for HUD wrapping #1726

@seunggabi

Description

@seunggabi

Problem

When the terminal is resized to a narrow width, the HUD statusline gets truncated by Claude Code with ..., cutting off useful information.

Currently, maxWidth must be manually configured in ~/.claude/settings.json. Without it, no width-aware formatting happens and the truncation is handled by Claude Code at the terminal level — meaning the user loses all content beyond the cutoff point.

Expected Behavior

The HUD should automatically detect the terminal width and wrap its output to fit — without requiring any manual configuration.

Proposed Fix

In src/hud/index.ts, after readHudConfig(), auto-detect terminal width via a fallback chain:

// Auto-detect terminal width if maxWidth not explicitly configured
if (!config.maxWidth) {
    const cols = parseInt(process.env.COLUMNS ?? '0', 10)
        || process.stderr.columns
        || process.stdout.columns
        || 0;
    if (cols > 0) {
        config.maxWidth = cols;
        if (!config.wrapMode) config.wrapMode = 'wrap';
    }
}

Why this fallback chain?

  • process.env.COLUMNS — shell-exported terminal width (most common)
  • process.stderr.columns — stderr is often still a TTY even when stdout is piped
  • process.stdout.columns — available when stdout is a TTY

When auto-detected, wrapMode defaults to 'wrap' (instead of 'truncate') so content is preserved across multiple lines rather than being cut with ....

Impact

  • Zero config change needed for users
  • Existing maxWidth / wrapMode settings are fully respected (no behavior change)
  • HUD becomes responsive to terminal resizing

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions