Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pluxx.dev/llms.txt

Use this file to discover all available pages before exploring further.

Pluxx is the cross-host compiler for MCP-backed and host-native agent plugins. It gives you one maintained source project, normalizes the plugin primitives that drift across hosts, and compiles native outputs for Claude Code, Cursor, Codex, and OpenCode. You can start from a raw MCP with pluxx init --from-mcp ..., import an MCP that is already configured in a local host with pluxx discover-mcp and pluxx init --from-installed-mcp ..., or import an existing host-native plugin with pluxx migrate <path>. For the shortest product, primitive, migration, and codebase map, read Start Here.

​
The source project

You edit one maintained project: 
acme-plugin/
  pluxx.config.ts
  INSTRUCTIONS.md
  skills/
  commands/
  scripts/
  assets/
  .pluxx/mcp.json
  .pluxx/taxonomy.json
Pluxx generates per-host bundles under dist/: 
dist/
  claude-code/
  cursor/
  codex/
  opencode/
The source project is the durable layer. The dist/ directories are generated outputs. Pluxx is opinionated about what “cross-host” means. It does not pretend every platform is identical. Instead, it keeps a canonical model for instructions, skills, commands, agents, hooks, permissions, runtime, and distribution, then compiles each host’s native equivalent as honestly as possible.

​
Deterministic layer vs agent layer

Pluxx has two command layers.

​
Deterministic layer

These commands do not invoke Claude Code, Codex, Cursor, or OpenCode:
  • pluxx init --from-mcp ...
  • pluxx discover-mcp
  • pluxx init --from-installed-mcp ...
  • pluxx sync
  • pluxx doctor
  • pluxx doctor --consumer <bundle>
  • pluxx lint
  • pluxx eval
  • pluxx build
  • pluxx test
  • pluxx install
  • pluxx verify-install
  • pluxx migrate <path>
  • pluxx mcp proxy --record ...
  • pluxx mcp proxy --replay ...
  • pluxx --version
  • pluxx upgrade
This layer handles import, file generation, validation, build, install, installed-state verification, migration, lifecycle ergonomics, and deterministic MCP replay.

​
Agent layer

These commands invoke a host coding agent:
  • pluxx agent prepare
  • pluxx agent prompt ...
  • pluxx agent run ...
  • pluxx autopilot ...
This layer is for semantic refinement:
  • taxonomy cleanup
  • instruction rewriting
  • review passes
Pluxx keeps ownership of structure and packaging. The host agent only works inside the refinement boundary Pluxx prepares.

​
What the main commands are for

​
pluxx discover-mcp and pluxx init --from-installed-mcp ...

Use installed MCP discovery when the MCP already exists in a local host config and you want Pluxx to turn that setup into a maintained source project. Example user story:
I already configured an MCP in Codex or Claude Code. I want to import that server without copying secrets by hand.
discover-mcp reads common Claude Code, Cursor, Codex, and OpenCode MCP config locations. init --from-installed-mcp <host:name> imports the selected server and normalizes auth without copying literal secret values.

​
pluxx verify-install

Use verify-install after local install when you need to know whether the host-visible bundle is actually present and shaped correctly. Example user story:
The build passed, but I need to know whether Codex or Claude Code will see the installed plugin I just generated.
verify-install checks installed paths, stale cache/version problems, installed bundle shape, and consumer-side runtime checks. For installed stdio MCP bundles, it also smoke-launches the installed command instead of passing on file shape alone.

​
pluxx eval

Use eval when the project already builds but you want a quality gate on the scaffold itself. Example user story:
The plugin builds, but I want to know whether the generated taxonomy, instructions, and prompt pack are coherent enough to publish.
eval does not call a model. It checks the scaffold and prompt-pack contract directly.

​
pluxx migrate <path>

Use migrate when you already have a host-native plugin and want to move it into a Pluxx source project instead of rewriting it from scratch. Example user story:
We already have a plugin for one host. We want to move into Pluxx and keep using the same project through Agent Mode, eval, and cross-host build output.
migrate does not call a model.

​
pluxx doctor --consumer <bundle>

Use consumer doctor when you need to inspect a built or installed bundle from the end-user side. Example user story:
The installed plugin looks wrong in my host. I want to inspect the shipped bundle itself, not the source repo.
doctor --consumer does not call a model.

​
pluxx mcp proxy --record / --replay

Use the MCP proxy when you need a reproducible MCP session for CI, demos, or debugging. Example user story:
The live MCP is flaky or expensive. I want to capture one real session and replay it locally.
The proxy records and replays MCP traffic without invoking a model.

​
Typical flow

For a new plugin: 
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp
npx @orchid-labs/pluxx doctor
npx @orchid-labs/pluxx lint
npx @orchid-labs/pluxx eval
npx @orchid-labs/pluxx build
npx @orchid-labs/pluxx test
npx @orchid-labs/pluxx install --target codex
npx @orchid-labs/pluxx verify-install --target codex
If the MCP is already installed in a host: 
npx @orchid-labs/pluxx discover-mcp
npx @orchid-labs/pluxx init --from-installed-mcp codex:acme --yes
If the scaffold needs better naming or instructions: 
npx @orchid-labs/pluxx agent prepare --docs https://docs.example.com/overview
npx @orchid-labs/pluxx agent run taxonomy --runner codex
npx @orchid-labs/pluxx agent run instructions --runner codex
If you want one coordinated flow: 
npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --name acme \
  --display-name "Acme" \
  --author "Acme"
Continue with Getting started.