Claude HUD Configuration Guide: Layouts, Presets, and Display Options

Mar 21, 2026

I was working with Claude Code and noticed my statusline was getting cluttered. I wanted to see my git status and current model, but I didn’t need the full breakdown of every tool being called. That’s when I discovered Claude HUD’s configuration options.

The Problem

By default, Claude HUD shows a lot of information. When I’m deep in a coding session, I want my statusline to be informative but not overwhelming. Sometimes I need everything visible; other times I just want the essentials.

The issue is that different workflows need different information. When I’m debugging, I want to see tool activity. When I’m planning, I care about my todo list. But I don’t always want everything on screen.

The Solution: `/claude-hud:configure`

Claude HUD provides a guided configuration wizard. I just ran:

/claude-hud:configure

This launched an interactive setup that walked me through the options.

Layout Modes

The first choice I made was between two layout modes:

Layout	Description
Expanded	Multi-line semantic layout with separate lines for model, context, tools, agents, todos
Compact	Single-line condensed view

I initially tried compact because I thought I wanted minimal screen space. But I found it harder to quickly parse the information. The expanded layout groups related info together, which actually makes it faster for me to scan.

Here’s how expanded layout organizes things:

Line 1: Model name, project path, git status
Line 2: Context bar, usage bar
Line 3+: Tools, agents, todos (when enabled)

Presets

After choosing a layout, I could select from three presets:

Preset	What’s Shown
Full	Everything — tools, agents, todos, git, usage, duration
Essential	Activity lines + git status, minimal info clutter
Minimal	Core only — just model name and context bar

I started with Essential. It felt like a good middle ground — I get my git status and context, but I’m not overwhelmed with tool-by-tool updates.

Then I realized I could customize further by toggling individual features.

Feature Toggles

The configuration wizard let me turn individual features on or off:

Feature	What It Shows
`showTools`	Tool activity (which tools are being called)
`showAgents`	Agent status (when using multi-agent workflows)
`showTodos`	Todo progress (task tracking)
`showUsage`	Token usage limits
`showDuration`	Session duration timer

I found the sweet spot for my workflow:

Tools OFF — I don’t need to see every file read or bash command
Agents ON — I use agent workflows and need to see which agent is active
Todos ON — I track my progress and want to see task completion
Usage ON — I want to know when I’m approaching context limits
Duration OFF — I don’t need a timer for my sessions

Git Display Options

I also customized how git information appears:

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true
  }
}

enabled — Show git branch at all
showDirty — Show dirty indicator when there are uncommitted changes
showAheadBehind — Show how many commits ahead/behind remote

I keep all three enabled. Seeing my git status in the statusline is one of the features I appreciate most — I don’t have to run git status separately.

My Final Configuration

After experimenting, here’s what I settled on:

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true
  },
  "display": {
    "showTools": false,
    "showAgents": true,
    "showTodos": true,
    "showUsage": true,
    "showDuration": false
  }
}

The pathLevels: 2 setting shows two directory levels in my project path, which gives me enough context without cluttering the line.

Direct Config File Editing

I learned I can also edit the config file directly:

~/.claude/plugins/claude-hud/config.json

This is faster than running the wizard if I just want to toggle one setting. I’ll use the wizard for initial setup or when I want to reconsider my choices, but direct editing works for quick tweaks.

When I Switch Presets

I’ve found myself switching depending on what I’m doing:

Planning mode — I use Full preset because I want to see todos and agent activity
Implementation mode — I use Essential preset to stay focused
Quick fix mode — I use Minimal preset to reduce distraction

The key insight is that there’s no single “right” configuration. The best setup depends on what I’m working on.

Full Configuration Reference

Here’s the complete list of configuration options:

Option	Type	Default	Description
`lineLayout`	string	`expanded`	`expanded` or `compact`
`pathLevels`	1-3	1	Directory levels in path
`elementOrder`	string[]	[…]	Order of HUD elements
`gitStatus.enabled`	boolean	true	Show git branch
`gitStatus.showDirty`	boolean	true	Show dirty indicator
`gitStatus.showAheadBehind`	boolean	true	Show ahead/behind count
`display.showTools`	boolean	false	Show tool activity
`display.showAgents`	boolean	false	Show agent status
`display.showTodos`	boolean	false	Show todo progress
`display.showUsage`	boolean	true	Show usage limits
`display.showDuration`	boolean	false	Show session duration

What I Learned

Claude HUD’s configuration system taught me that the best statusline is the one that shows me what I need, when I need it, and nothing more. The guided setup with /claude-hud:configure made it easy to get started, and the ability to toggle features individually means I can fine-tune for different workflows.

If you’re using Claude HUD, I’d recommend starting with the Essential preset, then toggling features on as you discover you need them. It’s easier to add information than to figure out what to remove.

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!