[BUG] Claude Code (v2.0.25) fails to load custom agents when `TMPDIR` environment variable points to a non-existent directory

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: Claude Code Silent Agent Loading Failure with Invalid TMPDIR

Summary

Claude Code (v2.0.25) fails to load custom agents when TMPDIR environment variable points to a non-existent directory. The failure is completely silent with no error messages or warnings, even in debug mode.

Note: I believe this affected custom /slash-commands, too.

Environment

• Claude Code Version: 2.0.25
• OS: Linux (WSL2) - Ubuntu on Windows
• Kernel: 6.6.87.2-microsoft-standard-WSL2
• Shell: bash
• Affected Users: Multiple users (Kinjal, Vijay confirmed; Dwayne unaffected)

Bug Description

Symptoms

1. User creates custom agents using /agents command or by placing .md files in .claude/agents/
2. Agents work perfectly during the current session
3. After restarting Claude Code, agents disappear completely from available agents list
4. Agent .md files remain on disk but are not loaded
5. No error messages appear in the UI
6. Debug logs show no indication of the problem

Root Cause

When TMPDIR environment variable points to a non-existent directory (in our case /var/tmp-shared), Claude Code silently fails during agent initialization. The debug log only shows:

[DEBUG] Total plugin agents loaded: 0

But provides no indication that TMPDIR is invalid or that agent loading failed due to filesystem issues.

Actual Behavior

1. ❌ No validation of TMPDIR
2. ❌ Silent failure - no errors logged
3. ❌ No user-facing messages
4. ❌ No fallback behavior
5. ❌ Debug logs only show "Total plugin agents loaded: 0" with no explanation

Debug Log Evidence

From /home/kinjal/.claude/debug/*.txt:

[DEBUG] Found 0 plugins (0 enabled, 0 disabled)
[DEBUG] Loading skills from directories: managed=/etc/claude-code/.claude/skills, user=/home/kinjal/.claude/skills, project=/mnt/data/kinjal/pd/pd-ui/.claude/skills
[DEBUG] Total plugin skills loaded: 0
[DEBUG] Total plugin commands loaded: 0
[DEBUG] Loaded 0 skills total (managed: 0, user: 0, project: 0)
[DEBUG] Ripgrep first use test: FAILED (mode=builtin, path=/home/kinjal/.local/share/claude/versions/2.0.25)
[DEBUG] Total plugin agents loaded: 0

Notable: No mention of scanning .claude/agents/ directory or any filesystem errors related to TMPDIR.

Additional Context

How TMPDIR Got Set

The invalid TMPDIR was added by a script:

# From ~/.bashrc line 127-129
# Temporary workaround for /tmp on Windows filesystem
# Added by setup-shared-tmpdir-simple.sh on Tue Aug 12 17:40:44 CDT 2025
export TMPDIR=/var/tmp-shared

This was intended as a WSL workaround but the directory was never created.

Workaround

Comment out or remove the TMPDIR export from .bashrc:

# export TMPDIR=/var/tmp-shared

Don't forget, to use unset TMPDIR and then retry, not just a 'source ~/.bashrc'

Then restart with a fresh terminal session.

Impact

• Severity: Medium to High
• User Impact: Complete loss of custom agent functionality
• Debugging Difficulty: Extremely high - no indication of the problem
• Affected Users: Any user with invalid TMPDIR (common in WSL environments)

Suggested Fixes

Priority 1 (Critical)

1. Add TMPDIR validation on startup:

``typescript
if (process.env.TMPDIR && !fs.existsSync(process.env.TMPDIR)) {
console.error(TMPDIR=${process.env.TMPDIR} does not exist, falling back to /tmp);
process.env.TMPDIR = '/tmp';
}
``

1. Improve debug logging:

``
[DEBUG] Checking TMPDIR: /var/tmp-shared
[ERROR] TMPDIR directory does not exist!
[DEBUG] Scanning for agents in: /home/user/.claude/agents/
[DEBUG] Found agent files: word-count-analyzer.md
[ERROR] Failed to load agent: Cannot create temp file in /var/tmp-shared
``

Priority 2 (Important)

1. Add user-facing error notification: Show a dismissible banner in the UI when agents fail to load

1. Add health check command: /healthcheck command to validate environment (TMPDIR, permissions, etc.)

Priority 3 (Nice to Have)

1. Documentation: Add troubleshooting section for agent loading failures
2. Startup diagnostics: Run environment validation and display results in debug log

Related Issues

• Agents are stored in ~/.claude/agents/ (global) OR project/.claude/agents/ (project-specific)
• The /agents command creates global agents
• No clear documentation on agent discovery mechanism
• [DEBUG] Total plugin agents loaded: 0 suggests agents are only loaded from plugins, not from .claude/agents/ directories

Files for Reference

• Debug logs: ~/.claude/debug/*.txt
• Agent files: ~/.claude/agents/*.md and project/.claude/agents/*.md
• Settings: ~/.claude/settings.json and project/.claude/settings.local.json

---

Submitted by: Dwayne
Date: 2025-10-23
Session Length: ~2 hours of debugging

What Should Happen?

Expected Behavior

Claude Code should:

1. Validate TMPDIR on startup and warn if it doesn't exist
2. Log clear errors when agent loading fails, especially in debug mode
3. Provide user-facing error messages explaining why agents failed to load
4. Fall back to /tmp if TMPDIR is invalid
5. Debug logs should explicitly state:

``
[ERROR] Cannot load agents: TMPDIR=/var/tmp-shared does not exist
[WARN] Falling back to /tmp for temporary directory
``

Error Messages/Logs

Steps to Reproduce

Reproduction Steps

1. Set invalid TMPDIR in user's .bashrc:

``bash
export TMPDIR=/var/tmp-shared # Directory doesn't exist
``

1. Start a fresh terminal and launch Claude Code:

``bash
claude -c
``

1. Create a custom agent:

``bash
/agents
# Follow prompts to create an agent
``

1. Test the agent - it will work in current session

1. Restart Claude Code:

``bash
# Exit and restart
claude -c
``

1. Try to use the agent:

``
Available agents: general-purpose, statusline-setup, output-style-setup, Explore
# Custom agent is missing!
``

Claude Model

Not sure / Multiple models

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.25

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Windows Terminal

Additional Information

To clarify, this is Ubuntu 22 via WSL.