Goal Ledger
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:
- Creates a fresh ledger under
.agent/runs/<goal-id>/ in the current project.
- Writes a contract file (
GOAL.md): objective, finishing criteria, escape hatch, parent goal.
- 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.
- 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.
- Updates the HTML at every meaningful checkpoint: validation runs, implementation milestones, blockers, spec-vs-reality conflicts, compaction prep, final hand-off.
The progress timeline is rendered directly from an inline progressEvents array inside the HTML file. There is no separate events.jsonl to keep in sync — the page is its own history. Open the file locally and you get the whole story at a glance.
Why one HTML file
Earlier versions of this skill used a sprawl of PROGRESS.md, HANDOFF.md, events.jsonl, and CODEBASE_STATUS.md. Agents got confused about which file was canonical. Humans got confused about which file to read. State drifted between them.
Goal Ledger collapses all of that into one self-contained HTML file:
- Top is a
Resume Here block: status, current phase, blockers, next exact action, last validation, protected paths. Built so the next agent (or human) can resume in under a minute.
- Middle is
Decisions Outside The Spec, Changes And Tradeoffs, Validation, Evidence. The execution record.
- Bottom is
Progress Timeline. Rendered from an inline events array, no external file dependencies, no fetches against sibling files. Opens cleanly even when you double-click the HTML straight out of the file browser.
The HTML is the contract with the next agent. GOAL.md is the contract with the current agent. That's the whole system.
What problem this actually solves
You ask Codex or Claude Code to do something multi-hour or multi-day. Halfway through it compacts, gets interrupted, or hands off to a new session. Without a ledger, the new agent picks up with vibes and a stale objective.
With this skill in /goal mode, the active goal text itself includes the ledger path. Compaction can drop the conversation history and the next agent still knows:
- where to read state
- what was already validated
- what's actively in progress
- what's blocked and why
- which paths are user-owned and out of bounds
- what the next exact action is
The skill is the difference between an agent that resumes work and an agent that re-explores the codebase.
Install
Claude Code
Add the marketplace, then install the plugin:
/plugin marketplace add kingbootoshi/goal-ledger
/plugin install goal-ledger
Restart Claude Code if the skill does not appear immediately. After install, the skill triggers automatically on goal-mode language, or you can invoke it explicitly.
OpenAI Codex CLI
Codex looks for skills at ~/.codex/skills/<name>/. Drop the skill directory there:
git clone https://github.com/kingbootoshi/goal-ledger.git ~/.goal-ledger
mkdir -p ~/.codex/skills
ln -sfn ~/.goal-ledger/plugins/goal-ledger/skills/goal ~/.codex/skills/goal
Restart Codex if needed. Invoke explicitly with $goal or describe the work in goal-mode language and Codex will auto-select it.
Codex also ships a native /goal lifecycle (/goal, /goal pause, /goal resume, /goal clear). Enable it once in ~/.codex/config.toml:
[features]
goals = true
When the native goal exists, the skill couples the ledger path directly into the runtime goal objective so compaction-safe continuation works end to end.
One canonical location for both agents
If you prefer a single source of truth, keep the skill in one place and symlink it into both agents:
