> ## 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 host agents

# 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](/getting-started/create-a-pluxx-plugin), which is the CLI-first authoring walkthrough.

The self-hosting reference project for this flow now lives at [example/pluxx](/examples/self-hosting-pluxx).

## Product Split

The meta workflow is:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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](https://developers.openai.com/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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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

## Recommended Prompts

### Import only

```text theme={null}
Use Pluxx to scaffold a plugin from this MCP and validate the first pass.
```

### Import + product shaping

```text theme={null}
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

```text theme={null}
Use Pluxx to review this scaffold critically and tell me what is still weak before we publish it.
```

### Sync existing project

```text theme={null}
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:

```text theme={null}
Use Pluxx to do the standard import -> refine -> verify loop for this MCP.
```

## Related Docs

* [Create a Pluxx plugin](/getting-started/create-a-pluxx-plugin)
* [Practical handbook](/getting-started/practical-handbook)
* [Getting started](/getting-started/getting-started)
* [Agent Mode](/how-it-works/agent-mode)