Mindraw

Mindraw for Codex agents: a project-scoped Codex plugin, skill, MCP server, and local sidebar preview service for opening a Mindraw canvas from the active Codex workspace.

• Repository: https://github.com/17lang/mindraw4agent
• Author and primary maintainer: 张军锋
• Copyright holder: 海南万幸科技有限公司
• License for this repository: MIT
• Companion app requirement: Mindraw >= 1.2.4
• First public target: macOS Apple Silicon

Mindraw App source code is not included in this repository. The Mindraw desktop app, DMG, product name, marks, and binary distribution are governed by separate binary and brand terms from the MIT-licensed agent integration in this repository.

What This Plugin Does

mindraw4agent treats the current Codex workspace as a project root, prepares or inspects MindrawCanvas/, and exposes a project-scoped Mindraw canvas through:

• a Codex skill: mindraw-open-canvas;
• an MCP stdio server: mindraw_mcp;
• a local read-only sidebar preview service;
• an explicit handoff path to the Mindraw desktop app.

The plugin keeps project canvas selection local to the active workspace. It does not read or publish unrelated project folders, does not write .mindraw package internals, and does not implement arbitrary mindraw://...documentId...elementId... target-link entry in this release.

Compatibility

The first public source candidate is scoped to:

• Mindraw App >= 1.2.4;
• macOS on Apple Silicon;
• Codex plugin runtime with local plugin installation support;
• project-local canvas packages under MindrawCanvas/.

Windows, Linux, Intel Mac, App Store distribution, automatic updates, and arbitrary target-link sidebar entry are outside this first release scope.

Install From A Local Clone

Clone the repository when it exists publicly:

git clone https://github.com/17lang/mindraw4agent.git
cd mindraw4agent

Install the local marketplace source and plugin:

./scripts/install-local.sh

The installer uses the current repository directory as a local Codex plugin marketplace source. It does not install or modify the Mindraw desktop app.

Uninstall

./scripts/uninstall-local.sh

This removes the Codex plugin installation and local marketplace entry for mindraw4agent. It does not remove Mindraw App or any project MindrawCanvas/ files.

Doctor

node scripts/doctor.mjs
node scripts/doctor.mjs --json

Doctor checks the current repository layout, Node runtime, Codex CLI availability, platform compatibility, and whether /Applications/Mindraw.app exists. It is read-only.

Use

In Codex, ask:

Open the Mindraw canvas for this project.

Useful explicit prompts:

Open Mindraw in sidebar for this project.
Open Mindraw app for this project.
Create a new Mindraw project canvas.

The default route starts a local sidebar preview service and prints a project-scoped URL:

http://127.0.0.1:<port>/?project=<hash>

If the preferred port is already owned by another Mindraw project service, the launcher skips that stale service and starts a service for the current project on the next available port.

Safety Model

• Project canvases are stored under the active workspace's MindrawCanvas/ directory.
• The plugin never overwrites an existing .mindraw package.
• The plugin never handwrites drawing.excalidraw, manifest.json, .assets/, or other .mindraw package internals.
• First-run creation uses Mindraw App API createBlankPackage when available.
• Sidebar preview uses Mindraw App API previewSnapshot when available.
• Desktop handoff uses Mindraw App API openPackage when available.
• On macOS, supported LaunchServices fallback is limited to launching Mindraw or the exact latest-created current-project package.
• Sidebar API calls include a project identity hash and fail closed on project mismatch.

Important blocker codes include:

• MINDRAW_CANVAS_CREATE_API_REQUIRED
• MINDRAW_PREVIEW_SOURCE_REQUIRED
• MINDRAW_PROJECT_CONTEXT_MISMATCH
• MINDRAW_PROJECT_CANVAS_SCOPE_MISMATCH
• MINDRAW_OPEN_PACKAGE_API_REQUIRED

Development Validation

npm run check
npm run smoke
npm run smoke:http
npm run smoke:lifecycle
npm run smoke:mcp

Optional sidebar smoke requires Playwright:

PLAYWRIGHT_NODE_MODULES=/path/to/node_modules npm run smoke:sidebar

Optional plugin validation when the Codex plugin validator is available:

python3 /path/to/validate_plugin.py plugins/mindraw

Optional SkillSpector safety checks:

skillspector scan plugins/mindraw/skills/mindraw-open-canvas --no-llm --format json --output skillspector-skill.json
skillspector scan plugins/mindraw --no-llm --format json --output skillspector-plugin.json

Release Status

This repository is prepared as a public source candidate. It is not a public release announcement by itself. A public release still requires repository bootstrap, review, QA, binary terms for the Mindraw DMG, release assets, and download smoke evidence.