All postsgeneral

Claude Code Multi-Profile HUD Setup

Running Claude Code with multiple accounts requires careful HUD configuration to show correct per-account usage stats. Here's how to fix cross-profile data leaks.

On this page 12
  1. Why It Matters
  2. Difficulties Encountered
  3. The Solution
  4. Profile Architecture
  5. What I Run Now
  6. Cache Lock Mechanism
  7. Midnight Aurora Theme
  8. HUD Configuration
  9. Token Management
  10. Common Pitfalls
  11. Why This Works
  12. Practical Tips

My work profile’s HUD was showing personal account usage stats. The failure was silent: no errors, just the other account’s numbers. Finding the cause took extensive debugging of the statusline wrapper.

If you run Claude Code with separate personal and work accounts, the HUD plugin needs explicit configuration to show the right stats for each profile.

Update (2026-10-29). Much of the patching below comes from the claude-hud v0.0.x era, when I pinned one plugin version and patched its source heavily. I retired that version pin in September 2026: the pinned cache directory was deleted out from under me twice, and each time the HUD degraded silently. These days nearly all of my customization lives in the plugin’s config.json, five small source patches remain, and current claude-hud reads usage from the rate_limits data Claude Code sends on stdin. I also run a single profile now. The CLAUDE_CONFIG_DIR passthrough lesson still holds for anyone running more than one. See What I Run Now.

Why It Matters

Claude Code supports multiple profiles through the CLAUDE_CONFIG_DIR environment variable. You can have a personal ~/.claude and a work ~/.claude-work, each with its own OAuth tokens, settings, and plugins.

The problem is that Claude Code does not pass CLAUDE_CONFIG_DIR to statusline subprocesses. The HUD plugin runs as a subprocess, so it always falls back to the default path (~/.claude). The work profile ends up showing personal account usage. The personal profile works fine since it’s the default.

This isn’t a bug in the obvious sense — the HUD still shows data. It just shows the wrong data. That makes it harder to catch than a crash.

Difficulties Encountered

These all come from the patched v0.0.x setup. Several of them — the keychain reads, the usage cache, the lock, usage-api.ts — no longer apply to current claude-hud, which gets usage from Claude Code’s stdin instead of calling the usage API itself.

The environment variable didn’t propagate. I assumed CLAUDE_CONFIG_DIR would pass through to the statusline wrapper script, but Claude Code strips it. I only discovered this after extensive debugging of the wrapper receiving the wrong config path.

Keychain entries looked identical at first glance. Both profiles create keychain entries under similar service names. The suffix hash that differentiates them isn’t obvious, so it was easy to confuse which entry belonged to which profile.

Duplicate keychain entries caused unpredictable reads. macOS security find-generic-password returns the first match. With duplicates, it silently returns wrong credentials — no error, just the wrong data.

HUD binaries are independent per profile. I initially assumed symlinks would work, but each profile’s plugin binary must be patched independently. Symlinking makes both profiles share the same binary, defeating the purpose.

Token sync was a red herring. I tried syncing tokens between keychain entries, which overwrote valid tokens with stale ones. Claude manages tokens natively per profile — manual intervention makes things worse.

Both tokens can expire silently. The profile-specific keychain entry only updates on clean session exit (via the _claude_sync_token hook). If sessions are closed uncleanly — terminal kill, crash — the profile entry goes stale while the default entry stays fresh. When the default also expires, both fallback paths fail simultaneously and usage shows nothing. No error, just null data.

The failure cache masks the real cause. usage-api.ts caches API failures for 15 seconds (CACHE_FAILURE_TTL_MS). Reading the cache file shows apiUnavailable: true, which looks like an API outage. The real cause is expired credentials that prevented the API call entirely. This misdirection cost significant debugging time.

Source TypeScript is behind compiled dist JavaScript. The HUD plugin has two code paths — src/ (TypeScript, run by bun) and dist/ (compiled JS). Plugin updates install new dist but don’t update source. Features like quotaBar, showSpeed, contextValue, usageBarEnabled, and sevenDayThreshold only existed in dist while source still had hardcoded values and missing functions. Patching must target src/ files since the wrapper runs bun src/index.ts.

Piped subprocesses have no terminal width. I attempted auto-wrap at | boundaries, but process.stderr.columns, process.stdout.columns, and $COLUMNS all return undefined or 0 in the piped statusline subprocess. Claude Code’s statusline renderer controls final line truncation — the HUD cannot detect or work around this.

429 race condition from missing lock mechanism. This was the nastiest bug. With 3+ concurrent CLI sessions sharing one cache file per profile, all sessions expired the 60-second cache simultaneously and fired parallel API requests. The Anthropic usage API (rate-limited) returned 429 to all of them. Once rate-limited, the 3-minute failure cache kicked in — but it created a retry loop: cached failure expired, all sessions retried, 429 again, never recovered. My emergency fix was raising the failure TTL to 5 minutes, but the real solution came from the upstream repo: a file-based lock using O_EXCL atomic create so only one process fetches while others wait for fresh cache.

