codex-goal-progress — Codex plugin for goal progress
codex-goal-progress is a plugin for Claude Code and Codex that shows progress for a Codex Goal and token usage. Enable it separately for each new Goal.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-goal-progress@awesome-codex-pluginsWhat codex-goal-progress does
The plugin adds a progress view beside a native Codex Goal. The model prepares or reuses that Goal’s checklist; a local Helper validates checklist changes and calculates progress for individual objectives and the whole Goal. Token usage and elapsed time appear as separate details.
The display adapts to Codex’s theme, font size, locale, and the layout of the Goal and composer. It requires an Apple Silicon Mac and Codex Desktop. Source installs also need Node.js 22.12 or newer and pnpm 11; the prebuilt macOS release includes its own runtime. Reopen the affected chat after installation so it loads the updated plugin.
What it helps with
- track checklist progress for a Codex Goal
- view overall Goal progress beside the native interface
- check token usage alongside Goal progress
- resume local progress after reopening a chat
Example prompts for the agent
- Enable the Goal Progress skill for this Goal and prepare its checklist.
- Use Goal Progress to update this Goal’s checklist and show its progress.
How to install codex-goal-progress
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install codex-goal-progress@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about codex-goal-progress
How do I install codex-goal-progress in Claude Code?
Run these commands in order: /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install codex-goal-progress@awesome-codex-plugins.
What does codex-goal-progress do?
It displays checklist-based progress for a native Codex Goal and shows token usage separately. A local Helper validates checklist changes and calculates progress.
What does codex-goal-progress require?
It requires an Apple Silicon Mac and Codex Desktop. Source installs also require Node.js 22.12 or newer and pnpm 11; the prebuilt macOS release has its own runtime.
Source text
codex-goal-progress · MIT
<div align="center">
<h1 align="center">
<img src="https://raw.githubusercontent.com/Ezra-Y/codex-goal-progress/main/docs/assets/codex-goal-progress-logo.png" alt="Codex Goal Progress logo" width="130"><br>
Codex Goal Progress
</h1>
<p>A native progress bar for Codex Goals, powered by verified checklists and local progress tracking.</p>
<p>
<strong>English</strong> ·
<a href="https://github.com/Ezra-Y/codex-goal-progress/blob/main/README.zh-CN.md">简体中文</a>
</p>
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/Ezra-Y/codex-goal-progress/0911a93fa55162333c6c772bde478fab29af2660/docs/assets/codex-goal-progress-demo.gif" alt="Codex Goal Progress in action">
</p>
## 🆕 Latest update
### v0.3.10 — Reliable progress after Codex updates
- Restore the right progress when reopening chats or switching between windows.
- Keep progress working when your system timezone changes.
- Report missing progress correctly and finish local installation checks without waiting on unrelated plugin catalogs.
Existing goals, checklists, progress and display preferences are preserved.
## ✨ Features
Displays a progress view beside the native Codex Goal, bringing together current objective
progress, overall progress, and Token usage attributable to that Goal.
| Capability | Behavior |
|---|---|
| Rule-driven progress | Calculates objective and overall progress from a validated checklist; Token usage and elapsed time remain separate supporting data. |
| Verifiable calculation | The model handles only the necessary Goal understanding and checklist updates; the local Helper manages state and progress calculation. |
| Native theme adaptation | Follows Codex Light/Dark mode and the user's current accent color. |
| Type scale adaptation | Reads the current Codex UI font size and derives spacing continuously from it. |
| Layout adaptation | Measures the real native Goal and composer geometry to coordinate fixed and draggable floating layouts. |
| Language adaptation | Reads the live Codex document locale and direction, selects a matching built-in catalog, and falls back to English. |
## 🚀 Quick start
### Install from a plugin marketplace
The source plugin requires an Apple Silicon Mac, Codex Desktop, Node.js 22.12 or newer,
and pnpm 11. Install Goal Progress from the marketplace. On first use it installs the locked
dependencies and builds the Helper in Codex plugin data; later starts reuse that build.
### Install with AI
Send this instruction to an AI:
```text
Install and verify https://github.com/Ezra-Y/codex-goal-progress by following its INSTALL-FOR-AI.md.
```
### Install from Terminal
```bash
curl -fsSL https://github.com/Ezra-Y/codex-goal-progress/releases/latest/download/install.sh -o /tmp/codex-goal-progress-install.sh
sh /tmp/codex-goal-progress-install.sh
```
The script downloads the macOS package and `SHA256SUMS`, verifies the ZIP, and runs the bundled
installer. If Codex must restart, the script asks first.
After installation, follow the reconnect prompt: reopen the affected chat or start a new one so
it loads the updated plugin. Finish running work before a full Codex restart.
## 🛠️ Requirements
- Apple Silicon Mac
- Codex Desktop
- Source Plugin: Node.js 22.12 or newer and pnpm 11
The prebuilt macOS Release includes its own runtime and does not require Node.js or pnpm.
## 🎯 How to use
Open a native Codex Goal, then select the **Goal Progress** Skill.
The current Codex model prepares or reuses that Goal's checklist and creates a local progress
record.
Enable Goal Progress separately for each new Goal. Ordinary Goals continue through the native
Codex flow.
## 🌓 Progress states and themes
### Preparing the checklist
<p align="center">
<img src="https://raw.githubusercontent.com/Ezra-Y/codex-goal-progress/0911a93fa55162333c6c772bde478fab29af2660/docs/assets/codex-goal-progress-preparing-light-en.gif" alt="Goal Progress preparing the acceptance checklist" width="760">
</p>
### Light
| Fixed view | Floating view |
|---|---|
|  |  |
### Dark
| Fixed view | Floating view |
|---|---|
|  |  |
## 🧭 How it works
<p align="center">
<img src="https://raw.githubusercontent.com/Ezra-Y/codex-goal-progress/main/docs/assets/codex-goal-progress-architecture.png" alt="How Codex Goal Progress works">
</p>
- The current model updates checklist evidence through local MCP tools.
- Helper validates revisions and is the only state writer.
- Core derives objective and overall progress from the checklist.
- Renderer receives a display-only ViewModel.
- The source Plugin builds the Helper in Codex Plugin data; the prebuilt Release uses a self-contained Node SEA Helper.
Read the [architecture](https://github.com/Ezra-Y/codex-goal-progress/blob/main/docs/ARCHITECTURE.md),
[permissions](https://github.com/Ezra-Y/codex-goal-progress/blob/main/docs/PERMISSIONS.md), and
[support reference](https://github.com/Ezra-Y/codex-goal-progress/blob/main/docs/SUPPORT.md)
for details.
## 🔐 Privacy and permissions
Goal Progress uses:
- local files under Codex Plugin data or its application-support directory;
- a private local Unix socket;
- a loopback CDP connection to the verified Codex process;
- a background Helper registered through launchd;
- three Plugin Hooks.
See [PERMISSIONS.md](https://github.com/Ezra-Y/codex-goal-progress/blob/main/docs/PERMISSIONS.md)
for the exact scope and removal steps.
## License
[MIT](https://github.com/Ezra-Y/codex-goal-progress/blob/main/LICENSE)
For source installations, **Check for updates** queries the published GitHub release. **View update notes** opens its release notes; install the update through the Codex plugin marketplace. It does not silently switch to a prebuilt Helper.
To remove a source installation, ask Codex to uninstall Goal Progress. The `goal_progress_uninstall` tool removes this source plugin, its Helper and its progress data. It keeps native Goals, other plugins and the shared marketplace. The first response reports that removal has started; the final result is recorded in `CODEX_HOME/logs/goal-progress-uninstall.log`.
© Codex Goal Progress Contributors · MIT · hashgraph-online/awesome-codex-plugins