[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-94828":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":11,"openIssues":13,"contributorsCount":12,"subscribersCount":12,"size":12,"stars1d":12,"stars7d":12,"stars30d":12,"stars90d":12,"forks30d":12,"starsTrendScore":12,"compositeScore":14,"rankGlobal":9,"rankLanguage":9,"license":15,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":16,"hasPages":16,"topics":18,"createdAt":9,"pushedAt":9,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":12,"starSnapshotCount":12,"syncStatus":13,"lastSyncTime":32,"discoverSource":33},94828,"codex-image-context-runtime","shixinnt\u002Fcodex-image-context-runtime","shixinnt","A Codex plugin and local MCP runtime for context-bounded image generation and inspection.",null,"JavaScript",106,0,2,40,"Apache License 2.0",false,"main",[19,20,21,22,23,24,25,26,27,28],"codex-plugin","context-management","image-analysis","image-generation","local-first","mcp-server","multimodal","nodejs","storyboard","visual-qa","2026-08-24 04:01:22","[简体中文](README.zh-CN.md)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"plugins\u002Fcodex-image-context-runtime\u002Fassets\u002Flogo.svg\" alt=\"Image Context Runtime logo\" width=\"144\">\n\u003C\u002Fp>\n\n# Image Context Runtime for Codex\n\n**Keep image-heavy Codex workflows responsive, resumable, and context-bounded.**\n\n![A conceptual workstation comparison of image-heavy Codex tasks with and without Image Context Runtime](docs\u002Fassets\u002Fimage-context-runtime-workstation-comparison.png)\n\n*Fictional concept interface—not an actual Codex UI or a measured context, token, speed, or latency benchmark.*\n\nImage 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.\n\nUse it when Codex is:\n\n- creating short-drama character sheets, location concepts, or storyboards;\n- producing image assets for websites and slide decks;\n- organizing image-heavy news, books, screenshots, or research;\n- generating many visual variations or running repeated visual QA.\n\n> **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.\n\nThe 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.\n\n## What it is\n\n**User-facing shape:** a Codex plugin.\n\n**Execution shape:** a bundled local MCP server plus a durable image-job runtime.\n\n~~~text\nCodex skill\n    |\n    v\nbounded MCP tools\n    |\n    v\ndurable local jobs ----> optional OpenAI API\n    |\n    +----> configured-workspace image artifacts\n    |\n    +----> bounded text handoffs, hashes, refs, and Job IDs\n~~~\n\nThe 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.\n\n## Public v0.2 scope\n\n- Text-to-image jobs.\n- Image inspection jobs.\n- Durable status and text handoffs.\n- Idempotent submission.\n- Restart reconciliation and explicit recovery.\n- Offline deterministic mock provider.\n- Optional OpenAI Image API and Responses API provider.\n- Strict public-result budgets with no MCP image, audio, or resource blocks.\n- One authenticated loopback broker shared safely by multiple Codex task bridges.\n- Cursor-based Job history and explicit privacy-minimizing terminal-record compaction.\n\nVideo generation is intentionally out of scope for v0.2.\n\n## Requirements\n\n- Node.js 22 or later.\n- Codex desktop app or Codex CLI with plugin support.\n- No API key for the default mock provider.\n- \u003Ccode>OPENAI_API_KEY\u003C\u002Fcode> only when the OpenAI provider is explicitly enabled.\n\n## Install and configure\n\nClone the tagged release, then run the following commands from its root. The configuration helper runs outside Codex, so a local clone is required:\n\n~~~powershell\ngit clone --depth 1 --branch v0.2.0 https:\u002F\u002Fgithub.com\u002Fshixinnt\u002Fcodex-image-context-runtime.git\ncd codex-image-context-runtime\n~~~\n\n~~~powershell\ncodex plugin marketplace add .\ncodex plugin add codex-image-context-runtime@codex-image-context-runtime\n~~~\n\nThe default provider is offline and deterministic, so installing the plugin cannot accidentally spend API credits.\n\nFor a first installation, choose **one** Provider configuration. For the offline mock:\n\n~~~powershell\nnpm run configure -- --workspace \"C:\\path\\to\\your\\project\" --provider mock\n~~~\n\nWorkspace paths may be absolute or relative to the repository clone's current directory. Custom `--config` and `--runtime-dir` paths must be absolute.\n\nOr, for the optional OpenAI Provider, make the key available to the Codex process and configure OpenAI from the start:\n\n~~~powershell\n$env:OPENAI_API_KEY = \"set-this-outside-the-repository\"\nnpm run configure -- --workspace \"C:\\path\\to\\your\\project\" --provider openai\n~~~\n\nThe configuration file stores paths and model choices only. It never stores the API key.\n\nThe PowerShell environment assignment applies only to that shell and child processes. Launch Codex CLI from that shell, or use your operating system's environment\u002Fcredential workflow before starting the desktop app. Restart Codex after configuration or credential changes.\n\nTo 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:\n\n~~~powershell\nnpm run configure -- --workspace \"C:\\path\\to\\your\\project\" --provider openai --runtime-dir \"C:\\path\\to\\image-runtime-openai\" --force\n~~~\n\nCheck the installation without exposing local paths or credentials:\n\n~~~powershell\nnpm run doctor\nnpm run doctor -- --json\n~~~\n\nPreview privacy-minimizing Job-record compaction without changing data:\n\n~~~powershell\nnpm run compact -- --older-than-days 30 --limit 25 --json\n~~~\n\nTo apply a bounded batch, stop Codex tasks using the configuration, wait for the Broker to exit, review the dry run, then add `--apply`. Compaction keeps retired idempotency tombstones and compact artifact receipts; it does not delete workspace images or guarantee secure erasure.\n\nFor Bash-compatible shells, export the key before starting Codex:\n\n~~~sh\nexport OPENAI_API_KEY=\"set-this-outside-the-repository\"\nnpm run configure -- --workspace \"\u002Fpath\u002Fto\u002Fyour\u002Fproject\" --provider openai\n~~~\n\n### Update an existing installation\n\nStop active image jobs, update the clone to the new tag, then refresh the installed plugin cache:\n\n~~~powershell\ngit fetch --tags\ngit checkout v0.2.0\ncodex plugin remove codex-image-context-runtime@codex-image-context-runtime\ncodex plugin add codex-image-context-runtime@codex-image-context-runtime\n~~~\n\nConfiguration and Runtime data are outside the clone and are not deleted by reinstalling the plugin. Restart Codex after the update.\n\n## Example prompts\n\n~~~text\nUse Image Context Runtime to generate one 1024x1024 storyboard frame.\nKeep the image bytes outside this task and return the Job ID.\n\nInspect images\u002Fframe-001.png for composition, continuity, and obvious text defects.\nReturn only the bounded inspection handoff.\n~~~\n\nThe 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.\n\n## Providers\n\n### Mock provider\n\n- Default.\n- Offline and deterministic.\n- Creates a synthetic PNG for generation jobs.\n- Returns metadata-oriented inspection text.\n- Validates transport and persistence behavior, not visual quality.\n\n### OpenAI provider\n\n- Opt-in only.\n- Uses \u003Ccode>gpt-image-2\u003C\u002Fcode> by default for image generation.\n- Uses \u003Ccode>gpt-5.6\u003C\u002Fcode> by default for image inspection.\n- Model names can be overridden in configuration.\n- Media sent to the API is subject to the applicable service terms, pricing, and data controls.\n\nThis is an independent open-source project. It is not affiliated with or endorsed by OpenAI.\n\n## Privacy boundary\n\nPublic MCP results:\n\n- never contain provider-returned image bytes;\n- never contain data URLs or base64 media;\n- never contain API keys or raw provider responses;\n- use relative artifact and handoff references;\n- are capped by a UTF-8 byte budget.\n\nThe runtime can still send an image to an explicitly enabled remote provider for inspection. Local runtime ownership is not the same as offline processing.\n\nThe local job records persist prompts, inspection questions, relative references, and provider state. Protect the configured Runtime directory as project data.\n\n## v0.2 shared Runtime boundary\n\nEach Codex task receives a thin stdio MCP bridge. Bridges using the same fixed configuration authenticate to one IPv4-loopback broker, which owns the only durable Runtime worker, Provider semaphore, idempotency index, and output reservations. Concurrent bridge startup converges on one broker owner instead of treating another task's live Job as interrupted.\n\nThe broker token and configuration hash are stored in an owner-only descriptor in the Runtime directory. Authentication time, per-client in-flight work, response buffering, and stdio-to-socket pressure are bounded. The broker listens only on \u003Ccode>127.0.0.1\u003C\u002Fcode>; it is not a remote service or a sandbox against another process running as the same operating-system user.\n\nAfter the last bridge disconnects and active Jobs settle, the broker shuts down after a bounded idle interval. Forced interruption after Provider dispatch remains ambiguous and becomes \u003Ccode>needs_review\u003C\u002Fcode>; it is never automatically repeated.\n\nSee [Architecture](docs\u002Farchitecture.md), [Tool reference](docs\u002Ftool-reference.md), [v0.2 claims](docs\u002Fclaims-v0.2.md), [Benchmark methodology](docs\u002Fbenchmark-methodology.md), [v0.2.0 validation receipt](docs\u002Fvalidation-v0.2.0.md), [Troubleshooting](docs\u002Ftroubleshooting.md), [Privacy](PRIVACY.md), [Support](SUPPORT.md), [Terms](TERMS.md), [Roadmap](ROADMAP.md), [Security](SECURITY.md), [Third-party services](THIRD_PARTY_SERVICES.md), and [Contributing](CONTRIBUTING.md).\n\n## Synthetic payload benchmark\n\nThe included benchmark compares:\n\n1. a deliberately naive MCP result that inlines synthetic image bytes; and\n2. this runtime's bounded ref\u002Fhash\u002FJob-ID result shape.\n\nRun it with:\n\n~~~powershell\nnpm run benchmark\n~~~\n\nThis is a deterministic serialized-payload proxy. It is **not** a measurement of Codex tokens, latency, memory usage, or native image handling.\n\nThe checked-in v0.1 scenario models 20 jobs with 1 MiB synthetic images:\n\n| Transport | Serialized MCP result bytes | Largest result |\n|---|---:|---:|\n| Naive inline-image baseline | 27,990,140 | 1,398,617 |\n| Reference-only candidate | 27,060 | 739 |\n\nThat is a 99.903% reduction for this synthetic result-payload comparison only. See the methodology and reproducible JSON report before quoting it.\n\n## Development\n\n~~~powershell\nnpm test\nnpm run benchmark:verify\nnpm run check:privacy\n~~~\n\nAll default tests are offline and make zero real provider calls.\n\n## Status\n\nv0.2.0 is an experimental public release. Review the threat model and data path before enabling a paid provider in a sensitive project.\n\nIf you try it in a real image-heavy workflow, open a GitHub Discussion with your operating system, Codex surface\u002Fversion, approximate image workload, and whether a fresh task remained responsive. Report reproducible defects with the issue templates; never upload private Runtime state.\n\n## License\n\nApache License 2.0. This independent project is not affiliated with or endorsed by OpenAI.\n","这是一个为 Codex 设计的本地化多模态上下文运行时插件，用于在图像生成与分析任务中实现上下文边界控制、作业持久化和资源隔离。核心功能包括：支持文本生成图像（T2I）与图像理解（VQA）两类作业；通过本地 MCP 服务管理作业状态，仅向 Codex 返回文本摘要、哈希值、相对路径引用及 Job ID；内置离线模拟提供者，可选对接 OpenAI 图像 API；保障媒体文件不越界传输，严格限制响应内容尺寸。适用于需批量生成角色设定图、故事板、网页\u002F演示文稿配图，或组织新闻\u002F研究类图像素材等对上下文体积敏感的本地化图像工作流。","2026-08-16 02:30:13","CREATED_QUERY"]