Codex OpenPencil

The Codex plugin for OpenPencil — create, inspect, and refine editable .op designs from a conversation.
_{One-Prompt Setup • Interactive Canvas • Selection Prompts • Native Rust Engine}

English · 简体中文

Quick Start · Features · Examples · Ecosystem · Install Guide · Validation

_{Design in a Codex conversation, refine on an editable OpenPencil canvas — MŌDE fashion app home and product detail screens.}

One-prompt install and first design

Image generation is enabled by default. When a design needs new image assets, Codex uses its built-in image generation, which may consume your Codex image-generation quota. Say “use stock images only” to skip generation. Unavailable or failed generation falls back to stock search.

Give Codex this:

Install and set up https://github.com/ZSeven-W/codex-openpencil following its INSTALL.md, open an editable canvas, and create a single-page mobile task app.

INSTALL.md guides Codex through prerequisites, installation, runtime verification, opening the canvas, and completing the first design. Setup downloads the complete Rust editor, matching WASM, CanvasKit, fonts, and templates for your OS and CPU, then verifies a real native edit, save, and reopen before registering the plugin.

You need Node.js 22+, Git, and a recent local Codex client with plugin support. No GitHub account, API key, DSH, Rust compiler, separate OpenPencil desktop app, or npm dependency install is needed for this plugin's setup.

Prefer to install manually?

git clone https://github.com/ZSeven-W/codex-openpencil.git
cd codex-openpencil
npm run setup

Keep the checkout in a persistent location. Setup registers it as a local marketplace and installs openpencil@zseven-openpencil. A newly installed plugin may need reconnecting or a new chat to load its tools; the terminal canvas lets Codex complete the first design in the installation chat.

Setup also verifies the tools through Codex's actual plugin loader. It records your current Node executable privately, so a desktop PATH that differs from your terminal does not prevent startup. Use npm run host-check to diagnose plugin loading without opening a chat or editing a design.

See the full compatibility table and dependency guidance. Fresh installation and native edit/save/reopen checks passed on all six OS/CPU builds; validation records distinguish these checks from bare-OS provisioning and embedded host UI verification.

Why Codex OpenPencil

Codex OpenPencil connects Codex to the local Rust OpenPencil engine. The result is a real vector document with editable layers, text, shapes, and layout.

Design with Codex

1. Open a canvas

After installation and any required reconnect, ask:

Open an interactive OpenPencil canvas for this conversation. Create a single-page dashboard for a small design studio.

You can shorten OpenPencil to op / OP, for example “Use OP to design a single-page mobile task manager” or “Use op to edit the selected button”. Chinese prompts such as “用op设计一个单页 APP” work too.

You can also choose + → OpenPencil Canvas → 在 Codex 中打开 (Open in Codex) in the desktop app's right panel. The launcher sends an opening request to the current chat, and Codex opens the canvas in its built-in browser. It confirms the connection after the native editor is ready. If the host does not support this handoff, use 复制打开指令 (Copy opening instruction) and send it in the current chat.

canvas_open_browser starts a separate managed Rust editor and returns its URL for Codex's browser panel. Codex verifies the connection and follows the bundled openpencil-design workflow to create, inspect, preview, and save the design. Use another chat for another document; opening an existing .op file copies it into the session.

The sidebar offers Layers and Slides. Slide cards show live board previews; click a card to navigate to its board. Conversation stays in Codex, so the embedded editor hides its own Agent tab.

2. Select elements and describe a change

Select a card or heading on the canvas, then tell Codex:

Make the selected card dark green and enlarge its heading. Keep the other elements unchanged.

Select elements in the canvas, then describe your edit in the current Codex chat. Codex reads canvas_selection to resolve the active page and node IDs, and confines edits to those subtrees. No copying requests or element IDs is needed.

The canvas footer only shows the selected count and names. Selection context syncs to capable hosts without sending chat messages. Instructions, edit progress and results stay in Codex; there is no second prompt box inside the canvas. Codex verifies the current selection before editing, then inspects the preview and saved design.

Images and generation quota

New photos, illustrations and product imagery use Codex's built-in image_gen by default and may consume image-generation quota. Suitable existing or user-provided images are preserved. Say “不要生图”, “只搜图” or “use stock images only” to use stock search throughout the task.

