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.

​
Use Pluxx In Claude, Codex, Cursor, And OpenCode

This is the operator guide for using Pluxx inside a host coding agent. Use this doc when you want the meta workflow:
  • install or enable Pluxx in your host
  • ask Claude, Codex, Cursor, or OpenCode to use Pluxx for you
  • scaffold a plugin from an MCP
  • refine the scaffold
  • review it
  • sync it later
This is different from Create a Pluxx plugin, which is the CLI-first authoring walkthrough. The self-hosting reference project for this flow now lives at example/pluxx.

​
Product Split

The meta workflow is: 
you in Claude/Codex/Cursor/OpenCode
  -> ask the host agent to use Pluxx
  -> Pluxx CLI does the deterministic work
  -> the host agent helps with refinement and review
Pluxx has two layers:
  • deterministic project commands
  • optional agent-driven refinement
So the host agent is the operator. Pluxx is the authoring system underneath it. What the host agent is good for:
  • improving taxonomy
  • rewriting instructions
  • running a review pass before ship
What Pluxx still owns directly:
  • MCP import
  • scaffold generation
  • lint, eval, build, and test
  • install and sync
  • platform packaging

​
Should the Pluxx plugin bundle the CLI?

No. The cleaner design is:
  • Pluxx CLI as the execution engine
  • thin host-native Pluxx plugins as the UX layer
That keeps one source of execution truth, smaller host bundles, clearer review surfaces, and better parity across Claude Code, Cursor, Codex, and OpenCode. The plugin should mainly provide:
  • skills, commands, and agents that route users into the right Pluxx workflow
  • polished metadata, prompts, and examples
  • a better in-host entrypoint for the deterministic CLI underneath

​
The Main Pluxx Workflows

The recommended Pluxx skill pack is organized around eight jobs:
  • pluxx-import-mcp
  • pluxx-migrate-plugin
  • pluxx-validate-scaffold
  • pluxx-refine-taxonomy
  • pluxx-rewrite-instructions
  • pluxx-review-scaffold
  • pluxx-build-install
  • pluxx-sync-mcp
Those correspond to:
  1. import an MCP and scaffold a plugin
  2. migrate an existing host-native plugin into Pluxx
  3. validate the scaffold deterministically
  4. improve the skill taxonomy
  5. rewrite the shared instructions
  6. review the scaffold critically
  7. build native outputs and optionally install them
  8. refresh the scaffold when the MCP changes
The self-hosting plugin also exposes matching explicit commands in hosts that support plugin commands:
  • /pluxx:import-mcp
  • /pluxx:migrate-plugin
  • /pluxx:validate-scaffold
  • /pluxx:refine-taxonomy
  • /pluxx:rewrite-instructions
  • /pluxx:review-scaffold
  • /pluxx:build-install
  • /pluxx:sync-mcp
Use commands when you want a direct host-native entrypoint in Claude Code, Cursor, or OpenCode. In Codex, use @pluxx and the skill list instead; / is reserved for native Codex commands. Use skills when you want the host agent to choose the right Pluxx workflow automatically.

​
What To Ask The Host Agent To Do

Think in terms of the job you want the host agent to perform:
  • “Use Pluxx to scaffold this MCP”
  • “Use Pluxx to improve the taxonomy”
  • “Use Pluxx to rewrite the instructions”
  • “Use Pluxx to review this scaffold”
  • “Use Pluxx to sync this plugin from its MCP again”
You do not need to memorize the exact CLI every time if the host agent already has Pluxx available.

​
Core Usage Patterns

​
1. Import a new MCP

Good prompt: 
Use Pluxx to scaffold a plugin from https://example.com/mcp.
Do a deterministic first pass, show me what gets generated, then run doctor, lint, and test.
If you already trust the MCP and want the scaffold to preapprove all of its tools up front: 
Use Pluxx to scaffold a plugin from https://example.com/mcp.
Preapprove all tools from that MCP in the generated scaffold, then run the normal validation pass.
If auth is needed: 
Use Pluxx to scaffold a plugin from https://example.com/mcp.
This MCP uses header auth via ACME_API_KEY and X-API-Key.
Do a dry-run first, then do the real import if it looks correct.
If you already know the desired project folder: 
Use Pluxx to scaffold this MCP into ./acme-plugin.
Use workflow grouping, safe hooks, and target Claude Code, Cursor, Codex, and OpenCode.

​
2. Refine the taxonomy

Good prompt: 
Use Pluxx to refine the taxonomy in this scaffold.
Refresh the agent context with the product website and docs first, then run the taxonomy pass and re-test the project.
If you want stronger product shaping: 
Use Pluxx to improve this scaffold's taxonomy.
The current skills are too lexical and fragmented.
Favor product-shaped workflows over one skill per tool.

​
3. Rewrite the instructions

Good prompt: 
Use Pluxx to rewrite the generated section in INSTRUCTIONS.md.
Keep the custom block intact, make the setup/auth boundaries clear, and keep the tone operational.

​
4. Review the scaffold

Good prompt: 
Use Pluxx to review this scaffold critically before shipping.
Find semantic weaknesses in the taxonomy, setup guidance, examples, and product framing.
Findings first.

