Pluxx

Turn a raw MCP into a native plugin across Claude Code, Cursor, Codex, and OpenCode.

Import a raw MCP or an existing host-native plugin, keep one maintained source project, and compile native outputs for Claude Code, Cursor, Codex, and OpenCode instead of maintaining four separate plugin codebases.

Pluxx is the authoring, maintenance, and compilation layer for teams that want one source of truth instead of four drifting per-host plugin repos. Start with init, or use pluxx autopilot when you want the one-shot path.

Raw MCP access is usually not enough. Most products still need workflow grouping, stronger instructions, hooks, commands, auth/setup guidance, and honest host-native packaging. Pluxx is the layer that makes that repeatable.

• Start here: docs/start-here.md
• Docs: docs.pluxx.dev
• Website: pluxx.dev

Current Proof

Proof claims are tiered and freshness-checked. See Proof freshness and evidence tiers and the machine-readable proof manifest; April/May host runs remain available as explicitly historical evidence.

If you want the fastest way to see what is already real, start with these:

• Release distribution proof map
  • the current source of truth for what Pluxx ships today, the local build/install/sync/prove lane for the primary fronts, and what still belongs to marketplace or trust-layer work
• Proof and install guide
  • the shortest public path to the current demos plus one-command install paths for the released self-hosted plugin
• Self-hosted core-four proof
  • example/pluxx rebuilt, installed, and verify-install checked across Claude Code, Cursor, Codex, and OpenCode
• Docs Ops core-four proof
  • the flagship example/docs-ops source project rebuilt, installed, verify-install checked, and exercised through read-only inspect/rewrite workflows across the official Claude Code, Cursor, Codex, and OpenCode CLIs
• Docs Ops live Codex walkthrough
  • one maintained docs-ops source project compiled into a real Codex plugin and used against Orchid's live Docsalot MCP
• Docs Ops authenticated publish path
  • the flagship example now separates Orchid's public read-only MCP proof from the private write/publish contract, and the install/runtime gate is mechanically proven
• Exa Research Example
  • a clean-room Exa-style research operator pack built from one maintained source project, with specialist agents, rich brand metadata, real build/install/verify proof across the core four, and live workflow proof in Claude Code, Codex Desktop, Cursor CLI, and OpenCode CLI
• Orchid Accordion before/after rewrite
  • concrete output from the flagship docs workflow example
• Core-four provider docs audit
  • first-party host capability and lifecycle truth for Claude Code, Cursor, Codex, and OpenCode
• Firecrawl connector docs-ingestion proof
  • the first real Firecrawl-backed extraction proof on the fixture set
• Docs-ingestion fixture snapshot
  • keyed local harness rerun with baseline, local, and firecrawl results recorded side by side
• Docs-ingestion scaffold before/after demo
  • a committed Sumble scaffold delta showing what sourced Firecrawl context changes in real generated files

The biggest remaining flagship gap is now a real private publish and rollback run against a safe sandbox authoring target, not basic cross-host workflow proof.

Why Pluxx

Every host has different plugin contracts and different places to express the same intent:

• manifests
• instructions and rules
• hook surfaces
• agents and subagents
• permission and approval controls
• MCP auth wiring
• brand and packaging metadata

Without Pluxx, those details drift across multiple repos. With Pluxx, you keep one source project and compile honest host-native outputs.

For teams that want the shortest path from raw MCP to something usable, pluxx autopilot wraps import, refinement, and build/test flow into one command.

The current product focus is the OSS authoring substrate:

• import
• scaffold
• refine
• lint
• doctor
• eval
• build
• test
• install
• sync

Pluxx is built around an explicit compiler model:

• preserve when a primitive maps cleanly to a host-native surface
• translate when the same intent belongs in a different host surface
• degrade when a host only supports a weaker equivalent
• drop when the host has no truthful native equivalent

That keeps the cross-host story explicit instead of pretending every platform works the same way.

Platform Focus

Pluxx is currently centered on the core four:

• Claude Code
• Cursor
• Codex
• OpenCode

Other targets still exist as generated secondary/beta outputs, but the product and docs are intentionally optimized around the core four. Gemini CLI is one of those beta generator targets today: it is fixture-tested, but it is not in the current release-smoked core-four installer lane.

For the detailed compatibility and verification matrix, see docs/compatibility.md. For the release/distribution/proof lane, see docs/release-distribution-proof-map.md.

Quick Start

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --name my-plugin --yes

cd my-plugin
npx @orchid-labs/pluxx doctor
npx @orchid-labs/pluxx lint
npx @orchid-labs/pluxx build
npx @orchid-labs/pluxx test

