> ## 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.

# What Pluxx Is

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](/overview/start-here).

## The source project

You edit one maintained project:

```text theme={null}
acme-plugin/
  pluxx.config.ts
  INSTRUCTIONS.md
  skills/
  commands/
  scripts/
  assets/
  .pluxx/mcp.json
  .pluxx/taxonomy.json
```

Pluxx generates per-host bundles under `dist/`:

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

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

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

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

```bash theme={null}
npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --name acme \
  --display-name "Acme" \
  --author "Acme"
```

Continue with [Getting started](/getting-started/getting-started).