{"id":"566d4a8e-a659-42eb-9308-58056c92a1ea","slug":"codex-agents-compact-reload","kind":"skill","name":"codex-agents-compact-reload","summary":"A dependency-free bootloader that reloads project AGENTS.md after context compaction across AI agent harnesses—automatically, visibly, and fail-closed.","owner":"paragon-ux","repoUrl":"https://github.com/paragon-ux/codex-agents-compact-reload","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-30T08:31:56.000Z","addedAt":"2026-10-21T21:49:03.980Z","logoUrl":"https://avatars.githubusercontent.com/u/263126673?u=3d17e758fe14aecd115f87ffeb08a8bcf0be901f&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","developer-tools"],"tags":["ai-agents","codex","codex-cli","context-compaction","continuity","developer-tools","hooks","nodejs"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T12:08:10.218Z","sample":false,"url":"https://conduits.dev/tools/codex-agents-compact-reload","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"assets/compact-reload-icon.png\" width=\"180\" alt=\"A document wrapped by a continuous reload ribbon\">\n</p>\n\n<h1 align=\"center\">AGENTS.md Compact Reload</h1>\n\n<p align=\"center\"><strong>Compaction happens. Your project rules come back.</strong></p>\n\n<p align=\"center\">\n  <a href=\"../../actions/workflows/ci.yml\"><img src=\"https://github.com/paragon-ux/codex-agents-compact-reload/actions/workflows/ci.yml/badge.svg\" alt=\"CI status\"></a>\n</p>\n\nKeep project instructions present at the moment they matter most: immediately after an agent harness compacts a long-running conversation.\n\nThis small, dependency-free bootloader reloads the registered Git root's `AGENTS.md`, computes its SHA-256, and supplies the exact UTF-8 text to the immediate post-compaction continuation across AI agent harnesses. It does not inspect transcripts, retain prompts, or write runtime state into the project.\n\n---\n\n## Table of Contents\n\n- [Why Use It?](#why-use-it)\n- [Cross-Repository Ecosystem](#cross-repository-ecosystem)\n- [Standardized 3-Tier Harness Model](#standardized-3-tier-harness-model)\n- [Quick Start](#quick-start)\n- [Supported Harnesses](#supported-harnesses)\n- [Division of Labor with Waymark](#division-of-labor-with-waymark)\n- [Multi-Project Registration](#multi-project-registration)\n- [Privacy and Trust Boundary](#privacy-and-trust-boundary)\n- [Verification Evidence](#verification-evidence)\n- [Repository Directory](#repository-directory)\n- [Documentation & Provenance](#documentation--provenance)\n\n---\n\n## Cross-Repository Ecosystem\n\nThis repository is part of an integrated, local-first multi-agent execution suite:\n\n### Internal Suite Repositories\n\n| Repository | Role & Responsibility | Core Invariant |\n| :--- | :--- | :--- |\n| **[`AGENTS.md Compact Reload`](https://github.com/paragon-ux/codex-agents-compact-reload)** | Static project governance & compaction survival. | Re-injects verified `AGENTS.md` and SHA-256 hash on context compaction. |\n| **[`Waymark`](https://github.com/paragon-ux/waymark)** | In-flight continuity ledger & AST discovery MCP. | Preserves verified code hops (`.waymark/`) across compactions (<216 tokens). |\n\n#### When to Use What\n\n- **Use [`AGENTS.md Compact Reload`](https://github.com/paragon-ux/codex-agents-compact-reload)** when an agent harness compacts context and you must deterministically guarantee that static project instructions, safety guardrails, and coding conventions are restored into the active session without spending agent recovery turns.\n- **Use [`Waymark`](https://github.com/paragon-ux/waymark)** when an agent is deep in a multi-file investigation or code trace and needs to preserve dynamic, verified line spans and causal breadcrumbs across compactions without repetitive, token-expensive codebase re-reads.\n### External Specifications\n\n| Specification | Canonical Reference | Usage in Suite |\n| :--- | :--- | :--- |\n| **Model Context Protocol (MCP)** | [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification) | Standardized JSON-RPC 2.0 stdio tool interface used across Waymark. |\n| **Tree-sitter WASM** | [Tree-sitter](https://github.com/tree-sitter/tree-sitter) | Polyglot AST grammars compiled to WebAssembly for zero-dependency symbol discovery. |\n| **Node.js Core Runtime** | [Node.js](https://github.com/nodejs/node) (v22+ LTS) | Native `node:sqlite`, `node:child_process`, `node:crypto`, `node:fs` (0 runtime npm dependencies). |\n| **Capn Hook / Memory Protocol** | [Capn Hook](https://github.com/cyrusNuevoDia/capn-hook) | Finalized episodic memory storage, distinct from Waymark's active in-flight trajectory ledger. |\n\n---\n\n## Why Use It?\n\n| Approach | Context and cache cost | Recovery control |\n|---|---|---|\n| No hook | No added context | Relies on the retained instruction snapshot; no explicit reload or source hash |\n| Manual prompt | Adds a turn and usually repeats recovery context | Depends on a person noticing compaction and prompting consistently |\n| Ralph-style loop | Reconstructs state for another iteration; changing prefixes can reduce cache reuse | Useful for repeated autonomous runs, but adds another startup and restoration surface |\n| **This hook** | Adds one bounded, deterministic instruction artifact to the existing compact continuation | Automatically reloads the registered root file and exposes its exact source and hash |\n\nThe hook is designed to preserve prompt-cache-friendly stable context, avoid a separate recovery turn, and reduce stale-phase or wrong-workspace mistakes. See [Rationale](Rationale.MD) for the detailed comparison and limits.\n\n---\n\n## Standardized 3-Tier Harness Model\n\nAgent harnesses provide varying levels of context-injection capability, categorized into three distinct support tiers:\n\n| Support Tier | Mechanism | Delivery Guarantee | Target Harnesses |\n| :--- | :--- | :--- | :--- |\n| **Tier 1: Active Lifecycle Hook** | Out-of-context process execution on compaction boundary. | **100% deterministic.** Instructions prepended before model turn; zero tokens spent remembering to recover. | **OpenAI Codex** (`SessionStart`), **Google Antigravity** (`PreInvocation.injectSteps`), **Claude Code** (`post_compact`), **Hermes Agent** (`pre_llm_call` shell hook). |\n| **Tier 2: MCP Ingestion** | In-band Model Context Protocol primitives. | **High reliability.** Standardized pull via resources/prompts. | **Claude Code**, **Cursor Composer**, **Windsurf**, **Cline**, **Hermes Agent** (`mcp_servers`). |\n| **Tier 3: Persistent Directives** | Sticky system instruction files (`CLAUDE.md`, `.cursor/rules/*.mdc`). | **Best-effort.** Instructs model to reload rules as step 1 when prior turn history is rolled. | **Cursor**, **Claude Code**, **Antigravity**, **Hermes Agent** (`AGENTS.md` context-file loading). |\n\nSee [Support Tiers Guide](docs/SUPPORT-TIERS.md) for full technical schemas.\n\n---\n\n## Quick Start\n\n### Requirements:\n\n- Node.js 20 or newer.\n- Git on `PATH`.\n- A nonempty UTF-8 `AGENTS.md` at the registered Git root.\n- A supported AI coding agent harness (OpenAI Codex, Google Antigravity, Claude Code, Cursor, Hermes Agent, etc.).\n\n### Verify the checkout:\n\n```sh\nnpm run verify\n```\n\n### Preview installation (Codex):\n\n```sh\nnode scripts/install.mjs --project my-project=<PROJECT_ROOT> --codex-version <CODEX_VERSION> --dry-run\n```\n\n### Install for that project (Codex):\n\n```sh\nnode scripts/install.mjs --project my-project=<PROJECT_ROOT> --codex-version <CODEX_VERSION>\n```\n\n### Preview installation (Hermes Agent):\n\n```sh\nnode scripts/install.mjs --target hermes --project my-project=<PROJECT_ROOT> --dry-run\n```\n\n### Install for that project (Hermes Agent):\n\n```sh\nnode scripts/install.mjs --target hermes --project my-project=<PROJECT_ROOT>\n```\n\n---\n\n## Supported Harnesses\n\nDedicated setup guides and recipes are located in [`harnesses/`](harnesses/):\n\n- **[OpenAI Codex (`harnesses/codex/`)](harnesses/codex/README.md):** Deep dive on why `SessionStart` (not `PostCompact`), minimum version 0.145.0, Windows NTFS quote-free short path wrapper, and companion skills (`$codex-compact-reload-setup`, `$codex-compact-reload-cleanup`).\n- **[Google Antigravity & Gemini (`harnesses/agy/`)](harnesses/agy/README.md):** Out-of-context hook protocol via `PreInvocation.injectSteps` and workspace instruction rules (`<RULE>`).\n- **[Claude Code (`harnesses/cc/`)](harnesses/cc/README.md):** Configuration for `hooks.post_compact` in `.claude/config.json` and persistent `CLAUDE.md` instructions.\n- **[Cursor (`harnesses/cursor/`)](harnesses/cursor/README.md):** Setup for `.cursor/rules/agents-reload.mdc` persistent rule.\n- **[Hermes Agent (`harnesses/hermes/`)](harnesses/hermes/README.md):** `pre_llm_call` shell hook in `~/.hermes/config.yaml` with a compaction-marker gate, first-use consent, and native MCP pairing for the Waymark ledger.\n\n---\n\n## Division of Labor with Waymark\n\nPost-compaction continuity operates across two complementary bootloaders:\n\n```text\n               Context Compaction Occurs\n                          │\n          ┌───────────────┴───────────────┐\n          ▼                               ▼\n [ AGENTS.md Compact Reload ]      [ waymark-compact-hook ]\n  Target: Root `AGENTS.md`          Target: `.waymark/active.json`\n  Role: Static behavioral rules     Role: Dynamic verified breadcrumbs\n  Output: Project authority & hash  Output: Hops & relocated line spans\n          │                               │\n          └───────────────┬───────────────┘\n                          ▼\n        Immediate Post-Compaction Continuation\n        (Full rules + Exact code breadcrumb trail)\n```\n\n1. **Static Project Governance ([AGENTS.md Compact Reload](https://github.com/paragon-ux/codex-agents-compact-reload)):** Reloads the root `AGENTS.md` and validates its SHA-256 hash. Ensures the agent never forgets its behavioral boundaries, test requirements, or safety invariants.\n2. **Dynamic In-Flight Trajectory ([Waymark](https://github.com/paragon-ux/waymark)):** Reloads the active `.waymark/` journal, verifies Git line anchors, detects relocated spans (`MOVED`), and injects the verified breadcrumb trail (<216 tokens).\n\n---\n\n## Multi-Project Registration\n\nRegister several projects in one installation:\n\n```sh\nnode scripts/install.mjs \\\n  --codex-version <CODEX_VERSION> \\\n  --project frontend=<FRONTEND_ROOT> \\\n  --project backend=<BACKEND_ROOT>\n```\n\nOn PowerShell, place the command on one line or use PowerShell's normal continuation syntax.\n\n---\n\n## Privacy and Trust Boundary\n\nAt runtime the hook reads only:\n\n- the hook JSON payload supplied on standard input;\n- its own `projects.json` registration file;\n- Git's observed repository root; and\n- the registered root's `AGENTS.md`.\n\nIt does not read agent session files, transcripts, prompts, tool results, environment-variable values, credentials, or task artifacts. It writes no runtime handoff or history files. See [Security](docs/SECURITY.md) for the complete boundary.\n\n`AGENTS.md` remains an instruction source, not evidence that work occurred. Claims about patches, tests, Git state, or external actions still require direct verification.\n\n---\n\n## Verification Evidence\n\nThe current automated test suite covers:\n\n- multi-harness payload auto-detection (Codex, Antigravity, Hermes, Markdown, JSON);\n- Hermes `pre_llm_call` compaction gating (injects on summary/continuation/fallback/merged markers with no live user turn; no-op on live user messages and ordinary turns);\n- Hermes installer line-surgery merge (comment/section preservation, idempotence, CRLF, fail-closed on unsupported shapes);\n- Hermes uninstaller scoped entry removal (foreign-entry preservation, emptied-key removal, backup reporting);\n- exact content and SHA-256 injection;\n- nested working directories inside Git roots;\n- unregistered-project no-op behavior;\n- stale unrelated registration isolation and invalid selected-registration failure;\n- event filtering (ignoring non-compact SessionStart and unrelated events);\n- missing, empty, oversized, and invalid UTF-8 fail-closed behaviors;\n- installer preservation of unrelated hooks;\n- repeat-install idempotence;\n- installer dry-run non-mutation;\n- partial deregistration; and\n- complete, recoverable uninstall without unrelated-hook loss.\n\nRun the exact suite with:\n\n```sh\nnpm run verify\n```\n\n---\n\n## Repository Directory\n\n```text\ncodex-agents-compact-reload/\n├── .agents/skills/            # Companion skills for agent environments\n│   ├── codex-compact-reload-setup/    # Guided setup & host acceptance\n│   └── codex-compact-reload-cleanup/  # Scoped uninstaller skill\n├── assets/                    # Project iconography\n├── docs/                      # Technical architecture and protocols\n│   ├── ARCHITECTURE.md        # Lifecycle flow and security boundary\n│   ├── HOST-ACCEPTANCE.md     # Real-host manual & automatic compaction test\n│   ├── PUBLICATION.md         # Release history and provenance\n│   ├── SECURITY.md            # Threat model and privacy constraints\n│   ├── SUPPORT-TIERS.md       # Standardized 3-tier harness classification\n│   └── releases/              # Historical release notes (v0.1.0 – v0.2.0)\n├── harnesses/                 # Harness-specific recipes and deep-dives\n│   ├── README.md              # Harness directory index and tier matrix\n│   ├── codex/                 # OpenAI Codex integration details\n│   ├── cc/                    # Claude Code integration details\n│   ├── agy/                   # Google Antigravity integration details\n│   ├── cursor/                # Cursor & Cursor Composer integration details\n│   └── hermes/                # Hermes Agent integration details\n├── scripts/                   # Management scripts\n│   ├── install.mjs            # Idempotent harness hook installer (Codex + Hermes)\n│   └── uninstall.mjs          # Scoped uninstaller and cleaner\n├── src/                       # Core runtime\n│   └── reload-agents.mjs      # Universal multi-harness compact bootloader\n└── test/                      # Node.js native test suite (24 automated tests)\n    ├── install.test.mjs       # Installer idempotence and preservation tests\n    ├── reload-agents.test.mjs # Multi-harness injection & fail-closed tests\n    ├── uninstall.test.mjs     # Uninstaller tests\n    └── hermes.test.mjs        # Hermes shell-hook, installer, and uninstaller tests\n```\n\n---\n\n## Documentation & Provenance\n\n- **[Support Tiers Guide](docs/SUPPORT-TIERS.md)**: 3-tier classification across Codex, Antigravity, Claude Code, Cursor, and Hermes Agent.\n- **[Harness Integration Recipes](harnesses/README.md)**: Detailed recipes for Codex, Claude Code, Antigravity, Cursor, and Hermes Agent.\n- **[Architecture Deep-Dive](docs/ARCHITECTURE.md)**: Runtime lifecycle, security model, and failure semantics.\n- **[Design Rationale](Rationale.MD)**: Why compact reload instead of manual prompting or loops.\n- **[Host Acceptance Protocol](docs/HOST-ACCEPTANCE.md)**: Empirical compaction acceptance test protocol.\n- **[Security & Privacy Boundary](docs/SECURITY.md)**: Trust boundaries and read/write constraints.\n- **[Waymark In-Flight Continuity](https://github.com/paragon-ux/waymark)**: Companion in-flight continuity ledger for verified code breadcrumbs.\n\n---\n\n## License\n\n[MIT](LICENSE). Copyright (c) 2026 the codex-agents-compact-reload contributors.\n"}