简体中文

Image Context Runtime for Codex

Keep image-heavy Codex workflows responsive, resumable, and context-bounded.

Fictional concept interface—not an actual Codex UI or a measured context, token, speed, or latency benchmark.

Image Context Runtime for Codex is an experimental open-source Codex plugin backed by a durable local MCP runtime. It runs image generation and inspection as persisted jobs, keeps provider-returned media bytes behind the public MCP boundary, and returns only bounded text results, hashes, relative references, and Job IDs.

Use it when Codex is:

• creating short-drama character sheets, location concepts, or storyboards;
• producing image assets for websites and slide decks;
• organizing image-heavy news, books, screenshots, or research;
• generating many visual variations or running repeated visual QA.

Important: This project reduces one source of context pressure. It does not claim that Codex can never slow down, that images use zero tokens, or that explicitly opening an image adds no visual context.

The plugin does not patch or intercept Codex's built-in image features or other image tools. The bounded boundary applies only when Codex uses this plugin's MCP tools and follows its bundled skill.

What it is

User-facing shape: a Codex plugin.

Execution shape: a bundled local MCP server plus a durable image-job runtime.

Codex skill
    |
    v
bounded MCP tools
    |
    v
durable local jobs ----> optional OpenAI API
    |
    +----> configured-workspace image artifacts
    |
    +----> bounded text handoffs, hashes, refs, and Job IDs

The plugin is the installable workflow. MCP is the tool boundary. The Runtime owns Job state, controls media transfer, and writes generated artifacts only to configured workspace-relative paths.

Public v0.1 scope

• Text-to-image jobs.
• Image inspection jobs.
• Durable status and text handoffs.
• Idempotent submission.
• Restart reconciliation and explicit recovery.
• Offline deterministic mock provider.
• Optional OpenAI Image API and Responses API provider.
• Strict public-result budgets with no MCP image, audio, or resource blocks.

Video generation is intentionally out of scope for v0.1.

Requirements

• Node.js 22 or later.
• Codex desktop app or Codex CLI with plugin support.
• No API key for the default mock provider.
• OPENAI_API_KEY only when the OpenAI provider is explicitly enabled.

Install and configure

Clone the tagged release, then run the following commands from its root. The configuration helper runs outside Codex, so a local clone is required:

git clone --depth 1 --branch v0.1.1 https://github.com/shixinnt/codex-image-context-runtime.git
cd codex-image-context-runtime

codex plugin marketplace add .
codex plugin add codex-image-context-runtime@codex-image-context-runtime

The default provider is offline and deterministic, so installing the plugin cannot accidentally spend API credits.

For a first installation, choose one Provider configuration. For the offline mock:

npm run configure -- --workspace "C:\path\to\your\project" --provider mock

Workspace paths may be absolute or relative to the repository clone's current directory. Custom --config and --runtime-dir paths must be absolute.

Or, for the optional OpenAI Provider, make the key available to the Codex process and configure OpenAI from the start:

$env:OPENAI_API_KEY = "set-this-outside-the-repository"
npm run configure -- --workspace "C:\path\to\your\project" --provider openai

The configuration file stores paths and model choices only. It never stores the API key.

The PowerShell environment assignment applies only to that shell and child processes. Launch Codex CLI from that shell, or use your operating system's environment/credential workflow before starting the desktop app. Restart Codex after configuration or credential changes.

To switch an existing mock setup to OpenAI, first stop the active worker, then replace the config and use a new Runtime directory so in-flight state is not mixed:

npm run configure -- --workspace "C:\path\to\your\project" --provider openai --runtime-dir "C:\path\to\image-runtime-openai" --force

Check the installation without exposing local paths or credentials:

npm run doctor
npm run doctor -- --json

For Bash-compatible shells, export the key before starting Codex:

export OPENAI_API_KEY="set-this-outside-the-repository"
npm run configure -- --workspace "/path/to/your/project" --provider openai

Update an existing installation

Stop active image jobs, update the clone to the new tag, then refresh the installed plugin cache:

git fetch --tags
git checkout v0.1.1
codex plugin remove codex-image-context-runtime@codex-image-context-runtime
codex plugin add codex-image-context-runtime@codex-image-context-runtime

Configuration and Runtime data are outside the clone and are not deleted by reinstalling the plugin. Restart Codex after the update.

Example prompts

Use Image Context Runtime to generate one 1024x1024 storyboard frame.
Keep the image bytes outside this task and return the Job ID.

Inspect images/frame-001.png for composition, continuity, and obvious text defects.
Return only the bounded inspection handoff.

The bundled skill instructs Codex to submit the job, poll by Job ID, and retrieve the compact handoff instead of asking the MCP server to return pixels.

Providers

Mock provider

• Default.
• Offline and deterministic.
• Creates a synthetic PNG for generation jobs.
• Returns metadata-oriented inspection text.
• Validates transport and persistence behavior, not visual quality.

OpenAI provider

• Opt-in only.
• Uses gpt-image-2 by default for image generation.
• Uses gpt-5.6 by default for image inspection.
• Model names can be overridden in configuration.
• Media sent to the API is subject to the applicable service terms, pricing, and data controls.

This is an independent open-source project. It is not affiliated with or endorsed by OpenAI.

Privacy boundary

Public MCP results:

• never contain provider-returned image bytes;
• never contain data URLs or base64 media;
• never contain API keys or raw provider responses;
• use relative artifact and handoff references;
• are capped by a UTF-8 byte budget.

The runtime can still send an image to an explicitly enabled remote provider for inspection. Local runtime ownership is not the same as offline processing.

The local job records persist prompts, inspection questions, relative references, and provider state. Protect the configured Runtime directory as project data.

v0.1 concurrency boundary

One Runtime directory has exactly one active MCP worker. A second process targeting the same directory fails closed with runtime_already_running instead of reconciling or redispatching another live worker's jobs. A dead owner's stale PID lock is recovered on the next start.

If a process is forcibly killed during the millisecond-scale lock-takeover critical section, an empty runtime.lock.guard directory can remain. Verify that no worker is running before removing that guard manually; the Runtime never guesses that an acquisition guard is stale.

For simultaneous Codex tasks, use distinct configuration and Runtime directories. A shared multi-client broker is a later roadmap item; v0.1 does not pretend that process-local coordination is cross-session coordination.

See Architecture, Tool reference, Claims, Benchmark methodology, v0.1.1 validation receipt, Troubleshooting, Privacy, Support, Terms, Roadmap, Security, Third-party services, and Contributing.

Synthetic payload benchmark

The included benchmark compares:

1. a deliberately naive MCP result that inlines synthetic image bytes; and
2. this runtime's bounded ref/hash/Job-ID result shape.

Run it with:

npm run benchmark

This is a deterministic serialized-payload proxy. It is not a measurement of Codex tokens, latency, memory usage, or native image handling.

The checked-in v0.1 scenario models 20 jobs with 1 MiB synthetic images:

That is a 99.903% reduction for this synthetic result-payload comparison only. See the methodology and reproducible JSON report before quoting it.

Development

npm test
npm run benchmark:verify
npm run check:privacy

All default tests are offline and make zero real provider calls.

Status

v0.1.1 is an experimental public baseline. Review the threat model and data path before enabling a paid provider in a sensitive project.

If you try it in a real image-heavy workflow, open a GitHub Discussion with your operating system, Codex surface/version, approximate image workload, and whether a fresh task remained responsive. Report reproducible defects with the issue templates; never upload private Runtime state.

License

Apache License 2.0. This independent project is not affiliated with or endorsed by OpenAI.