How to Install and Configure Claude HUD in Claude Code

Mar 21, 2026

I wanted to monitor my context usage while working with Claude Code, so I decided to install Claude HUD. The installation should be straightforward, but there are a few gotchas that tripped me up.

The Problem

I was running long coding sessions and losing track of how much context I had used. I’d hit context limits unexpectedly, forcing me to start fresh conversations. I needed a way to see my context consumption in real-time.

Claude HUD is a plugin that displays context usage, session activity, and other useful information directly in your Claude Code interface. But getting it installed correctly required more than just a simple install command.

Installation Steps

The installation has three parts: adding the marketplace, installing the plugin, and running setup.

Step 1: Add the Marketplace

First, I added the plugin marketplace source:

/plugin marketplace add jarrodwatts/claude-hud

This tells Claude Code where to find the plugin.

Step 2: Install the Plugin

Then I installed the plugin itself:

/plugin install claude-hud

At this point, I thought I was done. But the HUD didn’t appear. The missing piece was the statusline configuration.

Step 3: Run Setup

This is the step I initially skipped. The setup command configures your statusline to display the HUD:

/claude-hud:setup

The setup process does a few things:

Detects your platform and shell
Applies configuration to ~/.claude/settings.json
Verifies everything is working

Step 4: Restart Claude Code

After setup, I needed to fully quit and restart Claude Code. The new statusline configuration only loads on startup.

I quit completely (not just close the terminal tab) and ran claude again. The HUD appeared below my input field.

Linux-Specific Issue

On Linux, I encountered an error during installation:

EXDEV: cross-device link not permitted

This happens because Linux often uses /tmp as a separate tmpfs filesystem. The plugin installation tries to move files across filesystems, which fails.

The fix was to set TMPDIR to a directory on the same filesystem:

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

This creates a temporary directory in my home folder and tells Claude to use it instead of /tmp.

Post-Installation Configuration

After getting the HUD running, I wanted to customize what it shows. The configuration command lets you adjust the display:

/claude-hud:configure

Configuration options include:

Layout: Choose between Expanded (more details) or Compact (minimal space)

Presets:

Full: All features enabled
Essential: Core features only
Minimal: Just the basics

Individual Features: Toggle tools, agents, todos, and git status independently

I started with the Full preset to see everything, then switched to Essential after a few days when I realized I didn’t need every metric.

What I Learned

The key insight was that installation alone isn’t enough. Running /claude-hud:setup is required to configure the statusline. Without it, the plugin installs but does nothing visible.

The Linux TMPDIR workaround is also important if you’re on that platform. The error message doesn’t explain the root cause, so knowing this fix saved me debugging time.

Now I can see my context usage at a glance. I know when I’m approaching limits and can plan my prompts accordingly. The HUD has become an essential part of my Claude Code workflow.

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:

👨‍💻 Claude HUD GitHub

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