omc-lens

omc-lens

omc-lens is a visually enhanced statusline HUD for Claude Code, built on top of the OMC (oh-my-claudecode) data bridge. It renders rich session information across three lines using Nerd Font icons and 256-colour ANSI gradient bars. The renderer is registered as a statusLine command in Claude Code's settings.json, giving you a live, always-visible view of your session state.

Features

• Three-line layout: identity bar (Line 1), context/token/cost bar (Line 2), and orchestration/rate-limit bar (Line 3)
• Model identity segment: active model name (opus / sonnet / haiku) with tier-specific 256-colour coding and Nerd Font icon
• Extended thinking indicator: visual flag when extended thinking is active
• Permission approval alert: prominent APPROVE? badge when a tool permission is pending
• CWD and git status: current directory basename, branch name, staged/modified/untracked counts, ahead/behind indicators
• OMC version display: installed OMC version; shows (*newVersion) when an update is available on GitHub (cached 6-hour fetch)
• omc-lens update indicator: appears in magenta only when a newer omc-lens release exists — hidden otherwise
• Worktree: active worktree shown in Line 1
• 20-block 256-colour gradient context bar: cyan-to-red fill with embedded percentage text; COMPRESS? and CRITICAL warnings at 80 % and 90 %
• Token usage: input, output, session total, and reasoning token counts with compact K/M formatting
• Session cost: cumulative USD cost formatted to four decimal places
• Tool, agent, and skill call counters: wrench / robot / flash icons with running totals; last activated skill name
• Background task count: live count of active background tasks
• Todo progress: completed/total ratio with first in-progress item label (up to 30 characters)
• Vim mode indicator: INSERT vs NORMAL with distinct colours
• Cache hit metrics: per-request hit rate (hr), per-request efficiency (ef), and cumulative session hit rate (cu) with a 14-step colour gradient (cyan = high, red = low) and 3-tier per-turn delta colouring (noise / meaningful / large)
• Rate-limit gauges: per-window usage bars with 14-step colour gradient
• Agent tree: running sub-agents rendered as a box-drawing tree, up to four entries with overflow count
• Crash-safe: any rendering error falls back to a dim one-line message; Claude Code is never interrupted
• Update notifications: a SessionStart hook checks GitHub every 6 hours for new omc-lens and oh-my-claudecode releases. When an update is available it injects a parsable banner into Claude's session context and, on macOS only, also surfaces a native notification popup (consolidated into a single popup when both have updates). On other platforms the banner-only path is used.

Requirements

• macOS or Linux
• Node.js 18 or later
• OMC (oh-my-claudecode) plugin installed in Claude Code
• A terminal configured with a Nerd Font (e.g. JetBrainsMono Nerd Font, FiraCode Nerd Font)
• 256-colour terminal support

Installation

Inside Claude Code, run:

/plugin marketplace add https://github.com/DokaDev/omc-lens
/plugin install omc-lens@omc-lens

Activation

After installation, run the setup command inside Claude Code:

/install-omc-lens

This will:

1. Check dependencies (Node.js, OMC plugin).
2. Create ~/.claude/hud/omc-lens.mjs as a symlink to the plugin's src/hud.mjs.
3. Back up the current statusLine entry in ~/.claude/settings.json.
4. Set statusLine to node ~/.claude/hud/omc-lens.mjs.

Restart Claude Code to activate the HUD. To revert, run /uninstall-omc-lens.

Updating

/plugin marketplace update omc-lens
/plugin update omc-lens@omc-lens
/reload-plugins
/install-omc-lens

The final /install-omc-lens is required so that the symlink in ~/.claude/hud/ is re-pointed at the newly installed plugin version directory.

Uninstalling

To deactivate omc-lens and restore the previous statusline:

/uninstall-omc-lens

This removes the symlink and restores your backed-up statusLine value in settings.json. If no backup is found, the statusLine key is removed entirely so Claude Code falls back to its built-in default. Restart Claude Code for the change to take effect.

To remove the plugin entirely:

/plugin uninstall omc-lens@omc-lens

How It Works