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.

​
Create A Pluxx Plugin

This is the step-by-step guide for making a real Pluxx plugin from an MCP server. Use this doc when you want the exact sequence for:
  • starting from a raw MCP
  • generating the editable source scaffold
  • refining the scaffold with Claude, Codex, Cursor, or OpenCode
  • validating the result
  • building target bundles
  • installing and testing the plugin in a host app

​
The Mental Model

Pluxx works in two layers:
  1. Core generates the deterministic scaffold.
  2. Agent optionally refines that scaffold semantically.
That means the normal flow is: 
raw MCP
  -> pluxx init
  -> optional agent refinement
  -> pluxx doctor / lint / test
  -> pluxx build
  -> pluxx install
pluxx autopilot wraps that whole flow into one command, but the manual path is often easier to understand and debug.

​
Path A: Manual And Controlled

This is the best default authoring path today.

​
1. Create a real project folder

mkdir -p ~/Desktop/acme-pluxx
cd ~/Desktop/acme-pluxx

​
2. Export auth if the MCP needs it

Bearer auth: 
export ACME_API_KEY='your_real_key'
Custom header auth: 
export ACME_API_KEY='your_real_key'

​
3. Generate the deterministic scaffold

Remote HTTP MCP: 
npx @orchid-labs/pluxx init \
  --from-mcp https://example.com/mcp \
  --yes \
  --name acme \
  --display-name "Acme" \
  --author "Acme" \
  --targets claude-code,cursor,codex,opencode \
  --grouping workflow \
  --hooks safe
Remote bearer auth: 
npx @orchid-labs/pluxx init \
  --from-mcp https://example.com/mcp \
  --yes \
  --name acme \
  --display-name "Acme" \
  --author "Acme" \
  --targets claude-code,cursor,codex,opencode \
  --grouping workflow \
  --hooks safe \
  --auth-env ACME_API_KEY \
  --auth-type bearer
Remote custom header auth: 
npx @orchid-labs/pluxx init \
  --from-mcp https://example.com/mcp \
  --yes \
  --name acme \
  --display-name "Acme" \
  --author "Acme" \
  --targets claude-code,cursor,codex,opencode \
  --grouping workflow \
  --hooks safe \
  --auth-env ACME_API_KEY \
  --auth-type header \
  --auth-header X-API-Key \
  --auth-template '${value}'
Local stdio MCP: 
npx @orchid-labs/pluxx init \
  --from-mcp "npx -y -p @acme/mcp acme-mcp" \
  --yes \
  --name acme \
  --display-name "Acme" \
  --author "Acme" \
  --targets claude-code,cursor,codex,opencode \
  --grouping workflow \
  --hooks safe

​
4. Inspect the scaffold