Before generation, Codex sends a brief chat progress update with the intended assets and possible quota use, then continues without a separate per-call permission question. The host's own required approvals still apply. Unavailable or failed generation uses the native stock-search fallback, with the outcome reported. Uncertain generation calls are not blindly retried, and missing stock results are reported honestly. No generation toggle or provider setup is added to the canvas.

Generated assets are saved in your project and imported into individual editable image nodes. canvas_import_image embeds local PNG/JPEG/WebP bytes, verifies the current page/document version and preserves the node's layout. The workflow then inspects the native preview and verifies the saved .op. The bridge does not invoke image providers or manage your quota: the design skill guides Codex, while the host owns generation access and accounting.

3. Preview, save, and reopen

Check the layout, show me a preview, and save this design as an .op file in my project.

The design workflow checks native layout and the rendered PNG, then reads the saved result back. The panel's Save button flushes pending browser edits before writing. Changes to the source file outside the editor stop replacement; Save As refuses an existing destination. Recovery drafts persist in ~/.codex-openpencil/sessions/.

Design examples

These single-page examples were created with native OpenPencil tools and visually inspected. The dashboard and landing page come from the three-case design test; the task app comes from the v0.3.0 first-use test. All were saved and reopened; these images are native renders of editable documents.

_{FIELDNOTES — a desktop dashboard rendered from an editable .op document, saved and reopened during design testing.}

FORM & FIELD Brand landing page · editorial typography and vector artwork

A little less busy. Mobile task app · native status bar and editable task cards

Advanced setup

First canvas use also installs a missing runtime automatically. Private settings stay in ~/.codex-openpencil/runtime.json; downloaded binaries and machine paths are separate from the plugin package. Failed downloads never activate partial runtimes, and invalid existing configuration is reported explicitly.

To select a complete custom runtime:

npm run configure-runtime -- /absolute/path/to/runtime

To update, inspect the checkout for local changes, pull the published changes, and rerun npm run setup. Reconnect the plugin afterward; merely closing and reopening its canvas tab can retain the old running bridge. Toggle the plugin off/on in plugin management, or restart Codex if necessary. Valid custom runtimes remain selected, and an interrupted managed upgrade retains the previous configuration. See repair and update instructions.

Open Rust OpenPencil, enable MCP in Agent Settings, and run:

npm run doctor
# An intentional isolated endpoint:
npm run doctor -- --port 3100

Before a managed canvas opens, the bridge reads ~/.openpencil/.op-mcp-port and verifies the server identity and matching instance token before forwarding to loopback /mcp. It rejects stale records, unrelated listeners, and legacy REST endpoints. Once managed, all native tools route to the owned daemon, including guarded save_document. Failed writes are never retried automatically.

Canvas controls remain discoverable with the desktop editor offline. Reconnect after starting the editor to refresh the native catalog. Explicit local ports can use OPENPENCIL_MCP_PORT or --port PORT. Existing direct MCP configuration may expose duplicate tools; setup preserves unrelated settings.

Codex opens the editable canvas in its browser panel through canvas_open_browser. The MCP Apps entrypoint is in the right panel's ＋ → OpenPencil Canvas menu. Current Codex versions reject local HTTP iframes. Where the host supports chat messages, the entrypoint asks the current Codex chat to open the same canvas in its built-in browser; it waits for an editor-ready receipt before showing a connection. Otherwise, copy the opening instruction and send it in the current chat. The plugin does not launch your system browser. Hosts that permit the declared local frame origin can embed the canvas. The URL is temporary; closing the plugin stops only its owned Rust process, while recovery drafts remain available.

MCP Apps use the initial host theme and live theme notifications. A launched browser canvas starts with that theme; panels opened without a theme use prefers-color-scheme. Codex's in-app browser supplies its resolved app theme.

Native resource loading, browser interaction and embedded host presentation are separate checks. Codex's current HTTP iframe restriction prevents embedded canvas presentation. All hosts use the current Codex chat for edit instructions. In the browser canvas, click Code panel Generate and say “继续转代码” in chat; automatic prompt delivery is available only in an embedded host that supports messaging. See evidence and remaining checks.

