chenhg5/cc-connect · error

claudecode: read Claude Code /usage output: %w

Error message

claudecode: read Claude Code /usage output: %w

What it means

Raised by the /usage probe when reading the Claude Code process's merged output stream fails. It fires when the pty/pipe backing the probe breaks — usually because the underlying process died or the descriptor was closed unexpectedly.

Source

Thrown at agent/claudecode/claude_usage.go:163

		state       claudeUsageProbeState
		lastScreen  string
		lastChange  = time.Now()
		usageScreen string
	)

	for {
		select {
		case <-probeCtx.Done():
			if usageScreen != "" {
				return usageScreen, nil
			}
			if screenErr := detectClaudeUsageOutputError(lastScreen, stderr.String()); screenErr != nil {
				return "", screenErr
			}
			return "", fmt.Errorf("claudecode: timed out waiting for Claude Code /usage panel: %w", probeCtx.Err())
		case err := <-readDone:
			if err != nil {
				return "", fmt.Errorf("claudecode: read Claude Code /usage output: %w", err)
			}
		case <-processDone:
			if usageScreen != "" {
				return usageScreen, nil
			}
			if screenErr := detectClaudeUsageOutputError(lastScreen, stderr.String()); screenErr != nil {
				return "", screenErr
			}
			if waitErr != nil {
				return "", fmt.Errorf("claudecode: Claude Code exited before /usage rendered: %w", waitErr)
			}
			return "", fmt.Errorf("claudecode: Claude Code exited before /usage rendered")
		case <-ticker.C:
			screen := normalizeClaudeUsageText(terminal.String())
			if screen != lastScreen {
				lastScreen = screen
				lastChange = time.Now()
			}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Retry /usage after confirming the claude binary runs normally
2. Check for claude processes crashing on startup (auth, network)
3. Look at accompanying stderr in logs for the process's own error

When it happens

Trigger: Thrown at agent/claudecode/claude_usage.go:163 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/6cf7e7ca2b265080. Report an issue: GitHub.