copilot-hud

Copilot HUD

A GitHub Copilot CLI plugin that displays a real-time status line inside your Copilot session — project path, git branch, context usage, tool activity, and background agents.

English | 中文

  /Users/sky/Github/my-project [↙ main]                 Claude Opus 4.6 (3x) (high)
──────────────────────────────────────────────────────────────────────────────────────
  [Opus 4.6 3x·high] │ my-project │ git:(main* ↑2) │ Creating README │ ⏱ 5m │ +42/-3
  Ctx ████░░░░░░ 70.0k/200.0k 35% │ Credits 1.42 │ in:1.5M out:12.2k cache:1.4M │ 42 tok/s
  ✓ ✎ Edit: auth.ts | ✓ ⌨ Bash: git status ×3 | ◐ ◉ Read: index.ts
  ◐ [explore] Analyze test coverage (45s…)
  ✓ [explore] Search auth module (18s)
  ✗ [general-purpose] Parse config schema (1m 12s)

Install

Prerequisites

• GitHub Copilot CLI v1.0.12+ installed and authenticated
• Node.js 18+
• jq — required for hook scripts that track tool and agent activity

Quick Start

1. Install the plugin. Prefer the marketplace path — direct repo installs are deprecated by Copilot CLI:

   # Marketplace install (preferred)
   copilot plugin marketplace add griches/copilot-hud
   copilot plugin install copilot-hud@copilot-hud
   
   # Or, direct install (still works, but emits a deprecation warning)
   copilot plugin install griches/copilot-hud
   

2. Start Copilot with the experimental flag and run the setup skill:

   copilot --experimental
   

   Then inside the session:

   /copilot-hud:setup
   

The setup will automatically create the wrapper script, configure the status line, and enable the experimental flag. Restart Copilot after setup and the HUD will appear at the bottom of the interface.

3. (Optional) Customize what the HUD shows:

   /copilot-hud:configure
   

   Choose which elements to display — session name, duration, token breakdown, output speed, tool activity, agent tracking, and git style.

Note: The statusLine feature in Copilot CLI requires the --experimental flag as of v1.0.12. The setup skill adds this to your config permanently.

Install from Source

git clone https://github.com/griches/copilot-hud.git
cd copilot-hud
npm install
npm run build
copilot plugin install ./

---

Features

Model and Project Info

Shows which model you're using, your project path, git branch, session info, and code changes at a glance. The model name is shortened for readability — claude-opus-4.6 (3x) (high) becomes [Opus 4.6 3x·high]. The model badge parses effort level (high/medium/low) and multiplier (3x) from display_name. Path depth is configurable (pathLevels 0–3; 0 shows the full absolute path). Lines added/removed are shown with green/red coloring.

[Opus 4.6 3x·high] │ my-project │ git:(main* ↑2) │ ⏱ 5m │ +42/-3

Context Window and Requests

A live progress bar showing how much of the current context window you're using. Prefers Copilot's live current_context_used_percentage / current_context_tokens / displayed_context_limit fields (populated from the very first render) and falls back to the legacy cumulative fields when unavailable, so the bar is accurate and populated immediately on session start instead of showing 0% until the first response. Changes color as you approach the limit — green when you have plenty of room, yellow when it's getting tight, red when you're running low. Token breakdown (in/out/cache) is shown in a single segment.

Ctx ████░░░░░░ 70.0k/200.0k 35% │ Credits 1.42 │ in:1.5M out:12.2k cache:1.4M │ 42 tok/s

• Ctx — context bar with exact token usage used/total percentage
• Credits — AI units (AIU) consumed this session under Copilot's usage-based billing (1 AIU = $0.01 USD). Falls back to legacy premium request count (Reqs) on older CLI versions.
• in/out/cache — cumulative input, output, and cache tokens
• tok/s — output generation speed
• last call (optional) — tokens used in the most recent API call
• Cache R/W (optional) — separate cache read vs write counts

Session Info

Optionally show the session name and duration on the project line:

[Opus 4.6 3x·high] │ my-project │ git:(main* ↑2) │ Creating README │ ⏱ 5m │ +42/-3

Code Changes

Shows total lines added and removed during the session with green/red coloring:

+42/-3

Effort & Multiplier

The model badge shows effort level and request multiplier parsed from the model's display name. claude-opus-4.6 (3x) (high) becomes [Opus 4.6 3x·high].

Remote Session Indicator

When a remote controller is attached to your Copilot session (via --remote / --connect), a magenta ◉ remote badge appears right after the model badge so you can see at a glance that another device or teammate is driving the same session.