codex-goal-progress — Claude Code hook: goal progress bar and token usage
codex-goal-progress is a Claude Code hook that tracks Codex Goals with checklist progress and token usage. It shows goal status in the interface.
MIT ★ 1,596 updated 2026-10-29
.claude/settings.jsonWhat codex-goal-progress does
This hook puts a native progress bar on Codex Goals. The bar moves as checklist items get done, and token spend sits next to it. Apple Silicon Macs only.
It listens on PreToolUse, PostToolUse, and SessionStart. At session start, run-bootstrap.sh restores active goal sessions, injects runtime identity, and watches lifecycle signals. PostToolUse updates for update_goal run async with a 2-second timeout and 64-token context limit.
Setup goes into .claude/settings.json. On Intel Macs or other platforms the bar will not run, because it targets Apple Silicon directly.
What it helps with
- render goal progress as a checklist inside Claude Code
- show token spend per goal
- restore active goal sessions after a restart
- refresh progress after each goal update
Example prompts for the agent
- Activate goal_progress_activate and show its checklist
- Update the goal after I finish a checklist item
- Restore my active goal sessions when the session starts
How to install codex-goal-progress
Manually: put the files in place
.claude/settings.jsonThe hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json
Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command
Questions about codex-goal-progress
How do I install codex-goal-progress in Claude Code?
Add the hook config to .claude/settings.json. The hook picks it up on the next session start.
What does codex-goal-progress do?
It draws a progress bar for Codex Goals, based on checklist completion, with token usage shown alongside.
Why does it only run on Apple Silicon?
The native progress bar targets Apple Silicon Macs. Intel Macs and other platforms will not run it.
Source text
hooks.json · MIT
Hooks bundle shipped with the codex-goal-progress plugin for Claude Code.
A native progress bar for Codex Goals with checklist-based progress and token usage on Apple Silicon Macs.
Triggers on: PreToolUse, PostToolUse, SessionStart.
```json
{
"description": "Restore active Goal Progress sessions, inject runtime identity, and observe bounded lifecycle signals.",
"hooks": {
"SessionStart": [
{
"matcher": "^(?:startup|resume|compact)$",
"hooks": [
{
"type": "command",
"command": "/bin/sh \"$PLUGIN_ROOT/runtime/run-bootstrap.sh\" hook",
"timeout": 3,
"additionalContextLimit": 128
}
]
}
],
"PreToolUse": [
{
"matcher": "^(?:goal_progress_|.*[^A-Za-z0-9]goal_progress[^A-Za-z0-9]+goal_progress_)(?:activate|initialize|get|update|rescope|set_phase)$",
"hooks": [
{
"type": "command",
"command": "/bin/sh \"$PLUGIN_ROOT/runtime/run-bootstrap.sh\" hook",
"timeout": 1
}
]
}
],
"PostToolUse": [
{
"matcher": "^update_goal$",
"hooks": [
{
"type": "command",
"command": "/bin/sh \"$PLUGIN_ROOT/runtime/run-bootstrap.sh\" hook",
"timeout": 2,
"async": true,
"additionalContextLimit": 64
}
]
}
]
}
}
```
© Codex Goal Progress Contributors · MIT · hashgraph-online/awesome-codex-plugins