This plugin is distributed through the public GitHub repository and releases. It has not been submitted to OpenAI's public Plugin Directory.

Design → Code

Select a frame, open the right Code panel, choose a framework and click Generate. The panel first shows baseline source for preview, copy and download. An embedded host with MCP Apps messaging hands the captured target to the current Codex chat for a runnable implementation and checks. In a standalone browser, say “continue converting to code” in Codex. Codex returns the primary source to the panel; the full project and supporting files remain in your workspace. A changed design requires a fresh request.

Development and verification

npm run check
npm test
# Native/runtime changes also need the relevant isolated smoke checks:
npm run smoke -- --binary /path/to/openpencil-desktop
npm run canvas-smoke
npm run codegen-smoke
npm run selection-smoke -- --runtime /absolute/path/to/runtime --output /absolute/evidence-dir
npm run mobile-smoke -- --runtime /absolute/path/to/runtime --output /absolute/evidence-dir
# Keep an isolated canvas open for interactive verification:
npm run canvas-smoke -- --hold

The smoke runners use isolated file-backed Rust hosts and ignored artifacts/ outputs. They terminate only their own processes. CI checks packaging and protocol behavior on Linux, macOS, and Windows with Node.js 22/24. A complete compatible runtime is required for native smoke checks.

codex-openpencil/
├── .agents/plugins/          Local marketplace registration
├── plugins/openpencil/      Portable Codex plugin
│   ├── plugin.json          Plugin identity, branding, and capabilities
│   ├── mcp.json             Dependency-free Node.js stdio bridge
│   ├── scripts/             Runtime installation, sessions, and canvas routing
│   ├── ui/                  MCP Apps wrapper and interactive canvas panel
│   └── skills/              Setup diagnostics and design workflow
├── scripts/                 Setup, packaging, and native smoke runners
├── tests/                   Protocol, selection, theme, and installer regressions
├── docs/                    Architecture, validation, and design previews
└── INSTALL.md               One-prompt installation guide for the agent

After plugin edits, reinstall with codex plugin add openpencil@zseven-openpencil and reconnect to refresh the cached package. Read the architecture for process ownership, persistence, and UI contracts.

Ecosystem

Codex OpenPencil brings OpenPencil into Codex. It belongs to the ZSeven-W ecosystem: jian supplies the editor UI, agent-rs runs OpenPencil's built-in agents, and companion tools add terminal workflows, mobile workspaces, memory, delegation and QA.

	Project	What it does
	OpenPencil	The Rust vector design engine behind this plugin — editable documents, layouts, rendering, and native MCP tools.
	DSH OpenPencil	The sibling DeepSeek Harness integration — exact previews, an interactive canvas, and a managed editor inside DSH.
	agent-rs	Rust agent runtime powering OpenPencil's built-in agents, with model providers, tools, permissions and MCP.
	jian	The GPU-Skia Rust UI framework used by OpenPencil.
	Zode	AI coding assistant for the terminal that can drive OpenPencil through MCP.
	Rish App	Your pocket agent — conversations, workspaces and tool execution on your phone, with model choice and operation approvals.
	noema	Local-first agent memory with inspectable files, review queues, lexical recall and MCP.
	DSH Crew	Dispatch work from Codex or Claude Code to DeepSeek Harness agents, with native progress reporting.
	Craft Skills	Research- and evaluation-driven agent skills for image workflows, visual design and asset verification.
	DSH QA	Evidence-based app exploration and replayable QA scenarios across browser, desktop, iOS and Android drivers.

For the standalone OpenPencil editor, see the Homebrew tap for macOS and Scoop bucket for Windows. This Codex plugin installs its matching editor runtime through its own setup flow.

Contributing

Contributions are welcome! Create a branch, run npm run check and npm test, use Conventional Commits, and open a PR against main. Runtime changes also need the relevant native smoke checks. Rust engine changes belong in OpenPencil; this repository owns Codex packaging, the bridge, canvas integration, and workflows.

Community

Join our Discord — ask questions, share designs, and suggest features.

License

MIT — Copyright (c) 2026 ZSeven-W. Third-party attribution is in NOTICE. This is an independently maintained OpenPencil integration, not an OpenAI-authored plugin.