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.

This page defines how the Pluxx authoring model should map across the core four hosts:
  • Claude Code
  • Cursor
  • Codex
  • OpenCode
The goal is not to copy one host’s files into the others. The goal is to normalize author intent once, then compile it into the best native surface each host exposes.

​
Compiler Buckets

These are the eight buckets Pluxx should compile from:
BucketIncludes
instructionsshared host guidance and routing rules
skillsreusable workflows plus taxonomy-derived workflow metadata
commandsexplicit slash-command style entrypoints
agentsspecialist or delegated execution surfaces
hooksdeterministic lifecycle automation
permissionsportable allow / ask / deny intent
runtimeMCP, runtime auth, local runtimes, passthrough dirs, helper scripts
distributionuser config, brand, packaging, install, publish, and install-surface metadata
taxonomy remains an internal compiler input. It drives how skills, commands, instructions, and agents are rendered, but it is not itself a host-facing extension primitive.

​
Canonical Shape

interface PluxxPrimitiveModel {
  instructions?: InstructionsSpec
  skills?: SkillSpec[]
  commands?: CommandSpec[]
  agents?: AgentSpec[]
  hooks?: HookSpec[]
  permissions?: PermissionSpec[]
  runtime?: {
    mcp?: McpSpec
    auth?: RuntimeAuthSpec[]
    passthrough?: string[]
    scripts?: string[]
    assets?: string[]
  }
  distribution?: {
    userConfig?: UserConfigSpec[]
    brand?: BrandSpec
    install?: InstallSurfaceSpec
    publish?: PublishSurfaceSpec
  }
  taxonomy: TaxonomySpec
}
This is a compiler-facing model. It is not a claim that each host has one identical manifest or one identical config file.

​
Mapping Rules

BucketClaude CodeCursorCodexOpenCodePluxx mapping rule
instructionsCLAUDE.md plus plugin-level guidance surfacesrules/ plus AGENTS.md supportAGENTS.md and AGENTS.override.mdconfig-driven instruction filesKeep one instruction source of truth and compile it into the host-native guidance surface rather than duplicating prose by hand.
skillsskills/<skill>/SKILL.mdskills/<skill>/SKILL.md with a narrower documented frontmatter setskills/<skill>/SKILL.md, optionally bundled through pluginsskills/<skill>/SKILL.mdSkills stay the semantic center. Preserve shared metadata and strip or downgrade host-only frontmatter during migration and build.
commandsnative commands/ markdown command filesnative commands/ plugin filesno documented plugin-packaged command directory todaynative command system through markdown or JSON command definitionsTreat commands as first-class where the host exposes them. For Codex, degrade commands into skills and instruction routing instead of pretending parity exists.
agentsplugin agents/ with rich frontmatter and isolation settingsplugin agents plus Cursor subagentscustom agents in .codex/agents/*.toml and subagent workflowsprimary agents and subagents with model and permission configTreat agents as specialist execution surfaces. Compile one specialist concept into each host’s native agent or subagent format, even when the storage location differs.
hookshooks/hooks.json or inline plugin manifest hookshooks/hooks.json plus project and user hook locations.codex/hooks.json or ~/.codex/hooks.json, guarded by the codex_hooks feature flagJS or TS plugin event handlersNormalize hook intent and compile per host. Do not assume event names or return contracts are portable 1:1.
permissionstool scoping and approval controls live in Claude-specific agent, hook, and runtime surfaceshook allow or deny decisions, CLI permission config, and subagent tool accessapprovals, sandbox policy, hook matchers, and custom-agent configfirst-class permission config plus per-agent overridesKeep allow / ask / deny as the canonical authoring model. When one host lacks a per-skill field, move the policy to its native agent, hook, or runtime control plane.
runtime.mcp.json or inline MCP config, plus plugin support filesmcp.json, plugin support files, and host config integration.mcp.json in plugins plus active MCP state in config.toml, with optional .app.jsonconfig-driven MCP and JS plugin runtimeRuntime owns MCP, auth, env wiring, helper code, local runtimes, and passthrough dirs. Compile into bundle-local files when possible and external host config when required.
distribution.claude-plugin/plugin.json, install scopes, user configuration, plugin cache, install command surfaces.cursor-plugin/plugin.json, marketplace metadata, publish surface, local install path.codex-plugin/plugin.json, marketplace catalogs, cache install path, interface metadatanpm or local JS plugin distribution rather than one shared manifestDistribution owns userConfig, brand, legal links, icons, screenshots, install metadata, and publish metadata. Emit rich manifest fields where supported and install shims where they are not.

​
Practical Consequences

This matrix implies a few hard rules for Pluxx:
  1. Migration should be semantic, not syntactic. Import the source host’s intent, not its exact file format.
  2. Skills are the stable workflow layer. Commands and agents should compile from the same workflow model rather than forking meaning.
  3. Permissions are portable intent, not portable syntax. A Claude-only field such as allowed-tools should become a host-agnostic policy that Pluxx re-expresses for Cursor, Codex, and OpenCode in their native control planes.
  4. Codex is not command-parity with Claude, Cursor, or OpenCode today. That is a translation problem for Pluxx, not a reason to leak host differences into the authoring model.
  5. OpenCode is code-first for plugins. Hooks, runtime extensions, and some distribution behavior need real JS or TS generation rather than manifest-only generation.

​
Official Docs Basis

​
Claude Code

​
Cursor

​
Codex

​
OpenCode