📋 Pre-flight Checks
📄 Which Document?
docs/AGENT-SETUP.md
🔍 What's Wrong or Missing?
Following the recent update that fixed the marketplace.json schema, Linux users can finally proceed with the Claude Code plugin installation. However, users on distributions where /home and /tmp are mounted on different filesystems (which is the default partitioning on Fedora, openSUSE, Arch Linux, and many Ubuntu Server setups) will immediately hit a hard crash:
EXDEV: cross-device link not permitted, rename '/home/user/.claude/plugins/cache/engram' -> '/tmp/claude-plugin-temp-...'
This happens because Claude Code's plugin installer (running on Node.js) attempts to use fs.rename() to move the downloaded plugin across partition boundaries, which Node.js natively rejects. This completely blocks the installation for these users. There is currently no mention of this upstream limitation or its workaround in our documentation.
💡 Suggested Improvement
Troubleshooting: Claude Code plugin installation on Linux
EXDEV: cross-device link not permitted during plugin install
On Linux systems where /home and /tmp are on different partitions or filesystems, Claude Code's plugin installer fails because Node.js fs.rename() cannot move files across filesystem boundaries.
Workaround — redirect the temp directory to the same filesystem as ~/.claude:
mkdir -p ~/.cache/claude-tmp
TMPDIR=~/.cache/claude-tmp claude plugin marketplace add Gentleman-Programming/engram
TMPDIR=~/.cache/claude-tmp claude plugin install engram
Or make it permanent in your shell profile (~/.bashrc, ~/.zshrc):
export TMPDIR="$HOME/.cache/claude-tmp"
This is a known Claude Code issue ([#14799](anthropics/claude-code#14799)) affecting all plugin installations on Linux with separate /tmp, not specific to Engram.
Docker users: This does not affect Docker containers since the entire filesystem is typically a single overlay mount.
📎 Additional Context
This is a documented limitation in the Claude Code CLI itself, independent of Engram, but Engram users will be the ones experiencing it directly now that the marketplace schema is unblocked.
- Upstream Anthropic issue: https://github.com/anthropics/claude-code/issues/14799
- I have personally verified the issue and tested the `TMPDIR` workaround successfully on Fedora Linux natively.
- Once this issue receives the `status:approved` label, I have the PR ready to submit.
📋 Pre-flight Checks
📄 Which Document?
docs/AGENT-SETUP.md
🔍 What's Wrong or Missing?
Following the recent update that fixed the
marketplace.jsonschema, Linux users can finally proceed with the Claude Code plugin installation. However, users on distributions where/homeand/tmpare mounted on different filesystems (which is the default partitioning on Fedora, openSUSE, Arch Linux, and many Ubuntu Server setups) will immediately hit a hard crash:EXDEV: cross-device link not permitted, rename '/home/user/.claude/plugins/cache/engram' -> '/tmp/claude-plugin-temp-...'This happens because Claude Code's plugin installer (running on Node.js) attempts to use
fs.rename()to move the downloaded plugin across partition boundaries, which Node.js natively rejects. This completely blocks the installation for these users. There is currently no mention of this upstream limitation or its workaround in our documentation.💡 Suggested Improvement
Troubleshooting: Claude Code plugin installation on Linux
EXDEV: cross-device link not permittedduring plugin installOn Linux systems where
/homeand/tmpare on different partitions or filesystems, Claude Code's plugin installer fails because Node.jsfs.rename()cannot move files across filesystem boundaries.Workaround — redirect the temp directory to the same filesystem as
~/.claude:Or make it permanent in your shell profile (
~/.bashrc,~/.zshrc):This is a known Claude Code issue ([#14799](anthropics/claude-code#14799)) affecting all plugin installations on Linux with separate
/tmp, not specific to Engram.📎 Additional Context