Skip to content
Get packs

Guide · Agent skill

How to use the HUD Statusline Configurator agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The hud skill sets up and customises a status bar, called the HUD, that appears in Claude Code. It can show things like the git branch, context window usage, running subagents and todo progress. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to check before you run it.

HUD Statusline ConfiguratorYeachan-Heo/oh-my-claudecode · MIT

Quick start

  1. 1Install oh-my-claudecode. Make sure the oh-my-claudecode plugin is installed, since the HUD needs its template and dist files. The setup check reports whether it is found.
  2. 2Add the hud skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ for one project. You can also upload it under Settings → Capabilities → Skills.
  3. 3Run setup. Type /oh-my-claudecode:hud setup in Claude Code. The agent checks for existing files, copies the wrapper script and updates settings.json.
  4. 4Restart Claude Code. Restart the app so the new statusline takes effect.
  5. 5Pick a preset. Run /oh-my-claudecode:hud minimal, focused or full to choose how much information the bar shows.

What is an agent skill and what does hud do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. When a request matches the skill, the agent follows its instructions. The hud skill is one of these, and it is part of the oh-my-claudecode project, published under the MIT licence.

When you run it, the agent copies a wrapper script and a helper file into your ~/.claude folder, edits your settings.json so the statusline runs that script, and tells you to restart Claude Code. You can also switch between minimal, focused and full display presets.

  • Shows the git repository and branch, context window usage (ctx), running subagents (agents), background task slots (bg) and todo completion (todos)
  • Offers three presets: minimal, focused (the default) and full
  • Full preset adds multi-line agent details with tree characters and how long each agent has been running

What do you need before installing?

The skill depends on several pieces. Check each one before you start, because the HUD reads files from the oh-my-claudecode plugin and will report it as not installed if they are missing.

  • Claude Code
  • The oh-my-claudecode plugin installed, which provides the template and dist files
  • Node.js, because the setup commands run via node -e and the statusline itself runs with node
  • Permission for the skill to run scripts. This skill runs scripts and does not use the network

How do you install the hud skill?

You have two options. Download the ZIP file from this page, then either unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder for that project only.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into .claude/skills/ inside your project
  • Apps install: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with a request?

You can use the slash commands listed in the skill, or describe what you want in plain language. Slash commands are the most predictable option. The skill accepts the arguments setup, minimal, focused, full and status.

Running the command with no argument shows the current HUD status and sets it up if needed. Use setup to install or repair the statusline.

  • /oh-my-claudecode:hud shows current HUD status and auto-sets up if needed
  • /oh-my-claudecode:hud setup installs or repairs the statusline
  • /oh-my-claudecode:hud minimal switches to the minimal display
  • /oh-my-claudecode:hud focused switches to the focused display (default)
  • /oh-my-claudecode:hud full switches to the full display
  • /oh-my-claudecode:hud status shows detailed HUD status
/oh-my-claudecode:hud setup

What changes does the setup make?

Setup creates a hud folder inside your Claude config directory, copies the wrapper script omc-hud.mjs and a config-dir.mjs helper into it, and makes the script executable on Unix. It then sets the statusLine field in settings.json to run the script with node. Other settings are kept, because the agent edits only that field.

The skill also looks for an old omc-hud.js script and removes it if found. Changes take effect after you restart Claude Code. HUD config lives under the omcHud key in settings.json.

  • Creates ~/.claude/hud/omc-hud.mjs and ~/.claude/hud/lib/config-dir.mjs
  • Rewrites the statusLine field in ~/.claude/settings.json
  • Respects CLAUDE_CONFIG_DIR if that variable is set
  • Stores HUD options under the omcHud key in settings.json

How do you customise the display?

Pick a preset to start with, then adjust individual elements if you want. Each option can be set on its own, and any unset values fall back to defaults. You can edit the omcHud config by hand.

Colours also carry meaning. Green is normal, yellow is a warning (context above 70%, or ralph above 7), and red is critical (context above 85%, or ralph at its maximum).

  • Minimal shows only the essentials, for example: [OMC] ralph | todos:2/5
  • Focused (default) shows all relevant elements, including branch, context, agents and todos
  • Full adds the multi-line agent view with tree characters and per-agent duration
  • Description text for each running agent is cut at 45 characters
{"preset":"focused","elements":{"contextBar":true,"agents":true,"todos":true,"maxOutputLines":4}}

What should you check for safety?

This skill writes to your ~/.claude folder and runs scripts, so read the steps before approving them. It rewrites the statusLine field in settings.json and copies files into that folder. If you share the machine and do not want your settings changed, do not run it.

The skill does not use the network, according to its description. Setup also includes a Windows-specific rule: use forward slashes in the statusLine command path, because bash treats backslashes as escape characters.

  • Only install on a machine where modifying ~/.claude/settings.json is acceptable
  • The HUD reads plugin files, so it will not work without oh-my-claudecode
  • On Windows, use forward slashes and an absolute path in the command

What people use it for

  • Keep an eye on context window usage during long sessions with many steps
  • See which subagents are running and how long each has been working
  • Track todo completion and background task slots while working on a feature
  • Use the minimal preset on a small screen and full when debugging agent activity

Frequently asked questions

Is the hud skill free to use?

The oh-my-claudecode project is published under the MIT licence, and this skill is listed with that licence. The page does not list any price, so check the project's licence file for the terms.

What do I need to install the hud skill?

You need Claude Code, the oh-my-claudecode plugin, and Node.js. The plugin provides the template and dist files the HUD copies, and Node.js runs both the setup commands and the statusline.

How do I install the hud skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Why does the HUD say the plugin is not installed?

The HUD reads files from the oh-my-claudecode plugin, so it cannot run without them. Install the plugin with /plugin install oh-my-claudecode, then run setup again.

Does the hud skill change my settings?

Yes. It rewrites the statusLine field in ~/.claude/settings.json and copies scripts into the hud folder. Other settings are meant to be preserved, but you should avoid it on shared machines where your settings must not change.

Are there alternatives to the hud skill?

The source does not compare this skill with other tools, so it cannot say how they differ. You can still configure the HUD manually by editing the omcHud config in settings.json.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

The hud skill suits Claude Code users of the oh-my-claudecode plugin who run long sessions with multiple subagents and want to see context usage at a glance. It is a poor choice if you do not use that plugin, or if you share a machine and do not want your ~/.claude/settings.json modified.

Download the skill