claude-tmpdir-manager

Automatic TMPDIR management for Claude Code on external drive boot environments.

Prevents ENOSPC (No space left on device) errors by redirecting temp files to your boot volume.

한국어 참고: 외장 드라이브(SSD/HDD)에서 macOS를 부팅하여 Claude Code를 사용할 때 발생하는 /private/tmp 용량 부족 문제를 자동으로 해결하는 플러그인입니다.

---

The Problem

When you boot macOS from an external drive (common for portable dev setups), Claude Code writes task output to /private/tmp on the internal drive. If the internal drive has limited space, you hit:

ENOSPC: no space left on device, open '/private/tmp/claude-...'

Before (broken):

HOME=/Volumes/EXTERNAL_SSD/Users/you
TMPDIR=/private/tmp          # <-- on internal drive (tiny partition)
Claude Code writes → /private/tmp/claude-*  → ENOSPC!

After (fixed):

HOME=/Volumes/EXTERNAL_SSD/Users/you
TMPDIR=$HOME/tmp             # <-- on YOUR external drive (plenty of space)
Claude Code writes → ~/tmp/claude-*  → works!

Quick Start

1. Add marketplace

In Claude Code, run:

/plugin marketplace add beomwookang/claude-tmpdir-manager

2. Install plugin

/plugin install tmpdir-manager@tmpdir-manager

3. Run the setup script

bash ~/.claude/plugins/marketplaces/tmpdir-manager/scripts/install.sh

This configures TMPDIR in your shell profile and creates the tmp directory on your boot volume.

4. Restart Claude Code

Restart for the sandbox process to pick up the new TMPDIR. That's it!

Alternative: Manual git clone

git clone https://github.com/beomwookang/claude-tmpdir-manager.git \
  ~/.claude/plugins/marketplaces/tmpdir-manager
bash ~/.claude/plugins/marketplaces/tmpdir-manager/scripts/install.sh

Features

Feature	Description
Auto-detect	Detects external drive boot at session start
Space monitoring	Warns when /private/tmp or TMPDIR drops below 500MB
TMPDIR redirect	Points temp files to $HOME/tmp on your boot volume
Shell persistence	Adds export TMPDIR to ~/.zshrc so it survives reboots
Bash injection	Pre-Bash hook ensures child processes inherit correct TMPDIR
Manual fix	/fix-tmpdir command for on-demand repair

How It Works

Claude Code starts
      │
      ▼
┌─────────────────────────────┐
│  SessionStart Hook          │
│  hooks-handlers/session-    │
│  start.sh                   │
├─────────────────────────────┤
│  1. Detect if HOME is on    │
│     /Volumes/* (external)   │
│  2. Check TMPDIR volume     │
│     matches HOME volume     │
│  3. Check free space on     │
│     /private/tmp & TMPDIR   │
│  4. Warn if misconfigured   │
└────────────┬────────────────┘
             │
             ▼
      Session running...
             │
      User runs Bash command
             │
             ▼
┌─────────────────────────────┐
│  PreToolUse (Bash) Hook     │
│  hooks-handlers/pre-bash.sh │
├─────────────────────────────┤
│  1. If external drive:      │
│     ensure ~/tmp exists     │
│  2. Inject TMPDIR context   │
│     for child processes     │
└─────────────────────────────┘

Command Reference

/fix-tmpdir

Run this command inside Claude Code to manually configure TMPDIR. It will:

1. Detect your boot volume
2. Create ~/tmp on the boot volume
3. Add export TMPDIR="$HOME/tmp" to ~/.zshrc
4. Optionally clean stale files in /private/tmp
5. Verify the configuration

> /fix-tmpdir

You need to restart Claude Code after running this for the sandbox process to pick up the new TMPDIR.

Configuration

Custom tmp path

Pass a custom path during installation:

bash scripts/install.sh /Volumes/MY_DRIVE/custom-tmp

What the installer does

Step	Action
1	Detects external drive boot
2	Creates $HOME/tmp (or custom path)
3	Adds export TMPDIR to ~/.zshrc
4	Makes hook scripts executable
5	Enables plugin in ~/.claude/settings.json

Manual plugin enable

If the installer can't modify settings.json (e.g., jq not installed), add manually:

{
  "enabledPlugins": {
    "tmpdir-manager@tmpdir-manager": true
  }
}

Repo Structure

claude-tmpdir-manager/
├── .claude-plugin/
│   ├── marketplace.json     # Marketplace catalog
│   └── plugin.json          # Plugin metadata
├── commands/
│   └── fix-tmpdir.md        # /fix-tmpdir slash command
├── hooks/
│   └── hooks.json           # Hook registrations
├── hooks-handlers/
│   ├── session-start.sh     # Session health check
│   └── pre-bash.sh          # Bash env injection
├── scripts/
│   └── install.sh           # Setup script
├── README.md
├── LICENSE
└── .gitignore

Troubleshooting

Plugin not activating

Make sure the plugin is enabled in ~/.claude/settings.json:

"enabledPlugins": {
  "tmpdir-manager@tmpdir-manager": true
}

Still getting ENOSPC after install

The Claude Code sandbox process reads TMPDIR at launch time. You must restart Claude Code (not just the session) for changes to take effect.

Hooks not running

Ensure scripts are executable:

chmod +x ~/.claude/plugins/marketplaces/tmpdir-manager/hooks-handlers/*.sh

Not on an external drive?

This plugin is designed for external drive boot environments. On standard setups, the SessionStart hook will silently report TMPDIR status without making changes.

Requirements

• macOS (designed for external drive boot scenarios)
• Claude Code CLI
• zsh (default macOS shell)
• jq (optional, for automatic settings.json modification)

License

MIT - Use it however you like.