Troubleshooting

Start with /doctor — it checks runtime version, provider credentials, config integrity, plugin/MCP status, and Sentry telemetry.

Startup Issues

"No provider configured" or model doesn't respond

Check: Provider API key and model selection.

/status                          # Shows active provider and model
echo $ANTHROPIC_API_KEY          # Verify key is set
claude --model sonnet          # Specify model at startup

Build fails

node --version                   # Must be 22.12.0+
bun --version                    # Must be 1.3+
bun x tsc --noEmit               # Type check
bun run build                    # Full build

Check for strict TypeScript violations. Some native modules are externalized (--external flags in build script).

Windows: "Not a TTY" errors

The application polyfills TTY for Ink compatibility in src/main.tsx. If you see TTY-related issues:

Runtime Issues

Tool prompts appearing too often

/permissions                     # View current mode and rules
/permissions set auto            # Auto-approve low-risk actions
# Or use CLI flags:
claude --allowedTools "Bash(git *) Edit Read"

MCP tools not showing or server won't start

/mcp                             # List configured MCP servers
claude --mcp-config ./mcp-config.json  # Load from file

Verify the server's configuration JSON. Check src/services/mcp/client.ts for protocol version requirements.

Plugins not appearing after install

/plugin                          # List installed plugins
/reload-plugins                  # Refresh without restart
claude --plugin-dir /path/to/plugins  # Load from custom dir

Context window full

/context                         # Show usage
/compact                         # Compress (log snipping, consolidation)
/clear                           # Start fresh

Dependency issues

rm -rf node_modules bun.lock
bun install

# Windows PowerShell
Remove-Item -Recurse -Force node_modules
Remove-Item bun.lock
bun install

Debug Mode

claude --debug                          # General debug
claude --debug api,hooks                # Category-filtered
claude --debug-file /tmp/debug.log      # Log to file
DEBUG=provider:anthropic claude         # Provider-specific

Print Mode (Non-Interactive)

If the TUI doesn't work in your environment, use --print for pipe-friendly output:

claude -p "explain this file" > output.txt
claude -p --output-format json "list dependencies" | jq
echo "refactor this" | claude -p

Getting Help