One-shot path:

npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --name my-plugin \
  --yes

Common output shape:

dist/
  claude-code/
  cursor/
  codex/
  opencode/

For local stdio MCPs, pass the real executable command, not just the npm package name. The bin name can differ from the package name.

npx @orchid-labs/pluxx init --from-mcp "npx -y -p @acme/mcp acme-mcp" --yes

If the MCP is already installed in one of your agents, discover and import it directly:

npx @orchid-labs/pluxx discover-mcp
npx @orchid-labs/pluxx init --from-installed-mcp codex:acme --yes

Discovery reads Claude Code, Cursor, Codex, and OpenCode config locations and avoids copying literal secret values into the generated project.

For core-four stdio MCPs, Pluxx owns the runtime variable launcher. Pure placeholder values in MCP stdio config stay runtime-inherited, so a globally installed plugin can be reused from different workspaces without baking one workspace's local config into Claude Code, Cursor, Codex, or OpenCode bundles.

Command Cheat Sheet

Need a new project from an MCP?
  pluxx init --from-mcp <source> --yes

Already configured that MCP in Claude, Cursor, Codex, or OpenCode?
  pluxx discover-mcp
  pluxx init --from-installed-mcp <host:name> --yes

Need the all-in-one path?
  pluxx autopilot --from-mcp <source> --runner <runner>

Need deterministic checks?
  pluxx doctor
  pluxx lint
  pluxx eval
  pluxx build
  pluxx test

Need local installs too?
  pluxx build --install
  pluxx test --install
  pluxx verify-install --target codex
  pluxx uninstall

Need release installers or a GitHub release?
  pluxx publish --dry-run
  pluxx publish --github-release --version <x.y.z>
  pluxx publish --npm --version <x.y.z>

Need agent refinement?
  pluxx agent prepare [--website <url>] [--docs <url>]
  pluxx agent run taxonomy --runner <runner>
  pluxx agent run instructions --runner <runner>
  pluxx agent run review --runner <runner>

Need to import an old host-native plugin?
  pluxx migrate <path>

Need to inspect a shipped bundle?
  pluxx doctor --consumer <bundle>

Need deterministic MCP replay?
  pluxx mcp proxy --from-mcp <source> --record tape.json
  pluxx mcp proxy --replay tape.json

  Recordings use a versioned schema and recursively redact common credential
  keys plus source and URL credentials by default. Raw recording is not
  supported. Review tapes before sharing because arbitrary private tool
  content may not look like a credential.

Need to refresh from the MCP later?
  pluxx sync

Full docs tree:

• docs.pluxx.dev/getting-started/command-decision-tree

Core Commands

Pluxx includes more than scaffold generation:

• pluxx eval reports deterministic scaffold contracts separately from an evidence-bearing semantic rubric for tool coverage, routing, taxonomy, examples, arguments, delegation, setup truth, and cross-file consistency; projects can set warning/failure thresholds with eval.warningThreshold and eval.failureThreshold
• pluxx migrate <path> imports an existing host-native plugin into a Pluxx project
• pluxx doctor --consumer <bundle> inspects built or installed plugin bundles from the user side
• pluxx mcp proxy --record and --replay give you strictly validated, default-redacted deterministic MCP tapes for debugging and CI

Authoring Model

Pluxx is intentionally opinionated around a compact cross-host model:

• skills
• instructions
• mcp
• commands
• hooks
• permissions
• userConfig
• agents
• brand and assets
• taxonomy

Pluxx owns the deterministic scaffold, validation, and host compilation layer. Your host coding agent can refine taxonomy, instructions, and examples without breaking the structure.

Install And Runtime Notes

• npm package: @orchid-labs/pluxx
• preferred invocation: npx @orchid-labs/pluxx ...
• global install also works: npm install -g @orchid-labs/pluxx
• check the active global CLI version with: pluxx --version
• upgrade the active global CLI with: pluxx upgrade
• published CLI runtime: Node >=18
• source builds and maintainer workflows also run on Node >=18
• runtime contract: docs/runtime-contract.md

Read Next

• Getting started
• Create a Pluxx plugin
• How it works
• Runtime contract
• Self-hosted core-four proof
• Docs Ops core-four proof
• Proof and install guide
• Docs Ops Codex walkthrough
• Use Pluxx in host agents
• Core primitives
• OSS wedge and trust layer
• Compatibility matrix
• First proof and demo asset pack
• Releasing Pluxx

License

MIT