Maelstone

Maelstone is a small shell wrapper around codex exec for walking a markdown plan through the storm, one milestone at a time.

The installed command is maelstone; the work begins with grind.

YOLO mode is a required mindset here, not a decorative option. Maelstone sends Codex into the dark with --yolo; the bargain is that every milestone must come back committed, accounted for, and with the worktree clean.

It keeps the ritual plain:

• reads a markdown plan
• asks Codex which milestone is next
• prints Milestone x of y
• runs Codex on one milestone
• expects Codex to update that milestone status
• expects Codex to commit the completed milestone
• stops when the worktree gets dirty or progress turns ambiguous

Install

From the repository root:

ln -sf "$PWD/bin/maelstone" "$HOME/.local/bin/maelstone"

Make sure ~/.local/bin is on your PATH.

Runtime requirements:

• codex
• jq

Usage

maelstone grind --plan docs/plans/my-plan.md --effort high

Run only one milestone:

maelstone grind --plan docs/plans/my-plan.md --max 1

Use Codex's fast service tier:

maelstone grind --plan docs/plans/my-plan.md --fast

Keep macOS awake while the loop runs:

maelstone grind --plan docs/plans/my-plan.md --caffeinate

Plan Format

The parser expects milestone headings and status labels like this:

## Milestone 1: Add the runtime bridge

Status: Not started

Supported status values:

• Status: Not started
• Status: In progress
• Status: Done

maelstone grind prefers an existing Status: In progress milestone. Otherwise it chooses the first milestone whose status is not Status: Done.

See examples/plan.md.

Safety Model

maelstone grind requires a clean git worktree before it starts. It does not try to tame the whole storm at once; after every completed milestone it verifies that:

• Codex reported exactly one final status
• a new commit was created
• no uncommitted changes remain

The milestone lookup uses low reasoning effort. Main milestone work runs Codex in unattended --yolo mode and streams codex exec --json events through jq to print concise progress updates while the machinery churns.

Development

Run the project checks:

scripts/check

This project has no package manager dependency.