​
5. Sync later

Good prompt: 
Use Pluxx to sync this project from its MCP source again.
Preview first, then explain what changed, what was preserved, and whether taxonomy or instructions should be rerun.

​
The Best Inputs To Give The Host Agent

Pluxx works much better when you hand the host agent the real product context up front. When possible, include:
  • MCP URL or local stdio command
  • auth shape
  • website URL
  • docs URL
  • plugin name
  • display name
  • desired targets
  • whether you want a dry-run first
Example: 
Use Pluxx to scaffold a plugin from https://mcp.sumble.com.
Use Claude Code, Cursor, Codex, and OpenCode as targets.
Website: https://sumble.com
Docs: https://docs.sumble.com/api/mcp
Do a deterministic import first, then prepare the agent context pack.

​
What The Host Agent Will Usually Do

Under the hood, the host agent should follow something close to this:
  1. run pluxx init --from-mcp ...
  2. inspect the scaffold
  3. run pluxx agent prepare --website ... --docs ...
  4. optionally run taxonomy/instructions/review passes
  5. run pluxx doctor
  6. run pluxx lint
  7. run pluxx test
For local host proof, the stronger deterministic finish is:
  1. run pluxx test --install
  2. reload any host app that was already open
  3. if the installed plugin still looks wrong, run pluxx doctor --consumer <installed-path>
  4. run pluxx build
  5. optionally run pluxx install --target ...
That is the right sequence whether the host is Claude, Codex, Cursor, or OpenCode.

​
What Good Operator Behavior Looks Like

The host agent should:
  • start with deterministic import and validation
  • only move into taxonomy or instructions passes when the scaffold needs semantic cleanup
  • keep edits inside Pluxx-managed sections
  • rerun validation after semantic changes
The host agent should not:
  • treat every import as an excuse for a full rewrite
  • change auth wiring casually
  • edit generated dist/ output directly
  • skip validation after major taxonomy or instructions changes

​
Host-Specific Guidance

​
Claude Code

Use Pluxx in Claude Code when you want:
  • interactive scaffold iteration
  • fast review/refine loops
  • native runtime testing of generated Claude plugins
Good prompt: 
Use Pluxx to scaffold this MCP, then refine the taxonomy and instructions before building and installing the Claude target.

​
Codex

Use Pluxx in Codex when you want:
  • CLI-first deterministic generation
  • stricter review behavior
  • strong local coding-agent workflows around the generated scaffold
  • explicit plugin invocation via @pluxx rather than plugin slash commands
Good prompt: 
Use Pluxx to import this MCP, validate the first pass, then review what still looks weak before we install anything.
This matches the general Codex workflow model described in the official OpenAI Codex use-cases docs: explicit tasks, concrete context, and repeatable operator flows. See Codex use cases.

​
Cursor

Use Pluxx in Cursor when you want:
  • plugin authoring in a more IDE-native environment
  • Cursor-specific validation and runtime testing
  • headless taxonomy/instructions passes via the Cursor agent CLI when needed
Good prompt: 
Use Pluxx to scaffold this MCP, then make the plugin feel natural in Cursor and check the generated Cursor output before we ship it.

​
OpenCode

Use Pluxx in OpenCode when you want:
  • OpenCode-specific plugin wrapper generation
  • attachable headless runs for refinement
  • explicit command and hook mapping into OpenCode’s plugin model
Good prompt: 
Use Pluxx to generate this plugin, then run the refinement passes through OpenCode and verify the final wrapper output.

​
How To Ask For The Right Level Of Automation

​
Deterministic first

Use this when you want control: 
Use Pluxx, but keep the first pass deterministic.
Do not jump into semantic rewrites until the scaffold builds and tests.

​
Full autopilot

Use this when you want convenience: 
Use Pluxx autopilot for this MCP.
Run the standard mode, summarize what changed, and only stream runner logs if something fails.

​
Review before mutation

Use this when you want caution: 
Use Pluxx to dry-run the import first and show me the plan before writing files.

​
What “Good” Looks Like

A good Pluxx-assisted run should leave you with:
  • a valid pluxx.config.ts
  • a sensible INSTRUCTIONS.md
  • product-shaped skills/*/SKILL.md
  • passing doctor, lint, and test
  • built dist/ outputs for the requested targets
  • optionally an installed local plugin for one host

​
Import only

Use Pluxx to scaffold a plugin from this MCP and validate the first pass.

​
Import + product shaping

Use Pluxx to scaffold this MCP, then improve the taxonomy and instructions so the plugin feels product-shaped instead of tool-shaped.

​
Review before shipping

Use Pluxx to review this scaffold critically and tell me what is still weak before we publish it.

​
Sync existing project

Use Pluxx to sync this scaffold from its MCP source again and explain what changed.

​
What To Document For Your Team

If your team uses Pluxx inside host agents regularly, capture these four things:
  • which MCPs you wrap
  • what auth shape each one uses during import
  • whether runtime auth is platform-managed or plugin-managed
  • which prompts/workflows you want people to use by default
That gives your team a stable way to say: 
Use Pluxx to do the standard import -> refine -> verify loop for this MCP.