kingbootoshi/goal-ledger

Goal Ledger is a small skill for two AI coding tools, Claude Code and OpenAI's Codex CLI. Both tools have a 'goal' mode that keeps the agent pointed at one longer-running objective, but the author found that goal mode is poor at remembering what already happened. This skill fills that gap by writing the running state of the work into a single HTML file that opens in any browser and survives the events that usually wipe an agent's memory, such as conversation compaction or a hand-off to a new session. When the user types a phrase like '$goal' or 'start a goal', the skill creates a fresh folder under '.agent/runs/<goal-id>/' inside the current project. It writes two files there. The first is GOAL.md, a short contract with the objective, the finishing criteria, an escape hatch, and a parent goal if there is one. The second is implementation-notes.html, a self-contained page that starts with a 'Resume Here' block at the top, lists decisions, tradeoffs, validation runs, and evidence in the middle, and shows a progress timeline at the bottom. The timeline is built from a JavaScript array embedded in the same file, so the page does not need any sibling files to render. The author explains why everything collapsed into one file. Earlier versions used PROGRESS.md, HANDOFF.md, events.jsonl, and CODEBASE_STATUS.md side by side, and both the agents and the humans got confused about which file was the real source of truth. With a single HTML page, the contract for the next agent and the readable state for the human are the same artifact. The skill also couples to Codex's built-in goal lifecycle when that lifecycle is turned on in the user's config, dropping the absolute path of the ledger into the goal objective so the next agent on the thread always knows where to read and write. Installation is short. Claude Code users add a plugin marketplace and install the plugin from a slash command. Codex users clone the repo and symlink the skill folder into '~/.codex/skills/goal/'. The README also shows a one-clone-two-symlinks pattern for keeping the skill in a single location and pointing both agents at it, so a 'git pull' updates both copies at once.