CodexHud

See the work behind an agentic coding session — before it disappears into the terminal scrollback.

CodexHud is a local Windows extension for VS Code. It turns Codex session logs into a live dashboard: the main agent at the center, the subagents it calls, the tools they run, and the skills they load. It also shows token usage, API-equivalent cost, context pressure, execution time, and a clear completion signal. It is for the moment when “it is still working” is not enough. Open the HUD to understand the shape of a task, find a busy subagent, verify that a skill was actually called, and know when the root session is complete.

CodexHud is an independent community project. It is not affiliated with, endorsed by, or sponsored by OpenAI or Microsoft.

Why use it?

Delegation becomes visible. See which subagents belong to the current root task and their observed state. Skills become verifiable. Distinguish a skill reference from a skill that was actually called. Tool ownership stays clear. Follow the agent that owns each tool, its lifecycle, and the execution flow. Completion reaches you. Receive one clear signal in VS Code, Windows, sound, or the optional Ntfy phone push.

The extension reads local Codex session data only. It does not edit Codex logs, run a web server, or expose your HUD in a browser.

Install

CodexHud currently supports trusted local Windows x64 workspaces in VS Code 1.132.0 or later.

1. In VS Code, open Extensions and search for CodexHud.
2. Confirm the publisher is PareschiApps, then select Install.
3. Open a trusted local folder and start a Codex task.
4. Select the CodexHud status-bar item or run CodexHud: Open HUD from the Command Palette.

If you previously installed a legacy or deleted-listing build, uninstall it first. The current extension identity is PareschiApps.codex-hud and its Marketplace title is CodexHud Flow; the in-product brand remains CodexHud.

Watch the flow

The live graph keeps the main agent, subagents, skills, and tools together in the current task. It makes delegation legible without inventing relationships: a tool stays attached to the agent that ran it, and a skill read is not presented as a completed skill execution.

• Use Focus graph to give the execution map the whole panel.
• Follow the latest task with Live, or select a session or turn to inspect its history.
• Open the activity list for compact tool history and details.
• See token usage, estimated cost, context, and elapsed execution time without leaving VS Code.
• Keep monitoring active even while the panel is closed.

History controls change only CodexHud’s view. They never delete or rewrite Codex session logs.

Get a phone notification with Ntfy

Ntfy support is built in. For the normal public Ntfy service, install the official ntfy phone app, choose a hard-to-guess topic, subscribe to it on the phone, then save that same topic in CodexHud → Settings. After the root Codex task explicitly completes, the push is deliberately small: 🤖 ✅ COMPLETED, the elapsed time, and the session name. It does not send prompts, payloads, tool arguments, command output, token counts, costs, or private reasoning.

1. In the ntfy app, subscribe to a random topic of 1 to 64 letters, numbers, hyphens, or underscores. Topics do not need to be created first. Do not use a name, email address, project name, or anything guessable.
2. In VS Code, open CodexHud → Settings, enable Ntfy, enter the same topic, and select Save and test.
3. Confirm the test notification on the phone. If necessary, allow notifications for ntfy in the phone operating system.

Subagent completions and isolated tool failures do not create extra completion pushes.

No token is needed for the normal setup

The public Ntfy service uses a secret topic and needs no token. The topic is stored encrypted in VS Code secure storage, not in ordinary Settings, Settings Sync, logs, or Webview state. Saving a new topic replaces the previous one. Use Remove topic to delete it.

A token is relevant only for an authenticated or self-hosted Ntfy server. Put it in an operating-system environment variable before starting VS Code, then enter only that variable’s name in Token environment variable. Never paste a token into the HUD, VS Code Settings, a local environment file, or this repository.

For a protected server, choose its HTTPS address in Server, subscribe to the same server and topic in the phone app, restart VS Code after adding the environment variable, and select Save and test. Delivery diagnostics are available in the CodexHud Output channel without exposing the topic or token.

Notifications and privacy

CodexHud alerts only after the main task records an explicit terminal event. Replayed history does not alert. Ntfy is optional and independent from the HUD banner, VS Code notification, optional Windows toast, and local sound.

The extension uses VS Code-managed storage for its rebuildable index, delivery reservations, view state, and encrypted Ntfy topic. Clear Stored Data removes only CodexHud-owned data and the saved Ntfy topic; it never deletes Codex logs, unrelated settings, or your system PATH.

Marketplace updates

The Marketplace page uses the README and changelog inside the published extension package. To change this page, prepare a new extension version, package it, and publish that version. Updating an extension from the same PareschiApps publisher installs over the previous version.

The images on this page are bundled inside the extension package, so the Marketplace page does not depend on assets hosted by the private repository.

Support and limitations

• Windows x64 local workspaces only; remote, browser, Linux, macOS, Windows ARM64, and WSL environments are not supported by this package.
• The project repository may remain private. Marketplace users can use the Marketplace Q&A route for support.
• Initial indexing is progressive. Very large session files can take time to reach the latest event.
• The cost display is an API-equivalent estimate, not a ChatGPT subscription charge.

See the Ntfy documentation for phone subscriptions and server options. See the extension’s bundled license, security policy, support guide, and changelog for project details.

Created by Carlos Pareschi.