Skip to content
BSWEN
Blog

Fix Claude HUD Plugin Installation on Linux: EXDEV Cross-Device Error

Cowrie
Cowrie
Dev @ Bswen

I tried installing the Claude HUD plugin on my Linux machine and got this cryptic error:

error
EXDEV: cross-device link not permitted

The installation just failed silently. No helpful message, no suggestion on what to do next. Let me show you what causes this and how to fix it.

What’s Happening

On many Linux distributions, /tmp is mounted as a tmpfs — a RAM-backed filesystem that’s separate from your home directory’s filesystem. When Claude Code’s plugin system tries to move files from /tmp to ~/.claude/plugins/, the underlying rename() syscall fails because you can’t atomically move files across different filesystems.

Let me check if this is the issue on my system:

terminal
[ "$(df --output=source ~ /tmp 2>/dev/null | tail -2 | uniq | wc -l)" = "2" ] && echo "CROSS_DEVICE"
output
CROSS_DEVICE

Yep — my /tmp and home directory are on different filesystems. That’s the problem.

The Fix

Set TMPDIR to a directory on the same filesystem as your home directory before running Claude Code.

Step 1: Create a temp directory on your home filesystem

terminal
mkdir -p ~/.cache/tmp

Step 2: Run Claude Code with TMPDIR set

terminal
TMPDIR=~/.cache/tmp claude

Step 3: Install the plugin in that session

claude-code
/plugin install claude-hud

Step 4: Run the setup

claude-code
/claude-hud:setup

The installation should now complete without the EXDEV error.

Why This Works

By setting TMPDIR to ~/.cache/tmp (which lives on your home filesystem), the plugin installation’s temporary files and their final destination (~/.claude/plugins/) are now on the same filesystem. This allows the atomic rename() operation to succeed.

The key insight is that rename() can only work within a single filesystem — it can’t move files across filesystem boundaries. When /tmp is a tmpfs and your home is on a different partition or drive, they’re separate filesystems.

Making It Permanent

If you want this fix to persist across sessions, add it to your shell profile:

For Bash users (~/.bashrc):

~/.bashrc
export TMPDIR="$HOME/.cache/tmp"
mkdir -p "$TMPDIR"

For Zsh users (~/.zshrc):

~/.zshrc
export TMPDIR="$HOME/.cache/tmp"
mkdir -p "$TMPDIR"

Then reload your shell or source the file:

terminal
source ~/.bashrc  # or source ~/.zshrc

This Is a Claude Code Platform Limitation

This isn’t a bug in Claude HUD specifically. It’s a known issue in Claude Code’s plugin system, tracked as GitHub issue #14799. The plugin system doesn’t handle cross-filesystem moves gracefully on Linux.

Summary

If you see EXDEV: cross-device link not permitted when installing Claude HUD (or any Claude Code plugin) on Linux:

  1. Check if /tmp and your home are on different filesystems
  2. Create ~/.cache/tmp (or any directory on your home filesystem)
  3. Set TMPDIR to that directory when running Claude Code
  4. The plugin installation will now work

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: