Improve error messages when Claude Code CLI authentication fails

[sobuur0]

Problem

When Vide starts up, it tests the Claude Code CLI connection. If authentication has expired or there are other Claude-related issues, users see a generic error message that displays raw stderr output:

Claude test failed:
[raw error output]

This doesn't give users clear guidance on how to fix the issue. I had to dig into the code to understand that I needed to run claude login in a separate terminal.

Current Behavior

The verification step in the startup process catches errors but doesn't parse or interpret them for the user. Common scenarios like:

• Expired OAuth tokens
• Claude Code CLI not installed
• Claude Code not in PATH

All result in cryptic error messages.

Proposed Solution

Parse common error patterns from Claude Code CLI and provide actionable error messages. For example:

Authentication expired:

Claude authentication expired.

Please run: claude login
Then restart Vide.

CLI not found:

Claude Code CLI not found.

Please install it with:
npm install -g @anthropic-ai/claude-code

Implementation Notes

Before implementing this, we should:

1. Research how Claude Code CLI returns errors (exit codes, stderr formats)
2. Test various failure scenarios to document actual error outputs
3. Check if Claude Code has documented error codes/formats
4. Decide on the most reliable way to detect and handle each case

I'm happy to work on this if there's interest. Would love feedback on the approach before opening a PR.

Related

This complements the troubleshooting documentation I added in #59 .