sed r with address range inserts on every line. Using sed "/start/,/end/r file" inserts the file after every line in the range, not just the last. For precise insertions after a function body, use awk insert-before on a unique anchor line below the target instead.

getOutputSpeed return type mismatch. The speed-tracker returns number | null directly, but I wrote code assuming it returns { speed, outputTokens }. This caused intermittent undefined is not an object TypeErrors — triggered only when speed was non-null, which is rare due to the 2-second measurement window.

Stale marketplace paths after profile rename. ~/.claude/plugins/known_marketplaces.json stores absolute paths to marketplace clones. After renaming ~/.claude-personal/ to ~/.claude/, the old paths persisted and claude plugin install failed with “Source path does not exist” — no obvious error pointing to the marketplace file.

Statusline height is fixed by Claude Code. The HUD plugin outputs lines via console.log() but Claude Code controls the vertical area allocated to the statusline. The plugin has no API to request more space. Line ordering in render output directly controls degradation: first lines survive, last lines clip.

Stale usage cache after plugin upgrade. During a plugin upgrade, there’s a window where the old (unpatched) HUD binary runs and populates the cache with wrong-profile data. After patches are applied, the patched HUD serves the stale cache indefinitely (60s TTL resets on reads). Fix: the post-patches script must clear both profiles’ usage caches after applying patches.

API failure overwrites good cache with error. When the usage API returns 423 (Locked) or any non-200 status, the original code overwrites the stale cache entry (which had valid usage data) with {apiUnavailable: true}. This causes Usage ⚠ (423) to flash for 15 seconds even though the stale data was only seconds old. The fix uses a stale-while-revalidate pattern: check if stale cache exists and is non-failure before overwriting.

