项目文件夹

文件

T

Daniel Naves de Carvalho ea97ddd69e feat(terminal): honor CCSTATUSLINE_WIDTH env var to override probe (#380 )

* feat(terminal): honor CCSTATUSLINE_WIDTH env var to override probe

Provide an explicit width override so users can bypass the TTY probe
entirely when both ancestor-walk and `tput cols` fall through.

This is the fallback case the existing probe cannot solve on its own:
Claude Code >= 2.1.139 spawns statusline/hooks without terminal access,
and in some configurations (IDE integrations, nested shells, certain
agent-mode spawn paths) no ancestor process owns a TTY either. The
ancestor walk fails, `tput cols` returns 80, and the multi-line layout
truncates regardless of the actual iTerm2/terminal width.

PR #377 (`stty -F`/`stty -f`) covers the case where an ancestor does
hold a TTY but the legacy `< /dev/tty` form errors with ENOTTY. This
patch is complementary -- it handles the case where the ancestor walk
finds no TTY at all -- and gives users a knob today while upstream
work on passing `terminalWidth` via stdin JSON (#308) lands.

Change
------

`src/utils/terminal.ts` -- `probeTerminalWidth` now reads
`CCSTATUSLINE_WIDTH` before any platform check or probe. A valid
positive integer short-circuits with that value; anything else
(missing, empty, non-numeric, zero, negative) falls through to the
existing probe logic.

Usage
-----

Set the env var on the statusLine command in `~/.claude/settings.json`:

```json
"statusLine": {
  "type": "command",
  "command": "CCSTATUSLINE_WIDTH=200 ccstatusline"
}
```

Tests
-----

Four new cases in `src/utils/__tests__/terminal.test.ts`:

- override short-circuits probing entirely
- non-positive override (`0`) falls back to probing
- non-numeric override falls back to probing
- override applies on Windows where probing is otherwise disabled

`bunx vitest run src/utils/__tests__/terminal.test.ts` -> 12/12 pass.
Full-suite delta vs `main`: 4 new passing tests, zero new failures
(the pre-existing 105 env-specific failures in other suites are
unchanged on both branches).

`bun run lint` -> clean.

* docs: document terminal width override

---------

Co-authored-by: Matthew Breedlove <sirmalloc@gmail.com>

2026-05-17 03:01:58 -04:00

5.6 KiB

原始文件 永久链接 Blame 文件历史

Windows Support

ccstatusline works on Windows across PowerShell (5.1+ and 7+), Command Prompt, and Windows Subsystem for Linux (WSL).

If you want the main project overview, return to README.md.

Installation on Windows

Option 1: Using Bun (Recommended)

# Install Bun for Windows
irm bun.sh/install.ps1 | iex

# Run ccstatusline
bunx -y ccstatusline@latest

Option 2: Using Node.js

# Using npm
npx -y ccstatusline@latest

These commands launch the configuration TUI. To pin the install, start the TUI with bunx -y ccstatusline@latest or npx -y ccstatusline@latest, then choose Pinned global install. The TUI installs the active ccstatusline version globally with Bun or npm and configures Claude Code to run ccstatusline. After a pinned install, you can run ccstatusline directly to launch the TUI in the future.

Claude Code Integration

Configure ccstatusline in your Claude Code settings:

Settings location:

Default: %USERPROFILE%\.claude\settings.json
Custom: set CLAUDE_CONFIG_DIR to use a different directory

PowerShell custom config example:

$env:CLAUDE_CONFIG_DIR="C:\custom\path\.claude"

For Bun users:

{
  "statusLine": {
    "type": "command",
    "command": "bunx -y ccstatusline@latest",
    "padding": 0,
    "refreshInterval": 10
  }
}

For npm users:

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline@latest",
    "padding": 0,
    "refreshInterval": 10
  }
}

refreshInterval is optional and only supported by Claude Code >=2.1.97. You can configure it from ccstatusline's TUI after installation.

The bunx and npx examples above follow @latest. If you choose Pinned global install in the TUI, it writes "command": "ccstatusline" instead after installing the selected version globally. You can also run ccstatusline directly for future TUI launches.

Windows-Specific Features

Powerline Font Support

For optimal Powerline rendering on Windows:

Windows Terminal (Recommended):

Supports Powerline fonts natively
Download from Microsoft Store
Auto-detects compatible fonts

PowerShell/Command Prompt:

# Install JetBrains Mono Nerd Font via winget
winget install DEVCOM.JetBrainsMonoNerdFont

# Or download manually from: https://www.nerdfonts.com/font-downloads

# Alternative: Download and install base JetBrains Mono font
# from [JetBrains](https://www.jetbrains.com/lp/mono/)
# or [GitHub](https://github.com/JetBrains/JetBrainsMono)
# or [Google Fonts](https://fonts.google.com/specimen/JetBrains+Mono)

Path Handling

ccstatusline automatically handles Windows-specific paths:

Git repositories work with both / and \ path separators
Current Working Directory widget displays Windows-style paths correctly
Full support for mapped network drives and UNC paths
Handles Windows drive letters (C:, D:, etc.)

Windows Troubleshooting

Common Issues & Solutions

Issue: Status lines wrap because terminal width cannot be detected

# Set an explicit width before launching Claude Code
$env:CCSTATUSLINE_WIDTH="160"
claude

CCSTATUSLINE_WIDTH accepts a positive integer column width and is checked before automatic width detection. Set it in the same environment that starts Claude Code so the status line command inherits it. This is useful on Windows because native width probing is disabled when ccstatusline runs outside WSL.

Issue: Powerline symbols showing as question marks or boxes

# Solution: Install a compatible Nerd Font
winget install DEVCOM.JetBrainsMonoNerdFont
# Then set the font in your terminal settings

Issue: Git commands not recognized

# Check if Git is installed and in PATH
git --version

# If not found, install Git:
winget install Git.Git
# Or download from: https://git-scm.com/download/win

Issue: Permission errors during installation

# Use non-global installation (recommended)
npx -y ccstatusline@latest

# Or run PowerShell as Administrator for global install

Issue: "Execution Policy" errors in PowerShell

# Temporarily allow script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Issue: Windows Defender blocking execution

# If Windows Defender flags the binary:
# 1. Open Windows Security
# 2. Go to "Virus & threat protection"
# 3. Add exclusion for the ccstatusline binary location
# Or use temporary bypass (not recommended for production):
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.bun\bin"

Windows Subsystem for Linux (WSL)

ccstatusline works well in WSL environments:

# Install in WSL Ubuntu/Debian
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bunx -y ccstatusline@latest

WSL benefits:

Native Unix-style path handling
Better font rendering in WSL terminals
Seamless integration with Linux development workflows

Windows Terminal Configuration

For the best experience, configure Windows Terminal with these recommended settings:

Terminal Settings (`settings.json`)

{
  "profiles": {
    "defaults": {
      "font": {
        "face": "JetBrainsMono Nerd Font",
        "size": 12
      },
      "colorScheme": "One Half Dark"
    }
  }
}

Performance on Windows

ccstatusline includes Windows-specific runtime behavior:

UTF-8 piped output fix: In piped mode, it attempts to set code page 65001 for reliable symbol rendering
Path compatibility: Git and CWD widgets handle both / and \ separators

5.6 KiB 原始文件 永久链接 Blame 文件历史