Understanding the OMX Runtime Overlay Contract in oh-my-codex

The oh-my-codex framework uses HTML-style comment markers <!-- OMX:RUNTIME:START --> and <!-- OMX:RUNTIME:END --> to define bounded injection points for temporary, session-specific data within immutable specification files without altering static policy text.

The OMX runtime overlay contract provides a migration-safe mechanism for injecting transient session context into the immutable core specifications of the oh-my-codex repository. According to the source code in Yeachan-Heo/oh-my-codex, these markers appear in the root AGENTS.md file and the guidance schema to create stable boundaries for runtime modifications that sub-agents can consume during active sessions.

What Is the OMX Runtime Overlay Contract?

The contract is expressed by a pair of HTML-style comment markers that bound a mutable injection region:

<!-- OMX:RUNTIME:START -->
<!-- OMX:RUNTIME:END -->

In AGENTS.md (the canonical operating contract), these markers are documented at line 27【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/AGENTS.md#L27】. The same contract appears under "Marker contracts" in docs/guidance-schema.md at line 43【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/docs/guidance-schema.md#L43】. These markers form part of the Global Compatibility Contracts that tooling across the ecosystem relies upon for parse-replace operations.

Why Runtime Overlays Enable Migration-Safe Extensions

Runtime overlays solve three critical problems in specification management:

• Additive extension – Overlay content is added between markers without altering the original static wording, ensuring future repository versions parse the file unchanged.
• Session-scoped context – When a Codex session starts, the engine injects temporary blocks containing current mode, active shortcuts, or per-run configuration that sub-agents (explore, planner, executor) consume as runtime state rather than static policy.
• Stable contract – Because other tooling (e.g., team-worker overlay parsers) searches for these exact comment strings, the markers must remain immutable across releases to prevent breaking integrations.

The Three-Phase Overlay Lifecycle

The runtime overlay operates through a strict lifecycle defined in the oh-my-codex source:

Apply Phase

At session initialization, the engine reads AGENTS.md, locates the <!-- OMX:RUNTIME:START --> marker, and inserts a generated content block ending at <!-- OMX:RUNTIME:END -->. This block typically includes session metadata such as timestamps, active modes, or temporary configuration overrides.

Consume Phase

Sub-agents read the file and treat any content inside the markers as runtime state rather than immutable policy. This allows dynamic behavior modification without changing the underlying specification text that version control tracks.

Strip Phase

When the session terminates, the overlay block is removed, restoring the file to its pristine state. This guarantees that source control never contains transient session data, maintaining clean diffs and audit trails.

Programmatically Manipulating Runtime Overlays

Because the overlay is bounded by explicit markers, tools can safely parse-replace the inner region without risking accidental modification of surrounding documentation.

Injecting a Runtime Block with Python

The following Python script demonstrates how to inject or replace a runtime overlay in AGENTS.md:

import pathlib, re

AGENTS_PATH = pathlib.Path('AGENTS.md')
START = '<!-- OMX:RUNTIME:START -->'
END   = '<!-- OMX:RUNTIME:END -->'

def inject_runtime(content: str) -> str:
    runtime_block = (
        f"{START}\n"
        "## Session Context\n"

        "- Mode: **explore**\n"
        "- Started at: 2026‑04‑03T12:34:56Z\n"
        f"{END}"
    )
    # Replace any existing overlay (optional)

    pattern = re.compile(rf'{re.escape(START)}.*?{re.escape(END)}', re.DOTALL)
    return pattern.sub(runtime_block, AGENTS_PATH.read_text())

AGENTS_PATH.write_text(inject_runtime(AGENTS_PATH.read_text()))

This script looks for the exact marker strings and swaps the inner section with a freshly generated runtime context.

Extracting Overlay Data with Bash

Use awk to isolate the current runtime content for diagnostics:

awk '
  /<!-- OMX:RUNTIME:START -->/ { in=1; print; next }
  /<!-- OMX:RUNTIME:END -->/   { in=0; print; next }
  in { print }
' AGENTS.md

This prints only the lines between the two markers, useful for feeding runtime data to other agents or debugging session state.

Removing Overlays After Sessions with Node.js

To clean up transient data after a session ends:

const fs = require('fs');
const path = 'AGENTS.md';
let txt = fs.readFileSync(path, 'utf8');

const start = '<!-- OMX:RUNTIME:START -->';
const end   = '<!-- OMX:RUNTIME:END -->';

txt = txt.replace(
  new RegExp(`${start}[\\s\\S]*?${end}`, 'g'),
  `${start}\n${end}`   // empty block or placeholder
);

fs.writeFileSync(path, txt);

The empty block between markers signals that no runtime context is currently active.

Source Files Defining the Contract

Three critical files in the Yeachan-Heo/oh-my-codex repository establish and enforce the OMX runtime overlay contract:

• AGENTS.md (line 27) – The root operating contract where markers are defined and where runtime content is injected during active sessions.
• docs/guidance-schema.md (line 43) – Contains the Global Compatibility Contracts that formalize the marker syntax for all surfaces and tooling.
• templates/AGENTS.md (line 26) – The template version of the root contract; includes the overlay markers as a reference for generation pipelines.

Summary

• The OMX runtime overlay contract uses <!-- OMX:RUNTIME:START --> and <!-- OMX:RUNTIME:END --> markers to bound temporary session data.
• Markers appear in AGENTS.md (line 27) and docs/guidance-schema.md (line 43) as part of the Global Compatibility Contracts.
• The overlay lifecycle consists of Apply (inject), Consume (read by sub-agents), and Strip (remove after session) phases.
• HTML comment markers ensure migration-safe, additive extensions that preserve static specification integrity.
• Tools can programmatically manipulate overlays using regex or line-based parsing in Python, Bash, or Node.js without altering surrounding content.

Frequently Asked Questions

What are the exact marker strings for the OMX runtime overlay contract?

The contract requires the literal HTML comment strings <!-- OMX:RUNTIME:START --> and <!-- OMX:RUNTIME:END -->. These markers are defined in AGENTS.md at line 27 and in docs/guidance-schema.md at line 43. Because other tooling searches for these exact strings, they must remain unchanged across all releases.

Why does oh-my-codex use HTML comments instead of YAML frontmatter for runtime data?

HTML comments provide additive, migration-safe extension capabilities. Unlike YAML frontmatter, which requires structural changes to the document header, comment markers allow the engine to parse-replace bounded regions without breaking markdown parsers or altering the visible rendered output. This approach keeps the static specification stable while permitting temporary session injections.

Which files contain the authoritative definition of the runtime overlay contract?

The contract is defined in three locations within the Yeachan-Heo/oh-my-codex repository: AGENTS.md (line 27) serves as the root operating contract; docs/guidance-schema.md (line 43) formalizes the contract under Global Compatibility Contracts; and templates/AGENTS.md (line 26) provides the template reference for generation pipelines.

How does the overlay system prevent transient data from polluting source control?

During the Strip phase of the overlay lifecycle, the engine removes all content between the <!-- OMX:RUNTIME:START --> and <!-- OMX:RUNTIME:END --> markers, restoring the file to its pristine state. This guarantees that git diffs only contain permanent specification changes, not temporary session context such as timestamps or active modes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}