0-byte lock file creates a permanent “busy” state. If the HUD process crashes between fs.openSync(lockPath, 'wx') and fs.writeFileSync(fd, timestamp), the lock file is created but empty (0 bytes). readLockTimestamp() returns null for empty files, and the stale-lock cleanup checks if (lockTimestamp != null && ...) — so the null case is never cleaned up. The lock stays permanently “busy,” and the HUD returns stale cache data forever. I submitted an upstream fix (PR #203) that adds a lockTimestamp === null guard using statSync().mtimeMs to distinguish crash leftovers (old mtime — remove) from active writers (recent mtime — return busy).

Stale-while-revalidate without TTL refresh causes a 429 retry storm. The stale cache fallback (Patch 9) returns good stale data when the API fails, but originally it did not update the cache timestamp. Every render cycle (1–2s) saw expired cache, retried the API, got 429, returned stale, and repeated. Even with a single tmux session, this hammered the API continuously. The fix: call writeCache(homeDir, cacheState.data, now) to give the stale data a fresh 60s TTL, limiting retries to once per minute instead of every render.

The Solution

Embed CLAUDE_CONFIG_DIR directly in each profile’s settings.json statusline command. This bypasses the env var passthrough problem entirely.

json
// Personal — defaults to ~/.claude, no override needed
"command": "/path/to/statusline-wrapper.sh"

// Work — must explicitly set CLAUDE_CONFIG_DIR
"command": "CLAUDE_CONFIG_DIR=/path/to/.claude-work /path/to/statusline-wrapper.sh"

The personal profile doesn’t need an override since ~/.claude is the default. The work profile sets CLAUDE_CONFIG_DIR inline so the wrapper script knows which config directory (and therefore which keychain entry) to read.

Profile Architecture

text
~/.claude/              (personal, default)
├── plugins/cache/claude-hud/   (independent binary, patched)
└── settings.json               (statusline → wrapper)

~/.claude-work/         (work)
├── plugins/cache/claude-hud/   (independent binary, patched)
└── settings.json               (statusline → CLAUDE_CONFIG_DIR=... wrapper)

That is the layout I first built. Each profile had its own HUD install, and each had to be patched separately. It didn’t stay that way: by September 2026 the work profile’s plugins/ directory was a symlink to the personal one, so both profiles shared one plugin cache and one HUD config. Later I retired the work profile altogether.

What I Run Now

Here is what the statusline wrapper and the patch script do today:

  • No version pin. The wrapper loads the newest non-orphaned cache directory under ~/.claude/plugins/cache/claude-hud/claude-hud/. The plugin manager marks each replaced version as orphaned, so that directory is the installed version. An opt-in CLAUDE_HUD_VERSION variable can pin a version for bisecting a bad upstream release, and a pin that names a missing directory fails loudly instead of falling back.
  • Config as a regular file. claude-hud opens its config with O_NOFOLLOW. A symlinked config.json fails with ELOOP, and the HUD silently falls back to its built-in defaults. So the config deploys as a copy.
  • Config first, patch last. A customization goes into config.json when a key exists for it; the installed src/config.ts is the authority on what config exposes. A source patch is only for what no key covers.
  • A self-healing patch guard. On every render the wrapper signs the three patched files (mtime and size). When a plugin update rewrites one, the signature changes, and the wrapper re-runs the patch script in the background so the next render is patched again.

The patch script resolves the same cache directory as the wrapper and applies five surgical patches. Each anchors on one exact expression and fails loudly if the anchor is gone:

#Target filePurpose
1i18n/en.tsAbbreviate the Context label to Ctx:
2i18n/en.tsCompact usage window labels 5h: / 7d:
3render/usage.tsPace indicator on each usage window
4render/parts.tsCompact pipe badge Opus5|h with short effort
5render/parts.tsPurple neon color for the package version text

None of these can be expressed through config today: upstream has a whole-language switch but no per-label override, and its own pace option only recolors a window. The patch count has moved a lot over time — 30 at v0.0.6, 9 at v0.0.9, 13 on the pinned v0.0.12, briefly 1 after I retired the pin, 4 once I allowed small patches again in September 2026, and 5 now.

Cache Lock Mechanism

The 429 race condition required a lock mechanism to prevent concurrent API calls. The upstream repo’s solution uses tryAcquireCacheLock with O_EXCL atomic file creation — the operating system guarantees only one process succeeds in creating the lock file.

The flow works like this: when cache expires, the first process acquires the lock and fetches fresh data. Other processes see the lock, return busy, and poll every 50ms (up to 2 seconds) waiting for fresh cache to appear. Stale locks older than 30 seconds are auto-cleaned to prevent deadlocks from crashed processes.

This makes the upstream TTLs safe: 60 seconds for successful responses, 15 seconds for failures. Without the lock, multiple processes would all fire API calls on every cache expiry. With the lock, exactly one process fetches per expiry cycle. Two important details: clearCache() must also remove .usage-cache.lock — otherwise an orphaned lock file blocks all processes from fetching. And watch out for the 0-byte lock edge case: if the process crashes between creating the lock file and writing the timestamp, the file exists but is empty. The stale-lock cleanup skips it because it checks for a non-null timestamp. The upstream fix (PR #203) adds a lockTimestamp === null guard that falls back to statSync().mtimeMs — if the file’s mtime is old, it’s a crash leftover and gets removed; if recent, an active writer might still be going.

Midnight Aurora Theme

This theme was a copied colors.ts patch in the v0.0.x setup, and that patch is retired. Current claude-hud takes truecolor hex values per role (context, usage, warning, critical, model, project and so on) in the colors object of config.json, so a palette no longer needs a source patch. The original theme used 9 semantic color roles via ANSI 256-color codes (\x1b[38;5;{N}m):

RoleCodeColor NameUsage
NEON_VIOLET135Vivid purpleHero elements, quotes
VIOLET141Soft purpleDominant text color
SOFT_CYAN117Light cyanPrimary informational
WARM_AMBER215GoldAccent highlights
SOFT_ROSE211PinkSecondary emphasis
MINT85GreenSuccess indicators
PEACH216Light orangeWarnings
CORAL203Red-orangeDanger/error
LAVENDER103Muted purpleMuted/disabled text
GRAY245NeutralInactive elements

Color functions use semantic names (e.g., green() maps to success) rather than literal color names. Swapping the entire palette only requires editing colors.ts. The quote line renders with BOLD + neonViolet() (code 135, vivid) — separate from general violet() (code 141, softer) for visual hierarchy.

HUD Configuration

The HUD plugin supports several configuration options worth knowing:

Layout modes. Two choices: "compact" (single line, truncates on narrow terminals) and "expanded" (multiline with identity, project, environment, and usage on separate lines). Use "expanded" to avoid losing information to truncation.

Patch durability. Plugin updates overwrite source files, so claude-hud-post-patches.sh re-applies the patches after updates. Today it covers 5 patches, and the wrapper’s patch guard re-runs it automatically when an update rewrites a patched file.

Always show the 7-day usage window. Set sevenDayThreshold: 0 in config. The default (80) hides the 7-day window until usage exceeds 80%.

Output token speed. Enable showSpeed to display output token speed (tok/s) via the speed-tracker.ts module.

Context display modes. The contextValue option switches context display between 'percent' and 'tokens' in both compact and expanded layouts.

Expanded layout order. In the v0.0.x setup a render/index.ts template patch set the order and rendered the quote LAST, so on narrow terminals the decorative quote clipped first. Today the order comes from elementOrder in config.json, and the quote is the config customLine, which upstream renders inline on the first row. I accepted that trade when I dropped the template patch.

Speed tracker return type. getOutputSpeed() returns number | null directly, not an object. Check the return type carefully when integrating speed into custom renderers.

Stale-while-revalidate on API failure (v0.0.x). When the usage API fails (423, timeout, network error), the HUD checks if the expired cache holds valid data (not apiUnavailable). If so, it returns the stale data AND refreshes the cache timestamp with writeCache. This gives the stale data a fresh 60s TTL so retries happen once per minute, not every render cycle. Without the timestamp refresh, every 1–2 second render sees expired cache, retries the API, hits 429, and returns stale — a continuous retry storm even from a single session. Only when no previous good data exists does the HUD fall through to failure-caching.

Reinstall workflow. When things go sideways, the full reinstall sequence is: claude plugin uninstall claude-hud@claude-hud, then claude plugin install claude-hud@claude-hud. The plugin install overwrites source with clean upstream; the patch guard re-runs claude-hud-post-patches.sh on the next render, or you can run it by hand to see its output. Remember that known_marketplaces.json stores absolute paths to marketplace clones — these must be updated after any profile directory renames.

Token Management

Claude Code manages OAuth tokens natively per profile:

  • Auto-creates profile-specific keychain entries on login
  • Auto-refreshes tokens before expiration
  • No manual sync needed — syncing between entries is harmful

When /login is needed: After refresh token revocation, new machine setup, manual keychain deletion, or when both profile-specific and default tokens have expired. You can diagnose the dual-expiry scenario by checking for apiUnavailable: true in the cache file combined with expired expiresAt timestamps in keychain entries.

Common Pitfalls

These are the mistakes I made (and you should avoid):

  1. Don’t sync tokens between keychain entries. Claude manages them natively per profile. Manual sync breaks things.
  2. Don’t assume env vars pass through. Embed CLAUDE_CONFIG_DIR in the statusline command.
  3. Don’t patch what config can express. Check src/config.ts in the installed plugin first. Every plugin update overwrites a patch; a config key survives.
  4. Reload your shell after .zshrc changes. Old functions stay in memory. New settings only apply in new terminal sessions.
  5. Check for duplicate keychain entries. Duplicates cause unpredictable reads. List entries with security find-generic-password -a and remove duplicates.
  6. Don’t symlink the HUD config. claude-hud opens it with O_NOFOLLOW, so a symlink silently drops every setting back to the defaults.
  7. Watch for 0-byte lock files (v0.0.x). If the HUD crashes mid-lock-creation, the empty lock file blocks all processes from fetching fresh data. Check for a .usage-cache.lock file with 0 bytes and delete it manually if usage is stuck.
  8. Update known_marketplaces.json after directory renames. This file stores absolute paths to marketplace clones. After renaming a profile directory, plugin install commands will fail silently.
  9. Frame composed statusline rows explicitly. In June 2026 my statusline-wrapper.sh appended Token Optimizer health (CtxQ, Eff, optional duration) before the 3B session-state row (3B claude·<sid> · locks:N). The Token Optimizer filter had to print a trailing newline, or the rows concatenated as Eff:--3B claude.... Today the wrapper prints the claude-hud rows, an optional Ponytail badge row, and the session row last, and each row must still end with a newline. I used to guard this with a claude-hud-pin-guard.sh script, but I have since retired that guard and don’t plan to bring it back. The newline invariant still matters when checking the wrapper, and patch-marker checks alone don’t prove the rows are framed correctly.
  10. Don’t pin a plugin version as a defense. A plugin reconcile can delete the pinned cache directory. Mine was deleted twice, and both times the HUD degraded without a single error.

Why This Works

The inline environment variable approach works because it completely bypasses the passthrough problem. Instead of relying on Claude Code to forward env vars to subprocesses (which it doesn’t), the correct values are embedded in the command string itself.

In the v0.0.x setup, the HUD read CLAUDE_CONFIG_DIR from its own environment, resolved the correct keychain entry and cache path, and displayed the right usage stats, while the file-based lock kept concurrent sessions from stampeding the API. Current claude-hud still reads CLAUDE_CONFIG_DIR itself, but it no longer needs a keychain entry or a usage cache, because Claude Code hands it the rate-limit data on stdin.

Practical Tips

Use this setup when: You run Claude Code with separate personal and work Anthropic accounts and need accurate per-account usage tracking in the terminal statusline.

Skip this when: You have a single account (no profile separation needed), only use the web UI (HUD is a terminal feature), or don’t use the HUD plugin at all. The basic multi-profile setup (CLAUDE_CONFIG_DIR) works without HUD patches. On v0.0.x the patches were needed for accurate statusline stats; the current patches only change appearance.

The key insight: Claude Code’s subprocess environment may not match your expectations. When in doubt, embed values directly in the command string rather than relying on environment variable inheritance.

Comments