claude-goal

A Codex-style /goal command for Claude Code.

It gives Claude Code a persistent local goal state, Codex-inspired continuation instructions, pause/resume/clear/status controls, completion-audit guardrails, and a Stop hook that keeps Claude working while a goal is active.

Install

git clone https://github.com/jthack/claude-goal.git
cd claude-goal
./install.sh

This installs:

• ~/.claude/skills/goal as a symlink to this repo's goal/ directory
• a user-level Claude Code Stop hook in ~/.claude/settings.json

The goal/ directory is the Claude skill package. It contains SKILL.md, scripts/claude_goal.py, and reference notes.

State is stored at:

~/.claude/goal/goals.sqlite

Usage

/goal find and fix the flaky auth tests
/goal --tokens 250K do deep research and build the full prototype
/goal
/goal status
/goal pause
/goal resume
/goal clear

When a goal is active, the command returns a continuation prompt that wraps the goal text in <objective> and requires a completion audit before marking the goal complete.

Notes

Claude Code custom skills do not currently expose reliable live per-turn token usage to markdown commands. Token budgets are therefore stored and displayed as soft budgets. Elapsed-time tracking is local and persistent.

The Stop hook blocks Claude from stopping while the current goal is active. It stops blocking when you run /goal pause, /goal clear, or /goal complete.

By default, the runaway guard allows up to 500 Stop-hook continuations for a single active goal. That high default is intentional: /goal is meant for long-running work where Claude may need many turns to finish. If you want a stricter cap, set CLAUDE_GOAL_MAX_STOP_CONTINUES before launching Claude Code:

export CLAUDE_GOAL_MAX_STOP_CONTINUES=50

Test

python3 -m pytest tests