Skip to content

sleepficus/hearthside-continuity

v0.1.0MIT

A local desk note that helps Codex resume the right job after context compaction.

GitHubOpen Website

Hearthside Continuity

Hearthside leaves Codex a small local desk note across context compaction: what the task is, what finished, what is still running, what must not be repeated, and the exact next action.

It is intentionally not a transcript archive or an attempt to preserve hidden reasoning. The hook records a session-specific pointer, verifies its hash, and injects only a bounded recovery reminder plus documented fields from an optional ACTIVE-CHECKPOINT.json.

What is included

  • PreCompact, PostCompact, and SessionStart(compact) lifecycle hooks;
  • a stronger operational compact prompt;
  • a fictional checkpoint example;
  • focused privacy, isolation, tamper, and configuration tests;
  • merge-safe prompt configuration, uninstall, and rollback commands.

Supported environment

The initial release was verified with Codex CLI 0.149.1 inside Codex Desktop on macOS on September 24, 2026. The hook uses Unix file locking and has not been verified on Windows, cloud tasks, Claude, Devin, OpenCode, or other computers.

Installation

The repository is designed to be installed as a Codex plugin. The source is published at https://github.com/sleepficus/hearthside-continuity under the MIT License.

codex plugin marketplace add <checkout>
codex plugin add hearthside-continuity@hearthside
python3 <checkout>/scripts/configure_compact_prompt.py install

Then restart Codex. Open /hooks, inspect all three Hearthside definitions, and trust them. Plugin hooks are not trusted automatically. Test manual /compact in a disposable task before relying on automatic recovery.

Tasks that were already open when the plugin was installed may need a restart or a fresh task before the hooks load.

Create a desk note

Hearthside can resume only the state that the compact handoff or checkpoint actually contains. Copy the fictional example to the current session's plugin data directory as ACTIVE-CHECKPOINT.json, then keep these fields current:

{
  "objective": "Ship the accepted dashboard",
  "completed": ["Targeted tests passed"],
  "in_progress": "One existing browser review",
  "next_action": "Read the review receipt",
  "decisions": ["Do not relaunch the reviewer"]
}

The allowed fields are objective, phase, completed, in_progress, next_action, decisions, files, receipts, blockers, and stop_condition. Checkpoints larger than 32 KiB, invalid JSON, and content that looks like a credential are withheld.

Verify from source

PYTHONDONTWRITEBYTECODE=1 python3 -m pytest -q
python3 /path/to/plugin-creator/scripts/validate_plugin.py .

The tests use temporary data and configuration roots. They do not touch your installed Codex settings.

Uninstall

Remove only the compact-prompt setting Hearthside installed, then remove the plugin through Codex:

python3 <checkout>/scripts/configure_compact_prompt.py uninstall
codex plugin remove hearthside-continuity@hearthside

Restart Codex afterward. Local continuity data is deliberately not deleted by the uninstaller; inspect and remove it separately if you no longer need it.

Roll back configuration

Every configuration change creates a timestamped backup. Inspect the path printed during installation, preview the rollback, then confirm it explicitly:

python3 <checkout>/scripts/configure_compact_prompt.py rollback --dry-run
python3 <checkout>/scripts/configure_compact_prompt.py rollback --yes

Rollback replaces config.toml with Hearthside's verified installation backup and first saves the current file again. It refuses missing, changed, or out-of-scope backups.

What Hearthside does not solve

Hearthside does not fix bad plans, broken code, provider outages, permission prompts, stale checkpoints, or incorrect external state. It does not guarantee lower usage, faster work, or perfect memory. Those outcomes require separate measurement.

License

MIT. Security and local-data details are in SECURITY.md.