Codex Runway

Codex Runway is a local Alpha tool for long-running Codex work. Before a large or tightly coupled phase, it issues an advisory decision about whether that phase should begin in the current context window. If a context boundary still occurs, the project preserves a concise working state outside the repository so the task can resume from a verifiable point instead of reconstructing its course from fragments of conversation.

This is more than another remaining-token meter. The same 20,000 tokens might be enough for a cheap edit that is easy to repeat, yet inadequate for a release whose intermediate decisions would be expensive to recover. Runway therefore combines telemetry for one exact thread with an estimate for the entire next phase, its recovery cost, and the freshness of durable state.

The decision applies to a phase, not the whole task

A phase is a bounded, coherent unit that the agent intends to complete under one estimate and recovery model—for example, changing a parser and running its related tests, or carrying a release through final verification. Runway evaluates an explicit estimate for that unit and returns one of four decisions:

• go — the phase fits together with a reserve for a safe finish;
• checkpoint_first — the phase fits, but durable state must first be brought up to date and the preflight repeated;
• defer — this particular phase does not fit, so a smaller useful unit can be defined and assessed separately;
• unknown — the evidence is missing or contradictory, so expensive coupled work must not begin.

Assessment is deterministic: identical inputs produce the same result and reason codes. The base reserve is at least 8,192 tokens or 5% of the context window, then grows with recovery cost. The result also includes a signed estimate_margin_tokens: for go, it is the available tolerance for estimate growth; for defer, it is the approximate deficit. Runway does not invent a work estimate or replace the agent’s engineering judgment. It makes the assumptions and arithmetic inspectable.

Telemetry for one exact thread

get_context_usage reads a bounded tail of local Codex history for an explicitly supplied canonical UUID of the active thread. It returns counters and freshness metadata, never prompts, responses, filenames, secrets, raw records, or log excerpts. The result is the latest recorded request snapshot, not live process memory or a billing counter.

The tool deliberately does not select the newest log, infer a session from the working directory, or accept a fallback identifier. The exact UUID must come from trusted runtime context. If the window is unknown, history is truncated, no reliable post-compaction measurement exists yet, or the requested thread cannot be identified unambiguously, the response preserves that uncertainty. Runway neither reconstructs missing budgets from percentages nor treats observations of compaction as knowledge of a hidden threshold.

An event-driven workflow, without constant polling

The skill installed with the server defines the operating procedure. The agent scopes one whole candidate phase, checks checkpoint state, restores it when present, judges its semantic freshness, obtains fresh telemetry, and only then calls assess_runway. Reading the counters alone is not a completed preflight; the measurement must be assessed against a specific phase.

A successful decision acts as a lease on unchanged assumptions, not as a timer. Reassessment is required when the expected size grows, recovery becomes more costly, a tool produces unexpectedly large or unbounded output, the objective or scope changes materially, ownership moves to another agent or checkout, or compaction is observed. Open-ended repetitive work is admitted in bounded batches and reassessed as their budget is consumed, rather than after every minor action.

Checkpoints are event-driven too. A material finding, decision, completed mutation, ownership change, blocker, or next action immediately makes the stored state dirty. It must be written before the next context-growing call, delegation, or costly subphase; known material deltas cannot wait for a more convenient moment. Minor updates that are independently reconstructible may be coalesced while recovery remains easy.

After a real context boundary, the previous decision is no longer valid. The agent restores durable state, checks mutable claims against the repository and tools, fetches fresh telemetry, and assesses the next phase independently.

Private durable continuity

The checkpoint lives in Codex’s local data directory, not in the working tree. Its namespace combines the canonical checkout root with the exact thread UUID. Linked Git worktrees therefore keep separate state even when they share a common Git directory, and different conversations in one checkout cannot collide.

The format is intentionally concise and structured: objective, user constraints, completed work, material findings and decisions, change ownership, performed verification, blockers, exact next action, and the next candidate phase. Conversation history, full tool output, environment dumps, rollout records, and credentials are outside the contract. Restored text is treated as untrusted historical state: it cannot grant new authority or override current instructions.

The server chooses the storage path; the agent does not. Writes are size-bounded and protected with private filesystem modes, locking, symlink guards, and atomic replacement. Updates use a monotonic revision and compare-and-swap. On a conflict, the agent must reread and reconcile instead of overwriting newer state.

Five MCP tools

In v0.4.2, one local stdio server exposes exactly five tools:

• get_context_usage — reads a bounded context-usage snapshot for the exact thread;
• assess_runway — evaluates one agent-defined phase against explicit assumptions;
• checkpoint_status — resolves the checkout/thread namespace and inspects checkpoint state;
• checkpoint_read — returns the validated structured checkpoint;
• checkpoint_write — atomically creates or updates it using compare-and-swap.

The first four operations do not change state. checkpoint_write is the sole state-changing, non-idempotent operation. The JSON CLI provides assess and usage, while the pure assessment engine is also available through the Python API. Checkpoint transport is deliberately absent from the CLI: those operations remain in MCP, so there is no longer an intermediate JSON file or separate subprocess runner.

Installation and the trust boundary

The recommended installer deploys the MCP server and matching skill as one consistent unit. It runs without sudo, verifies the published wheel’s SHA-256, creates a versioned per-user environment, installs a hash-pinned binary dependency closure, performs package and MCP smoke checks, and transactionally updates only the package-owned configuration and skill. Unrelated settings are preserved, while ambiguous ownership, modified managed files, scope collisions, or a checksum mismatch cause a fail-closed stop.

A global installation is visible across the current user’s projects. A local installation is confined to one already trusted Git checkout and requires an explicit acknowledgement of that fact. The installer neither grants project trust nor modifies trust settings. The server runs with the invoking user’s filesystem permissions; MCP annotations describe behavior but do not provide authorization or multi-user isolation.

The bootstrap requires Python 3.13 or newer; the maintained and tested release matrix is 3.13–3.14. Its primary environment is local Codex with a stdio MCP client on Linux. Codex or the IDE may need to be restarted after installation so the current client reloads the server registration and skill.

How the project reached version 0.4.2

Version v0.3.0 introduced private checkpoints for continuation across context boundaries and began reporting actual compaction observations separately, without turning them into a guessed hidden threshold. In v0.4.0, persistence moved into the same MCP server: three checkpoint tools replaced the CLI commands, subprocess runner, and temporary JSON flow. The namespace changed to the “checkout + exact thread” pair, while atomic CAS updates, a signed estimate margin, and the event-driven lease model arrived. This transition intentionally does not migrate v0.3.0 checkpoints or provide a compatibility layer.

In v0.4.1, the continuity rule became stricter: every material state change must be persisted before the next operation that can substantially grow context. v0.4.2 changes only the static illustration and README layout; runtime behavior and the five-tool MCP schema remain unchanged.

What remains outside the project

Codex Runway does not identify the active thread, read live counters from process memory, or predict or trigger compaction. It does not estimate a phase on the agent’s behalf, determine semantic checkpoint freshness, schedule agents, or force a client to obey its advisory decision.

The project has no web UI, daemon, polling loop, background service, cloud backend, or host lifecycle hook. Its boundary is narrower: obtain bounded local data for one exact thread, deterministically assess one phase, and safely preserve the minimum state needed to continue.