# hud

> A compact heads-up display CLI for coding agents (OpenCode, Claude Code, Codex) that shows live instruments while the agent works and renders the full answer when it stops.

hud is a zero-dependency, MIT-licensed terminal heads-up display built by Tracer Research Lab that wraps OpenCode, Claude Code, and Codex in a compact instrument panel. Instead of a scrolling wall of tool calls, it collapses agent activity into a live dashboard that updates in place, keeps the prompt bar always writable, and renders the full answer in markdown when the agent finishes. It was created by Adam Rida and published in August 2026 as an open-source companion to Tracer's Echo product.

## What It Is

hud is a CLI layer that drives each supported coding agent headless through its JSON event stream, maps events onto shared instruments, and maintains one real session per conversation via each engine's native resume mechanism. It is not a fork or patch of any agent — it sits in front of the agent's own CLI and translates its output into a structured display. The result is a TUI (terminal user interface) that shows status, model, mode, reasoning effort, message count, elapsed time, output tokens, live subagents, session cost, context size, and disk size — all in a configurable gauge cluster.

## How the Instrument Panel Works

The panel is built around a set of named gauges that can be reordered and filtered with `/gauges`:

- `STS` — status flag (NORM / PERM / INTR / FAULT)
- `MDL` — active model name
- `MODE` — permission/sandbox mode
- `EFF` — reasoning effort
- `MSG` — message count
- `T+` — elapsed time
- `TOK` — output tokens including reasoning
- `AGT` — live subagents
- `USD` — session cost where the engine reports it
- `CTX` — context size
- `DSK` — conversation size on disk (Claude Code, Codex)

The activity line shows what the agent is doing in real time (`READ`, `EDIT`, `EXEC`, `SCAN`, `NET`, `AGENT`, `PLAN`, `THINK`). Links the agent shares are stored in a per-session ledger and rendered as OSC 8 hyperlinks — cmd/ctrl-clickable in iTerm2, Ghostty, WezTerm, Kitty, and compatible terminals.

## The Full-TUI Toggle

A key design feature is the `/hud` command, which works bidirectionally. From inside hud it opens the same session in the engine's full TUI; from the full TUI, typing `/hud` (or the engine-specific equivalent) returns to the compact display — same session, nothing lost, terminal wiped clean. Each engine gets its most native handback mechanism:

- **OpenCode**: a custom command writes a handoff file locally at expansion time (near-zero tokens)
- **Claude Code**: a `UserPromptSubmit` hook intercepts before the model (zero tokens, ~150 ms)
- **Codex**: a global `AGENTS.md` rule or quitting the TUI

## Setup Path

Installation is a single npm command: `npm install -g adrida/hud-mode && hud install`. The `hud install` wizard configures the default agent, optional Echo integration for OpenCode, and wires the handback into all three CLIs. It requires Node ≥ 18 and at least one of `opencode`, `claude`, or `codex` on the PATH. `hud uninstall` cleanly removes all installed hooks and config blocks.

## Current Status

The repository was created on August 5, 2026 and last updated August 7, 2026, making it a very recent release. It is published under the MIT license by Adam Rida (adrida on GitHub) as part of Tracer Research Lab, a YC-backed research lab. The roadmap lists in-hud permission approvals via the Agent SDK, streaming partial text into the narration line, zero-token Codex handback via plugin hooks, and per-directory engine memory as planned future work.

## Features
- Live instrument panel (status, model, mode, effort, tokens, cost, context)
- Always-writable prompt bar — queue messages mid-turn
- ESC interrupt without losing session
- Full-TUI toggle via /hud command (bidirectional)
- Supports OpenCode, Claude Code, and Codex
- OpenAI-compatible Echo endpoint integration
- Per-session link ledger with OSC 8 clickable hyperlinks
- Configurable gauge cluster via /gauges command
- Session resume with -r flag
- Markdown rendering with clickable links in answer panel
- QR code generator (zero-dependency, from-scratch encoder)
- Message history recall with up/down arrows
- Zero dependencies
- MIT licensed open source

## Integrations
OpenCode, Claude Code, Codex, Echo (Tracer), iTerm2, Ghostty, WezTerm, Kitty

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://tracerml.ai
- Documentation: https://echo.tracerml.ai/docs/api
- Repository: https://github.com/adrida/hud-mode
- EveryDev.ai: https://www.everydev.ai/tools/hud-mode