You should now have a source repo that looks roughly like: 
.
├── .pluxx/
│   ├── mcp.json
│   └── agent/
├── INSTRUCTIONS.md
├── pluxx.config.ts
├── scripts/
└── skills/
Key files:
  • pluxx.config.ts — source of truth for targets, MCP wiring, hooks, rules, and assets
  • INSTRUCTIONS.md — shared instructions that get translated into host outputs
  • skills/*/SKILL.md — workflow surfaces over raw MCP tools
  • .pluxx/mcp.json — scaffold ownership metadata for future syncs

​
5. Prepare the agent context pack

If you want semantic refinement, give Pluxx the product context first: 
npx @orchid-labs/pluxx agent prepare \
  --website https://example.com \
  --docs https://docs.example.com/mcp
If you want to inspect the generated prompts: 
npx @orchid-labs/pluxx agent prompt taxonomy
npx @orchid-labs/pluxx agent prompt instructions
This creates:
  • .pluxx/agent/context.md
  • .pluxx/agent/plan.json
  • .pluxx/agent/taxonomy-prompt.md
  • .pluxx/agent/instructions-prompt.md

​
6. Refine the scaffold with an agent

Run only the pass you need: 
npx @orchid-labs/pluxx agent run taxonomy --runner claude
npx @orchid-labs/pluxx agent run instructions --runner claude
Or use the prompt packs manually inside Claude/Codex/Cursor/OpenCode if you want more control. Rule of thumb:
  • taxonomy pass: rename, merge, or split skills
  • instructions pass: rewrite the shared generated section in INSTRUCTIONS.md
  • review pass: ask for findings before shipping

​
7. Validate the project

npx @orchid-labs/pluxx doctor
npx @orchid-labs/pluxx lint
npx @orchid-labs/pluxx test --target claude-code cursor codex opencode
What each command means:
  • doctor checks runtime health, auth shape, paths, metadata, and trust advisories
  • lint checks frontmatter, platform rules, hook compatibility, and size limits
  • test runs the build + smoke contract across the selected targets

​
8. Build the platform bundles

npx @orchid-labs/pluxx build
This renders the source scaffold into dist/: 
dist/
├── claude-code/
├── cursor/
├── codex/
└── opencode/
Important:
  • the editable source of truth is the root project
  • dist/ is generated output
  • do not hand-edit dist/ unless you are debugging a generator

​
9. Install and test one host first

Claude Code: 
npx @orchid-labs/pluxx install --trust --target claude-code
Cursor: 
npx @orchid-labs/pluxx install --trust --target cursor
Codex: 
npx @orchid-labs/pluxx install --trust --target codex
Then restart the host app and test real requests.

​
Path B: One-Shot Autopilot

Use this when you want Pluxx to do the whole flow for you. Quick mode: 
npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --mode quick \
  --yes
Standard mode: 
npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --mode standard \
  --yes \
  --name acme \
  --display-name "Acme" \
  --author "Acme"
Thorough mode: 
npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --mode thorough \
  --yes \
  --verbose-runner
Mode guidance:
  • quick — fastest first pass
  • standard — best default when the MCP metadata is mixed
  • thorough — use before publishing or when you want review built in

​
OAuth-First MCPs

Some MCPs are one auth shape during import and another at runtime. Example:
  • import may work with bearer or custom-header auth
  • Claude Code or Cursor runtime may need platform-managed OAuth
That means:
  • init / sync can still use --auth-env, --auth-type, and related flags
  • the generated Claude/Cursor plugin can be configured to defer runtime auth to the host platform instead of injecting headers directly
  • in interactive mode, Pluxx can open the provider auth URL, let you paste a hidden token/API key for the current session, and retry the import immediately
  • for browser-interactive remote MCPs that work better through a local proxy, use --oauth-wrapper to introspect through npx -y mcp-remote <url> while keeping the remote URL as the scaffold source
This is the import auth != runtime auth split. When you want a quick real-world check of Pluxx auth import behavior, these MCPs cover the three main paths:
  • Sumble — bearer auth smoke
    • run pluxx init --from-mcp https://mcp.sumble.com --yes --auth-env SUMBLE_API_KEY --auth-type bearer --dry-run --json
    • expected result: scaffold preview succeeds
  • PlayKit — custom-header auth smoke
    • run pluxx init --from-mcp https://mcp.playkit.sh/mcp --yes --auth-env PLAYKIT_API_KEY --auth-type header --auth-header X-API-Key --auth-template '${value}' --dry-run --json
    • expected result: scaffold preview succeeds
  • Linear — OAuth-first/platform-auth guidance smoke
    • run pluxx init --from-mcp https://mcp.linear.app/mcp --yes --dry-run
    • expected result: import stops with explicit OAuth-first guidance and suggests --auth-type platform --runtime-auth platform or a local wrapper/proxy when browser-interactive auth is required
    • wrapper path: pluxx init --from-mcp https://mcp.linear.app/mcp --yes --oauth-wrapper --runtime-auth platform
Keep the automated local OAuth stub in tests for deterministic coverage, and use these servers as manual sanity checks against real MCP behavior.

​
What Pluxx Owns

Pluxx owns:
  • scaffold generation
  • managed sections in generated markdown
  • validation
  • build
  • install
  • sync
You own:
  • custom note blocks
  • pluxx.agent.md
  • any extra docs, assets, or tests you add
If you are new to Pluxx:
  1. use init, not autopilot
  2. inspect the scaffold
  3. run agent prepare --website ... --docs ...
  4. run a taxonomy pass
  5. validate with doctor, lint, and test
  6. build and install one target
That path is usually more understandable than jumping straight to full autopilot.