kingbootoshi/goal-ledger
67 stars · Last commit 2026-05-19
Single-file agent goal ledger for Claude Code and Codex CLI - pairs with /goal mode
README preview
# Goal Ledger <p align="center"> <img src="plugins/goal-ledger/skills/goal/assets/hero.jpeg" alt="Vibe Bot crossing the finish line with arms raised, scoreboard of completed objectives behind him" width="720"> </p> A single-file agent goal ledger that pairs with `/goal` mode in **Claude Code** and **OpenAI Codex CLI**. `/goal` mode is great at keeping an agent pointed at one durable objective. It is not great at remembering what already happened. The Goal Ledger fills that gap: every checkpoint, decision, blocker, and validation gets written into one human-readable `implementation-notes.html` file that opens in any browser and survives compaction, hand-offs, and chained goals. The same skill works in both agents. Same `SKILL.md`, same script, same on-disk layout. Drop it into `~/.claude/skills/goal/` and `~/.codex/skills/goal/` and both agents pick it up natively. ## What it does When the agent says `$goal`, `/goal mode`, `start a goal`, or any equivalent goal-mode language, the skill: 1. Creates a fresh ledger under `.agent/runs/<goal-id>/` in the current project. 2. Writes a contract file (`GOAL.md`): objective, finishing criteria, escape hatch, parent goal. 3. Writes a single canonical state file (`implementation-notes.html`): a self-contained HTML page with a `Resume Here` block at the top and an embedded progress timeline. 4. Couples to the runtime goal: when the user is in Codex `/goal` mode, the absolute ledger path is dropped into the goal objective so the next agent on the thread knows exactly where to read and write.