Debugging Claude Code Issues: Undocumented Environment Variables Uncovered#

Published on October 22, 2025

Claude Code versions 2.0.22 through 2.0.25 had some nasty bugs (#9936, #10104, and many more). Instead of waiting for a fix, I dug into the source code to see what debugging tools were available.

Turns out there are several powerful environment variables that aren't documented anywhere. I've added them to my improved settings schema.

The Most Useful Debugging Variables#

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE - Control when Claude compacts conversation history. Default is aggressive; set higher to preserve more context:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "0.8"
  }
}

DEBUG - Enable verbose debug logging to see what's happening under the hood:

{
  "env": {
    "DEBUG": "1"
  }
}

CLAUDE_CODE_DEBUG_LOGS_DIR - Send debug logs to a custom directory instead of default location:

{
  "env": {
    "CLAUDE_CODE_DEBUG_LOGS_DIR": "/path/to/custom/logs"
  }
}

The Nuclear Debugging Alias#

When Claude Code starts misbehaving, I use this alias to fire it up with full diagnostics:

alias dclaude="export DEBUG_SDK=1 MCP_TIMEOUT=60000 CLAUDE_CODE_DEBUG_LOGS_DIR=~/claude-debug && claude"

Run dclaude instead of claude and you get:

• SDK debug output (DEBUG_SDK=1)
• Longer MCP timeout to prevent premature disconnects (MCP_TIMEOUT=60000)
• All debug logs centralized in ~/claude-debug

This has saved me hours when tracking down issues with MCP servers, permission problems, or unexpected behavior.

Bypassing Permission Prompts on VPS (Use with Caution)#

IS_SANDBOX - If you're running Claude Code on a VPS or development server where you need to use --dangerously-skip-permissions with root/sudo privileges, this variable bypasses the security check:

IS_SANDBOX=1 claude --dangerously-skip-permissions

Or add it to your settings:

{
  "env": {
    "IS_SANDBOX": "1"
  }
}

Warning: This disables an important safety feature. Only use in trusted development environments where you understand the security implications.

This trick was discovered through source code investigation by users trying to run Claude Code on VPS instances.

Updating the Schema#

All these variables are now included in the improved Claude Code settings schema. Just add this to your .claude/settings.json:

{
  "$schema": "https://assets.turboai.dev/claude-code-settings.improved.json"
}

Type "CLAUDE_ and autocomplete shows all the debugging options with inline docs.

What I Learned#

The source code reveals Claude Code is far more configurable than the official docs suggest. Environment variables control everything from timeout behavior to memory management to debug verbosity.

If you're hitting weird issues, don't just file a bug report and wait. Grab the debug alias, turn on verbose logging, and see what's actually happening. You might find a workaround or at least get useful info to include in your bug report.