Skip to main content
hook CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/settings.json
Open on GitHub

What 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.json

The 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

Similar hooks

All hooks for Agent setup: memory, context, orchestration →

From the same set391

The whole set →

Project sponsors

Companies that keep this analytics open