kingbootoshi/goal-ledger

Analysis updated 2026-06-24

★ 30PythonAudience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((goal-ledger))
    Inputs
      Goal command from user
      Codex goal lifecycle
    Outputs
      GOAL.md contract
      Implementation-notes HTML
      Progress timeline
    Use Cases
      Resume after compaction
      Hand off to new session
      Track decisions and evidence
    Tech Stack
      Python
      Claude Code
      Codex CLI
      Single-file HTML

mindmap root((goal-ledger)) Inputs Goal command from user Codex goal lifecycle Outputs GOAL.md contract Implementation-notes HTML Progress timeline Use Cases Resume after compaction Hand off to new session Track decisions and evidence Tech Stack Python Claude Code Codex CLI Single-file HTML

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Keep a Claude Code or Codex agent on task across conversation compaction

USE CASE 2

Hand off a multi-day refactor between two sessions with no memory loss

USE CASE 3

Open a single HTML page in a browser to see what an agent did so far

USE CASE 4

Share one ledger install between Claude Code and Codex via two symlinks

What is it built with?

PythonClaudeCodeCodexHTMLJavaScript

How does it compare?

	kingbootoshi/goal-ledger	ramkumarmn/hub_backend	rusty4444/gatekeeper-ha
Stars	30	30	30
Language	Python	Python	Python
Setup difficulty	easy	hard	moderate
Complexity	2/5	4/5	3/5
Audience	developer	developer	ops devops

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 5min

Codex setup needs cloning the repo and symlinking into ~/.codex/skills/goal/.

In plain English

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.

Copy-paste prompts

Prompt 1

Install goal-ledger as a Claude Code plugin and start a goal called migrate-auth from a slash command

Prompt 2

Set up the one-clone-two-symlinks layout so both Codex and Claude Code see the same goal-ledger install

Prompt 3

Open my latest .agent/runs ledger and summarise what the previous agent decided and what is left to do

Prompt 4

Write a parent and sub-goal pair using goal-ledger for a feature that has a backend and a frontend slice

Frequently asked questions

What is goal-ledger?

A Claude Code and Codex CLI skill that records a long-running goal in a single self-contained HTML file, so a new agent session can resume the work without losing context.

What language is goal-ledger written in?

Mainly Python. The stack also includes Python, ClaudeCode, Codex.

How hard is goal-ledger to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is goal-ledger for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.